Merge pull request #23 from gemini-testing/sp.commands

docs(commands): add documentation about missing browser commands
gemini-testing · Aug 13, 2024 · a86d194 · a86d194
2 parents bd899ad + e4d4eb8
commit a86d194
Show file tree

Hide file tree

Showing 12 changed files with 559 additions and 4 deletions.
diff --git a/docs/commands/browser/clearSession.mdx b/docs/commands/browser/clearSession.mdx
@@ -0,0 +1,29 @@
+# clearSession
+
+## Обзор {#overview}
+
+Команда браузера, которая очищает состояние сессии (удаляет куки, очищает локальное и сессионное хранилища).
+
+## Использование {#usage}
+
+```javascript
+await browser.clearSession();
+```
+
+## Примеры использования {#examples}
+
+```typescript
+it("test", async ({ browser }) => {
+    await browser.url("https://github.com/gemini-testing/testplane");
+
+    (await browser.getCookies()).length; // 5
+    await browser.execute(() => localStorage.length); // 2
+    await browser.execute(() => sessionStorage.length); // 1
+
+    await browser.clearSession();
+
+    (await browser.getCookies()).length; // 0
+    await browser.execute(() => localStorage.length); // 0
+    await browser.execute(() => sessionStorage.length); // 0
+});
+```
diff --git a/docs/commands/browser/runStep.mdx b/docs/commands/browser/runStep.mdx
@@ -0,0 +1,78 @@
+# runStep
+
+## Обзор {#overview}
+
+Используйте команду `runStep`, чтобы получить человекочитаемую историю выполнения теста, которая, в том числе, автоматически будет отображаться в [html-reporter][reporter].
+Шаги могут быть вложенными.
+
+## Использование {#usage}
+
+```typescript
+await browser.runStep(stepName, stepCb);
+```
+
+## Параметры команды {#parameters}
+
+<table>
+    <thead>
+        <tr>
+            <td>**Имя**</td>
+            <td>**Тип**</td>
+            <td>**Описание**</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>`stepName`</td>
+            <td>`string`</td>
+            <td>Название шага.</td>
+        </tr>
+        <tr>
+            <td>`stepCb`</td>
+            <td>`() => Promise<any>`</td>
+            <td>Функция с набором команд, которые нужно объединить в единый шаг.</td>
+        </tr>
+    </tbody>
+</table>
+
+## Примеры использования {#examples}
+
+```typescript
+it("test", async ({ browser }) => {
+    await browser.runStep("prepare page", async () => {
+        await browser.url("some/url");
+        await browser.setCookies(someCookies);
+    });
+
+    await browser.runStep("make an order", async () => {
+        await browser.runStep("navigate to the shopping cart", async () => {
+            await browser.$("not-exist-selector").click();
+        });
+    });
+});
+```
+
+Данный тест завершится с ошибкой "Cannot call click on element with selector 'not-exist-selector' because element wasn't found" из-за отсутствующего селектора и будет создана следующая история:
+
+```
+- testplane: init browser
+- prepare page
+- make an order
+    - navigate to the shopping cart
+        - $("not-exist-selector")
+        - click()
+            - waitForExist
+```
+
+В этом примере шаг `prepare page` свернут, т.к. он был выполнен успешно.
+
+Также, вы можете вернуть конкретное значение из шага.
+
+```typescript
+const parsedPage = await browser.runStep("parse page", async () => {
+    // ...
+    return someData;
+});
+```
+
+[reporter]: ../../../html-reporter/html-reporter-setup
diff --git a/docs/commands/browser/setOrientation.mdx b/docs/commands/browser/setOrientation.mdx
@@ -0,0 +1,39 @@
+# setOrientation
+
+## Обзор {#overview}
+
+Используйте команду `setOrientation`, чтобы изменить ориентацию браузера. Эта команда гарантирует, что последующие команды не начнут выполнение раньше, чем произойдет смена ориентации.
+Если устройство не поддерживает такую возможность, то команда будет проигнорирована.
+
+## Использование {#usage}
+
+```typescript
+await browser.setOrientation(orientation);
+```
+
+## Параметры команды {#parameters}
+
+<table>
+    <thead>
+        <tr>
+            <td>**Имя**</td>
+            <td>**Тип**</td>
+            <td>**Описание**</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>`orientation`</td>
+            <td>`"landscape" | "portrait"`</td>
+            <td>The orientation to set.</td>
+        </tr>
+    </tbody>
+</table>
+
+## Примеры использования {#examples}
+
+```typescript
+it("test", async ({ browser }) => {
+    await browser.setOrientation("landscape");
+});
+```
diff --git a/docs/commands/browser/switchToRepl.mdx b/docs/commands/browser/switchToRepl.mdx
@@ -0,0 +1,83 @@
+import Admonition from "@theme/Admonition";
+
+# switchToRepl
+
+## Обзор {#overview}
+
+Используйте команду `switchToRepl`, чтобы остановить выполнение теста и открыть интерактивный интерфейс REPL в терминале, в котором можно выполнять код построчно и наблюдать за результатом выполнения в реальном времени.
+Этот режим позволяет удобно пошабого дебажить проблемные тесты как в локально установленном браузере, так и в удаленном гриде (например, с помощью [VNC][vnc]).
+
+Для более удобного использования REPL-режима рекомендуется использовать [расширение для VS Code][extension].
+
+<Admonition type="warning">
+    Данная команда доступна только при запуске `testplane` с опцией `--repl`. При запуске необходимо
+    явно указать тест и браузер, т.к. в REPL-режиме нельзя запускать сразу несколько тестов.
+</Admonition>
+
+## Использование {#usage}
+
+```typescript
+await browser.switchToRepl(ctx);
+```
+
+## Параметры команды {#parameters}
+
+<table>
+    <thead>
+        <tr>
+            <td>**Имя**</td>
+            <td>**Тип**</td>
+            <td>**Описание**</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>`context`</td>
+            <td>`Record<string, unknown>`</td>
+            <td>Контекст с данными, которые будут доступны в интерактивном режиме.</td>
+        </tr>
+    </tbody>
+</table>
+
+## Примеры использования {#examples}
+
+```typescript
+it("test", async ({ browser }) => {
+    console.log("before open repl");
+
+    await browser.switchToRepl();
+
+    console.log("after open repl");
+});
+```
+
+При выполнении данного теста сначала будет выведен текст `before open repl` в консоль. Затем выполнение теста остановится, и в терминале откроется интерактивный интерфейс REPL, ожидающий ввода команд.
+Например, можно выполнить следующую команду и сразу получить результат ее выполнения:
+
+```bash
+> await browser.getUrl();
+about:blank
+```
+
+После того, как вы закончите работу в REPL (например, нажатием `Cmd+D`), выполнение теста продолжится, и в консоли терминала будет выведен текст `after open repl`, а затем браузер закроется.
+
+Также, можно передать контекст в REPL, чтобы переменная была доступна в интерфейсе. Например:
+
+```
+it("test", async ({browser}) => {
+    const counter = 1;
+
+    await browser.switchToRepl({ counter });
+});
+```
+
+Т.к. мы передали в контекст переменную `counter`, то она будет доступна в терминале:
+
+```bash
+npx hermione --repl --grep "test" -b "chrome"
+> console.log("counter:", counter);
+counter: 1
+```
+
+[extension]: https://marketplace.visualstudio.com/items?itemName=gemini-testing.vscode-testplane
+[vnc]: https://novnc.com/info.html
diff --git a/docs/commands/element/moveCursorTo.mdx b/docs/commands/element/moveCursorTo.mdx
@@ -0,0 +1,50 @@
+import Admonition from "@theme/Admonition";
+
+# moveCursorTo
+
+## Обзор {#overview}
+
+<Admonition type="info">
+    Эта команда является временной и будет удалена в следующей мажорной версии (`[email protected]`).
+    Отличается от стандартной `moveTo` тем, что перемещает курсор относительно верхнего левого угла
+    элемента (как это было в `hermione@7`).
+</Admonition>
+
+Используйте команду `moveCursorTo`, чтобы переместить курсор мыши на смещение относительно указанного элемента.
+Если смещение не указано, то курсор мыши будет перемещен в верхний левый угол элемента.
+
+## Использование {#usage}
+
+```typescript
+await browser.$(selector).moveCursorTo({ xOffset, yOffset });
+```
+
+## Параметры команды {#parameters}
+
+<table>
+    <thead>
+        <tr>
+            <td>**Имя**</td>
+            <td>**Тип**</td>
+            <td>**Описание**</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>`xOffset`</td>
+            <td>`number`</td>
+            <td>
+                Смещение по оси X. Задается относительно верхнего левого угла элемента. Если не
+                указано, мышь переместится в левый верхний угол элемента.
+            </td>
+        </tr>
+        <tr>
+            <td>`yOffset`</td>
+            <td>`number`</td>
+            <td>
+                Смещение по оси Y. Задается относительно верхнего левого угла элемента. Если не
+                указано, мышь переместится в левый верхний угол элемента.
+            </td>
+        </tr>
+    </tbody>
+</table>
diff --git a/docs/commands/overview.mdx b/docs/commands/overview.mdx
@@ -39,8 +39,6 @@ import Admonition from "@theme/Admonition";
 
 -   не проставлены связи между похожими командами: нет кластеризации команд;
 
--   все команды описаны только на английском языке.
-
 Тем не менее в наше описание пока ещё не вошли протоколо-специфичные команды. Соответствующие команды вы можете посмотреть на сайте WebDriverIO в разделе "[Protocols][webdriverio-protocols]".
 
 Также в описаниях некоторых команд ссылки на отдельные рецепты все еще не локализованы и ведут на сайт WebDriverIO.

diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/clearSession.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/clearSession.mdx
@@ -0,0 +1,29 @@
+# clearSession
+
+## Overview {#overview}
+
+Browser command that clears session state (deletes cookies, clears local and session storages).
+
+## Usage {#usage}
+
+```javascript
+await browser.clearSession();
+```
+
+## Usage Examples {#examples}
+
+```typescript
+it("test", async ({ browser }) => {
+    await browser.url("https://github.com/gemini-testing/testplane");
+
+    (await browser.getCookies()).length; // 5
+    await browser.execute(() => localStorage.length); // 2
+    await browser.execute(() => sessionStorage.length); // 1
+
+    await browser.clearSession();
+
+    (await browser.getCookies()).length; // 0
+    await browser.execute(() => localStorage.length); // 0
+    await browser.execute(() => sessionStorage.length); // 0
+});
+```