From b4c92d1e247432c9e01b6fc7d1219ecdec196265 Mon Sep 17 00:00:00 2001 From: sipayrt Date: Tue, 13 Aug 2024 15:53:05 +0300 Subject: [PATCH] doc: review fixes + switchToRepl command --- docs/commands/browser/clearSession.mdx | 2 +- docs/commands/browser/runStep.mdx | 37 ++++++--- docs/commands/browser/setOrientation.mdx | 25 ++++-- docs/commands/browser/switchToRepl.mdx | 83 +++++++++++++++++++ docs/commands/element/moveCursorTo.mdx | 35 ++++++-- .../current/commands/browser/clearSession.mdx | 2 +- .../current/commands/browser/runStep.mdx | 37 ++++++--- .../commands/browser/setOrientation.mdx | 28 +++++-- .../current/commands/browser/switchToRepl.mdx | 82 ++++++++++++++++++ .../current/commands/element/moveCursorTo.mdx | 35 ++++++-- 10 files changed, 302 insertions(+), 64 deletions(-) diff --git a/docs/commands/browser/clearSession.mdx b/docs/commands/browser/clearSession.mdx index 513497f..c530c4e 100644 --- a/docs/commands/browser/clearSession.mdx +++ b/docs/commands/browser/clearSession.mdx @@ -12,7 +12,7 @@ await browser.clearSession(); ## Примеры использования {#examples} -```javascript +```typescript it("test", async ({ browser }) => { await browser.url("https://github.com/gemini-testing/testplane"); diff --git a/docs/commands/browser/runStep.mdx b/docs/commands/browser/runStep.mdx index 49a04f5..70a717e 100644 --- a/docs/commands/browser/runStep.mdx +++ b/docs/commands/browser/runStep.mdx @@ -7,26 +7,37 @@ ## Использование {#usage} -```javascript +```typescript await browser.runStep(stepName, stepCb); ``` ## Параметры команды {#parameters} - - - - - - - - + + + + + + + + + + + + + + + + + + +
**Имя****Тип****Описание**
stepNameStringНазвание шага.
stepCbFunctionФункция с набором команд, которые нужно объединить в единый шаг.
**Имя****Тип****Описание**
`stepName``string`Название шага.
`stepCb``() => Promise`Функция с набором команд, которые нужно объединить в единый шаг.
## Примеры использования {#examples} -```javascript +```typescript it("test", async ({ browser }) => { await browser.runStep("prepare page", async () => { await browser.url("some/url"); @@ -57,9 +68,9 @@ it("test", async ({ browser }) => { Также, вы можете вернуть конкретное значение из шага. -```javascript -const parsedPage = await browser.runStep('parse page', async () => { - ... +```typescript +const parsedPage = await browser.runStep("parse page", async () => { + // ... return someData; }); ``` diff --git a/docs/commands/browser/setOrientation.mdx b/docs/commands/browser/setOrientation.mdx index 6c2c9e6..d2d762f 100644 --- a/docs/commands/browser/setOrientation.mdx +++ b/docs/commands/browser/setOrientation.mdx @@ -7,25 +7,32 @@ ## Использование {#usage} -```javascript +```typescript await browser.setOrientation(orientation); ``` ## Параметры команды {#parameters} - - - - - - - + + + + + + + + + + + + + +
**Имя****Тип****Описание**
orientation"landscape" | "portrait"The orientation to set.
**Имя****Тип****Описание**
`orientation``"landscape" | "portrait"`The orientation to set.
## Примеры использования {#examples} -```javascript +```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 index a1f865f..d5ad40b 100644 --- a/docs/commands/element/moveCursorTo.mdx +++ b/docs/commands/element/moveCursorTo.mdx @@ -15,19 +15,36 @@ import Admonition from "@theme/Admonition"; ## Использование {#usage} -```javascript +```typescript await browser.$(selector).moveCursorTo({ xOffset, yOffset }); ``` ## Параметры команды {#parameters} - - - - - - - - + + + + + + + + + + + + + + + + + + +
**Имя****Тип****Описание**
xOffsetNumberСмещение по оси X. Задается относительно верхнего левого угла элемента. Если не указано, мышь переместится в левый верхний угол элемента.
yOffsetNumberСмещение по оси Y. Задается относительно верхнего левого угла элемента. Если не указано, мышь переместится в левый верхний угол элемента.
**Имя****Тип****Описание**
`xOffset``number` + Смещение по оси X. Задается относительно верхнего левого угла элемента. Если не + указано, мышь переместится в левый верхний угол элемента. +
`yOffset``number` + Смещение по оси Y. Задается относительно верхнего левого угла элемента. Если не + указано, мышь переместится в левый верхний угол элемента. +
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 index 85595d1..460c6d1 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/clearSession.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/clearSession.mdx @@ -12,7 +12,7 @@ await browser.clearSession(); ## Usage Examples {#examples} -```javascript +```typescript it("test", async ({ browser }) => { await browser.url("https://github.com/gemini-testing/testplane"); 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 index c6f6f2e..8f02545 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/runStep.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/runStep.mdx @@ -7,26 +7,37 @@ Steps can be nested. ## Usage {#usage} -```javascript +```typescript await browser.runStep(stepName, stepCb); ``` ## Command Parameters {#parameters} - - - - - - - - + + + + + + + + + + + + + + + + + + +
**Name****Type****Description**
stepNameStringStep name.
stepCbFunctionA function with commands that need to be combined into a single step.
**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} -```javascript +```typescript it("test", async ({ browser }) => { await browser.runStep("prepare page", async () => { await browser.url("some/url"); @@ -57,9 +68,9 @@ In this example step `some step name` is collapsed, because it is completed succ You can also return values from step: -```javascript -const parsedPage = await browser.runStep('parse page', async () => { - ... +```typescript +const parsedPage = await browser.runStep("parse page", async () => { + // ... return someData; }); ``` 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 index d27c488..ff1353a 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setOrientation.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/setOrientation.mdx @@ -7,25 +7,35 @@ If the device does not support this feature, the command will be ignored. ## Usage {#usage} -```javascript +```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).
**Name****Type****Description**
`orientation``"landscape" | "portrait"` + The path to the screenshot relative to the execution directory (the _.png_ extension + is mandatory). +
## Usage Examples {#examples} -```javascript +```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 index 9debfa6..9e8fd45 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/commands/element/moveCursorTo.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/commands/element/moveCursorTo.mdx @@ -14,19 +14,36 @@ If offset is not specified then mouse will be moved to the top-left corder of th ## Usage {#usage} -```javascript +```typescript await browser.$(selector).moveCursorTo({ xOffset, yOffset }); ``` ## Command Parameters {#parameters} - - - - - - - - + + + + + + + + + + + + + + + + + + +
**Name****Type****Description**
xOffsetNumberThe 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.
yOffsetNumberThe 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.
**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. +