docs: selectors

i18n/ru/docusaurus-plugin-content-docs/current/quickstart/index.mdx

@@ -4,36 +4,59 @@ sidebar_position: 1
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
+import Admonition from "@theme/Admonition";
 
-# Установка {#install}
+# Установка и настройка
 
-Запустите установщик testplane с помощью `npm`.
+## Системные требования
+
+Чтобы начать работу с testplane, установите `Node.js` версии 18.0 и выше.
+
+## Установка {#install}
+
+Для запуска установщика testplane, с помощью `npm` выполните следующую команду:
 
 ```bash
 npm init testplane@latest YOUR_PROJECT_PATH
 ```
 
-Если вы не хотите использовать дефолты при инициализации проекта, а настроить его с помощью визарда, укажите опцию `-v`.
+Чтобы настроить проект, а не использовать дефолты при его инициализации, укажите опцию `-v`.
+
+После выполнения команды установки, в директории проекта появится следующий набор файлов и папок:
+
+```bash
+node_modules
+testplane-tests
+    example.testplane.ts
+    ts.config.json
+package-lock.json
+package.json
+testplane.config.ts
+```
 
 ## Настройка {#setup}
 
-После выполнения команды, указанной выше, в корне проекта сгенерится файл `testplane.config.ts` с базовой настройкой.
+В файле `testplane.config.ts` содержится базовый набор настроек для запуска тестов:
 
 ```typescript
 export default {
-    // https://testplane.io/ru/docs/v8/basic-guides/managing-browsers/
     gridUrl: "local",
     baseUrl: "http://localhost",
     pageLoadTimeout: 0,
     httpTimeout: 60000,
     testTimeout: 90000,
     resetCursor: false,
+
+    // В параметре sets содержится информация о директории, в которой находятся тесты
+    // и перечень браузеров, в которых они будут запускаться:
     sets: {
         desktop: {
             files: ["testplane-tests/**/*.testplane.(t|j)s"],
             browsers: ["chrome", "firefox"],
         },
     },
+
+    // В поле `browsers` описана конфигурация используемых браузеров:
     browsers: {
         chrome: {
             headless: true,
@@ -48,9 +71,9 @@ export default {
             },
         },
     },
+
     plugins: {
         "html-reporter/testplane": {
-            // https://github.com/gemini-testing/html-reporter
             enabled: true,
             path: "testplane-report",
             defaultView: "all",
@@ -60,39 +83,10 @@ export default {
 };
 ```
 
-Вы можете загрузить браузеры, описанные в конфиге, отдельно от запуска самого Testplane:
+Чтобы загрузить браузеры, описанные в конфиге, отдельно от запуска самого Testplane, выполните команду:
 
 ```bash
 npx testplane install-deps
 ```
 
 Без предварительного запуска команды, недостающие браузеры будут автоматически загружены с первым запуском Testplane.
-
-## Создание теста {#test_creation}
-
-Перейдите в файл `tests/example.testplane.js` с тестом. В нем вы можете посмотреть пример теста или написать свой. Например,
-
-```javascript
-describe("github", async function () {
-    it("should find testplane", async function ({ browser }) {
-        await browser.url("https://github.com/gemini-testing/testplane");
-        const elem = await browser.$("#readme h1");
-
-        await expect(elem).toHaveText("Testplane");
-    });
-});
-```
-
-## Запуск теста {#test_running}
-
-Теперь вы можете запустить тесты:
-
-```bash
-npx testplane
-```
-
-или запустить gui-режим и запустить тест через интерфейс в браузере
-
-```bash
-npx testplane gui
-```

i18n/ru/docusaurus-plugin-content-docs/current/quickstart/running-tests.mdx

@@ -2,54 +2,174 @@
 sidebar_position: 3
 ---
 
-# Запуск тестов
+# Запуск и отладка
 
-Используйте команду `npx testplane` для запуска всех тестов в вашем проекте.
+## Запуск тестов
 
-## Запуск конкретного файла
+Для запуска тестов используйте команду:
 
-Если вы хотите запустить всю группу тестов, которые находятся в конкретном файле, то укажите путь к этому файлу в качестве входного параметра для testplane:
+```bash
+npx testplane
+```
+
+Также тесты можно запускать в `gui`-режиме, для этого выполните команду:
 
 ```bash
-testplane src/features/Reviews/Reviews.test/MyReview/MyReview.a11y@touch-phone.testplane.js
+npx testplane gui
 ```
 
-## Опция `--grep`
+### Запуск конкретного теста
+
+У вас имеется набор тестов и вам нужно запустить только один из них.
+
+```javascript
+const assert = require("assert");
+
+describe("tests", () => {
+    it("Проверка отображения главной страницы", async ({ browser }) => {
+        await browser.url("https://testplane.io/ru/");
+        const title = await browser.getTitle();
+        assert.ok(title.includes("Testplane"));
+    });
+
+    it("Проверка наличия логотипа на главной странице", async ({ browser }) => {
+        await browser.url("https://testplane.io/ru/");
+        const logo = await browser.$("a.navbar__brand");
+        const isDisplayed = await logo.isDisplayed();
+        assert.strictEqual(isDisplayed, true);
+    });
+
+    it("Проверка навигационного меню", async ({ browser }) => {
+        await browser.url("https://testplane.io/ru/");
+        const menuItems = await browser.$$("nav.navbar a.navbar__item");
+        assert.ok(menuItems.length > 0);
+    });
+
+    it("Проверка наличия поля поиска", async ({ browser }) => {
+        await browser.url("https://testplane.io/ru/");
+        const searchButton = await browser.$("button.DocSearch");
+        const isExisting = await searchButton.isExisting();
+        assert.strictEqual(isExisting, true);
+    });
+});
+```
 
