diff --git a/docs/commands/browser/clearSession.mdx b/docs/commands/browser/clearSession.mdx new file mode 100644 index 0000000..c530c4e --- /dev/null +++ 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 new file mode 100644 index 0000000..70a717e --- /dev/null +++ b/docs/commands/browser/runStep.mdx @@ -0,0 +1,78 @@ +# runStep + +## Обзор {#overview} + +Используйте команду `runStep`, чтобы получить человекочитаемую историю выполнения теста, которая, в том числе, автоматически будет отображаться в [html-reporter][reporter]. +Шаги могут быть вложенными. + +## Использование {#usage} + +```typescript +await browser.runStep(stepName, stepCb); +``` + +## Параметры команды {#parameters} + + + + + + + + + + + + + + + + + + + + + +
**Имя****Тип****Описание**
`stepName``string`Название шага.
`stepCb``() => Promise`Функция с набором команд, которые нужно объединить в единый шаг.
+ +## Примеры использования {#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 new file mode 100644 index 0000000..d2d762f --- /dev/null +++ b/docs/commands/browser/setOrientation.mdx @@ -0,0 +1,39 @@ +# setOrientation + +## Обзор {#overview} + +Используйте команду `setOrientation`, чтобы изменить ориентацию браузера. Эта команда гарантирует, что последующие команды не начнут выполнение раньше, чем произойдет смена ориентации. +Если устройство не поддерживает такую возможность, то команда будет проигнорирована. + +## Использование {#usage} + +```typescript +await browser.setOrientation(orientation); +``` + +## Параметры команды {#parameters} + + + + + + + + + + + + + + + + +
**Имя****Тип****Описание**
`orientation``"landscape" | "portrait"`The orientation to set.
+ +## Примеры использования {#examples} + +```typescript +it("test", async ({ browser }) => { + await browser.setOrientation("landscape"); +}); +``` diff --git a/docs/commands/browser/switchToRepl.mdx b/docs/commands/browser/switchToRepl.mdx index e69de29..5a4886f 100644 --- 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]. + + + Данная команда доступна только при запуске `testplane` с опцией `--repl`. При запуске необходимо + явно указать тест и браузер, т.к. в REPL-режиме нельзя запускать сразу несколько тестов. + + +## Использование {#usage} + +```typescript +await browser.switchToRepl(ctx); +``` + +## Параметры команды {#parameters} + + + + + + + + + + + + + + + + +
**Имя****Тип****Описание**
`context``Record`Контекст с данными, которые будут доступны в интерактивном режиме.
+ +## Примеры использования {#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 new file mode 100644 index 0000000..d5ad40b --- /dev/null +++ b/docs/commands/element/moveCursorTo.mdx @@ -0,0 +1,50 @@ +import Admonition from "@theme/Admonition"; + +# moveCursorTo + +## Обзор {#overview} + + + Эта команда является временной и будет удалена в следующей мажорной версии (`testplane@9.x`). + Отличается от стандартной `moveTo` тем, что перемещает курсор относительно верхнего левого угла + элемента (как это было в `hermione@7`). + + +Используйте команду `moveCursorTo`, чтобы переместить курсор мыши на смещение относительно указанного элемента. +Если смещение не указано, то курсор мыши будет перемещен в верхний левый угол элемента. + +## Использование {#usage} + +```typescript +await browser.$(selector).moveCursorTo({ xOffset, yOffset }); +``` + +## Параметры команды {#parameters} + + + + + + + + + + + + + + + + + + + + + +
**Имя****Тип****Описание**
`xOffset``number` + Смещение по оси X. Задается относительно верхнего левого угла элемента. Если не + указано, мышь переместится в левый верхний угол элемента. +
`yOffset``number` + Смещение по оси Y. Задается относительно верхнего левого угла элемента. Если не + указано, мышь переместится в левый верхний угол элемента. +
diff --git a/docs/commands/overview.mdx b/docs/commands/overview.mdx index 3f98a4a..1e5ceb6 100644 --- 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 new file mode 100644 index 0000000..460c6d1 --- /dev/null +++ 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 +}); +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/runStep.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/runStep.mdx new file mode 100644 index 0000000..8f02545 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/runStep.mdx @@ -0,0 +1,78 @@ +# runStep + +## Overview {#overview} + +Use the `runStep` command to obtain a human-readable execution history of the test, which will automatically be displayed in the [html-reporter][reporter]. +Steps can be nested. + +## Usage {#usage} + +```typescript +await browser.runStep(stepName, stepCb); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + + + + + + + + + + +
**Name****Type****Description**
`stepName``string`Step name.
`stepCb``() => Promise`A function with commands that need to be combined into a single step.
+ +## Usage Examples {#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(); + }); + }); +}); +``` + +This test will fail with the error "Cannot call click on element with selector 'not-exist-selector' because element wasn't found" due to the missing selector and the following history will be generated: + +``` +- testplane: init browser +- prepare page +- make an order + - navigate to the shopping cart + - $("not-exist-selector") + - click() + - waitForExist +``` + +In this example step `some step name` is collapsed, because it is completed successfully. + +You can also return values from step: + +```typescript +const parsedPage = await browser.runStep("parse page", async () => { + // ... + return someData; +}); +``` + +[reporter]: ../../../html-reporter/html-reporter-setup diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setOrientation.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setOrientation.mdx new file mode 100644 index 0000000..ff1353a --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setOrientation.mdx @@ -0,0 +1,42 @@ +# setOrientation + +## Overview {#overview} + +Use the `setOrientation` command to change the browser orientation. This command ensures that subsequent commands will not start executing until the orientation change occurs. +If the device does not support this feature, the command will be ignored. + +## Usage {#usage} + +```typescript +await browser.setOrientation(orientation); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + + + + + +
**Name****Type****Description**
`orientation``"landscape" | "portrait"` + The path to the screenshot relative to the execution directory (the _.png_ extension + is mandatory). +
+ +## Usage Examples {#examples} + +```typescript +it("test", async ({ browser }) => { + await browser.setOrientation("landscape"); +}); +``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchToRepl.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchToRepl.mdx index e69de29..5ac5890 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchToRepl.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchToRepl.mdx @@ -0,0 +1,82 @@ +import Admonition from "@theme/Admonition"; + +# switchToRepl + +## Overview {#overview} + +Use the `switchToRepl` command to stop the test execution and open an interactive `REPL` interface in the terminal where you can execute code line by line and observe the results in real-time. This mode allows for convenient debugging of problematic tests both in a locally installed browser and in a remote grid (for example, using [VNC][vnc]). + +For more convenient use of the `REPL` mode, it is recommended to use the [VS Code extension][extension]. + +## Usage {#usage} + +```typescript +await browser.runStep(stepName, stepCb); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + + + + + + + + + + +
**Name****Type****Description**
`stepName``string`Step name.
`context``Record`A context with data that will be available in the interactive console.
+ +## Usage Examples {#examples} + +```typescript +it("test", async ({ browser }) => { + console.log("before open repl"); + + await browser.switchToRepl(); + + console.log("after open repl"); +}); +``` + +When executing this test, the text before open repl will first be printed to the console. Then, the test execution will stop, and an interactive `REPL` interface will open in the terminal, waiting for command input. +For example, you can execute the following command and immediately get the result of its execution: + +```bash +> await browser.getUrl(); +about:blank +``` + +After you finish working in the `REPL` (for instance, by pressing `Cmd+D`), the test execution will continue, and the text after open repl will be printed in the terminal console, after which the browser will close. + +You can also pass context to the REPL so that a variable is available in the interface. For example: + +``` +it("test", async ({browser}) => { + const counter = 1; + + await browser.switchToRepl({ counter }); +}); +``` + +Since we passed the `counter` variable to the context, it will be available in the terminal: + +```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/i18n/en/docusaurus-plugin-content-docs/current/commands/element/moveCursorTo.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/element/moveCursorTo.mdx new file mode 100644 index 0000000..9e8fd45 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/element/moveCursorTo.mdx @@ -0,0 +1,49 @@ +import Admonition from "@theme/Admonition"; + +# moveCursorTo + + + This command is temporary and will be removed in the next major (`testplane@9.x`). Differs from + the standard `moveTo` in that it moves the cursor relative to the top-left corner of the element + (like it was in `hermione@7`). + + +Use the `moveCursorTo` command to move the mouse by specified offsets along the X and Y axes relative to the specified element. + +If offset is not specified then mouse will be moved to the top-left corder of the element. + +## Usage {#usage} + +```typescript +await browser.$(selector).moveCursorTo({ xOffset, yOffset }); +``` + +## Command Parameters {#parameters} + + + + + + + + + + + + + + + + + + + + + +
**Name****Type****Description**
`xOffset``number` + The X-axis offset relative to the top-left corner of the element. If not specified, + the mouse will move to the top-left corner of the element. +
`yOffset``number` + The Y-axis offset relative to the top-left corner of the element. If not specified, + the mouse will move to the top-left corner of the element. +
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/overview.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/overview.mdx index 332df8f..fa78b15 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/commands/overview.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/overview.mdx @@ -39,8 +39,6 @@ it("should test something", async ({ browser }) => { - There are no links established between similar commands: no clustering of commands; -- All commands are described only in English. - Nevertheless, our description does not yet include protocol-specific commands. You can find the relevant commands on the WebDriverIO website under the "[Protocols][webdriverio-protocols]" section. Also, in the descriptions of some commands, links to individual recipes are still not localized and lead to the WebDriverIO website.