doc: review fixes + switchToRepl command

gemini-testing · Aug 13, 2024 · b4c92d1 · b4c92d1
1 parent e549bb4
commit b4c92d1
Show file tree

Hide file tree

Showing 10 changed files with 302 additions and 64 deletions.
diff --git 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
@@ -7,26 +7,37 @@
 
 ## Использование {#usage}
 
-```javascript
+```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>Function</td><td>Функция с набором команд, которые нужно объединить в единый шаг.</td></tr>
-
-</tbody>
+    <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}
 
-```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
@@ -7,25 +7,32 @@
 
 ## Использование {#usage}
 
-```javascript
+```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>
+    <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}
 
-```javascript
+```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
@@ -15,19 +15,36 @@ import Admonition from "@theme/Admonition";
 
 ## Использование {#usage}
 
-```javascript
+```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>
+    <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/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
@@ -7,26 +7,37 @@ Steps can be nested.
 
 ## Usage {#usage}
 
-```javascript
+```typescript
 await browser.runStep(stepName, stepCb);
 ```
 
 ## Command Parameters {#parameters}
 
 <table>
-<thead>
-<tr><td>**Name**</td><td>**Type**</td><td>**Description**</td></tr>
-</thead>
-<tbody>
-<tr><td>stepName</td><td>String</td><td>Step name.</td></tr>
-<tr><td>stepCb</td><td>Function</td><td>A function with commands that need to be combined into a single step.</td></tr>
-
-</tbody>
+    <thead>
+        <tr>
+            <td>**Name**</td>
+            <td>**Type**</td>
+            <td>**Description**</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>`stepName`</td>
+            <td>`string`</td>
+            <td>Step name.</td>
+        </tr>
+        <tr>
+            <td>`stepCb`</td>
+            <td>`() => Promise<any>`</td>
+            <td>A function with commands that need to be combined into a single step.</td>
+        </tr>
+    </tbody>
 </table>
 
 ## 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
@@ -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}
 
 <table>
-<thead>
-<tr><td>**Name**</td><td>**Type**</td><td>**Description**</td></tr>
-</thead>
-<tbody>
-<tr><td>orientation</td><td>"landscape" | "portrait"</td><td>The path to the screenshot relative to the execution directory (the _.png_ extension is mandatory).</td></tr>
-
-</tbody>
+    <thead>
+        <tr>
+            <td>**Name**</td>
+            <td>**Type**</td>
+            <td>**Description**</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>`orientation`</td>
+            <td>`"landscape" | "portrait"`</td>
+            <td>
+                The path to the screenshot relative to the execution directory (the _.png_ extension
+                is mandatory).
+            </td>
+        </tr>
+    </tbody>
 </table>
 
 ## Usage Examples {#examples}
 
-```javascript
+```typescript
 it("test", async ({ browser }) => {
     await browser.setOrientation("landscape");
 });