-Если же вы хотите запустить конкретный тест, то воспользуйтесь опцией `--grep`, указав в качестве ее значения полное имя теста:
+В таком случае выполните команду:
 
 ```bash
-testplane --grep "Доступность Оставление отзыва"
+testplane --grep "Проверка наличия поля поиска"
 ```
 
-## Директива `.only`
+В кавычках вам необходимо передать содержимое скобок ключевого слова `it`.
 
-Ещё вы можете воспользоваться директивой `.only` для набора тестов `describe` и конкретного теста `it`, аналогично тому как это реализовано в `mocha` (см. раздел [exlusive tests](https://mochajs.org/#exclusive-tests)):
+### Запуск тестов в конкретных браузерах
 
-Например:
+По умолчанию тесты запускаются в тех браузерах, которые указаны в файле `testplane.config.ts`.
 
 ```javascript
-describe.only("Доступность", function () {
-    // набор тестов...
-});
+browsers: ["chrome", "firefox"];
+```
+
+При выполнении команды `npx testplane` тесты запустятся в браузерах Google Chrome и Mozila Firefox.
+
+```bash
+# Запуск во всех браузерах (по умолчанию)
+testplane
+```
+
+Чтобы выполнить тесты в конкретном браузере, используйте команду:
+
+```bash
+# Запуск только в Chrome
+testplane --browser chrome
 ```
 
-или
+Также вы можете указать конкретный браузер для работы в теле теста.
 
 ```javascript
-it.only("Оставление отзыва", async function () {
-    // код теста...
+// tests/browser-specific.test.js
+describe("Browser specific tests", () => {
+    it("should work in all browsers", async ({ browser }) => {
+        await browser.url("https://example.com");
+    });
+
+    // Пропустить тест в Safari
+    testplane.skip.in("safari", "Feature not supported in Safari");
+    it("should work only in Chrome and Firefox", async ({ browser }) => {
+        await browser.url("https://example.com");
+        // ... тело теста
+    });
+
+    // Запустить только в Chrome
+    testplane.only.in("chrome");
+    it("should work only in Chrome", async ({ browser }) => {
+        await browser.url("https://example.com");
+        // ... тело теста
+    });
 });
 ```
 
-## Запуск тестов несколько раз {#running_tests_multiple_times}
 
-Иногда может быть полезным запустить один и тот же тест несколько раз — например, для проверки стабильности. Плагин [@testplane/test-repeater][testplane-test-repeater] позволяет запустить тесты заданное количество раз.
+### Запуск теста из конкретного файла
 
-После установки и включения плагина вы можете запустить тесты нужное количество раз, используя следующую команду:
+Чтобы запустить тесты из конкретного файла, выполните команду:
 
 ```bash
-npx testplane --test-repeater-repeat 5 --grep 'Имя теста'
+# Запуск конкретного файла
+testplane ../testplane-tests/example.testplane.ts
+```
+
+Где `../testplane-tests/example.testplane.ts` это путь к файлу с тестами.
+
+### Режим пользовательского интерфейса
+
+В Testplane вы можете работать с тестами в UI формате с помощью Testplane UI.
+
+![](/img/docs/html-reporter/html-reporter-demo.png)
+
+О процессах установки и настройки Testplane UI вы можете прочитать в разделе [UI.](..//html-reporter//overview.mdx)
+
+## Отладка
+
+### Отладка в gui-формате
+
+Отслеживать процесс выполнения тестов очень легко, если запустить их в `gui`-режиме. В подобном формате работы html-reporter продемонстрирует, какие тесты были успешно выполнены, а в каких присутствуют ошибки и какого они характера.
+
+![Интерфейс Testplane GUI](/img/docs/guides/testplane-gui.png)
+
+### Browser.debug()
+
+В Testplane имеется встроенный инструмент для отладки — `browser.debug`.
+
+```javascript
+it("отладка с паузой", async ({ browser }) => {
+    // Открываем тестируемую страницу
+    await browser.url("/page");
+
+    // browser.debug() останавливает выполнение теста
+    // и открывает интерактивную консоль (REPL - Read-Eval-Print Loop)
+    await browser.debug();
+
+    // После вызова debug() тест приостанавливается
+    // В консоли можно вводить команды WebdriverIO в реальном времени:
+
+    // Примеры команд, которые можно вводить в REPL:
+    // > await browser.$('.button').click()  - кликнуть по кнопке
+    // > await browser.getTitle()            - получить заголовок страницы
+    // > await browser.$$('.items')          - найти все элементы
+    // > .exit                               - выйти из режима отладки
+
+    // Этот код выполнится только после выхода из debug()
+    await browser.$(".button").click();
+});
 ```
 
-[testplane-test-repeater]: ../../plugins/testplane-test-repeater
+### Отладка через Testplane UI
+
+Наиболее удобным способом для работы с отладкой тестов является UI режим, в нем вы можете в реальном времени наблюдать выполнения тестов.
+
+![](/gif/docs/ui/run-debug.gif)
+
+И находить нестабильные тесты, медленные тесты или другие проблемы с помощью опций «сортировка» и «группировка».
+
+![](/gif/docs/ui/analytics.gif)