Skip to content

Commit

Permalink
docs(commands): add documentation about missing browser commands
Browse files Browse the repository at this point in the history
  • Loading branch information
sipayRT committed Aug 8, 2024
1 parent 655fda6 commit fee3f3e
Show file tree
Hide file tree
Showing 10 changed files with 321 additions and 4 deletions.
29 changes: 29 additions & 0 deletions docs/commands/browser/clearSession.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# clearSession

## Обзор {#overview}

Команда браузера, которая очищает состояние сессии (удаляет куки, очищает локальное и сессионное хранилища).

## Использование {#usage}

```javascript
await browser.clearSession();
```

## Примеры использования {#examples}

```javascript
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
});
```
67 changes: 67 additions & 0 deletions docs/commands/browser/runStep.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# runStep

## Обзор {#overview}

Используйте команду `runStep`, чтобы получить человекочитаемую историю выполнения теста, которая, в том числе, автоматически будет отображаться в [html-reporter][reporter].
Шаги могут быть вложенными.

## Использование {#usage}

```javascript
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>
</table>

## Примеры использования {#examples}

```javascript
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` свернут, т.к. он был выполнен успешно.

Также, вы можете вернуть конкретное значение из шага.

```javascript
const parsedPage = await browser.runStep('parse page', async () => {
...
return someData;
});
```

[reporter]: ../../../html-reporter/html-reporter-setup
32 changes: 32 additions & 0 deletions docs/commands/browser/setOrientation.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# setOrientation

## Обзор {#overview}

Используйте команду `setOrientation`, чтобы изменить ориентацию браузера. Эта команда гарантирует, что последующие команды не начнут выполнение раньше, чем произойдет смена ориентации.
Если устройство не поддерживает такую возможность, то команда будет проигнорирована.

## Использование {#usage}

```javascript
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}

```javascript
it("test", async ({ browser }) => {
await browser.setOrientation("landscape");
});
```
33 changes: 33 additions & 0 deletions docs/commands/element/moveCursorTo.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
import Admonition from "@theme/Admonition";

# moveCursorTo

## Обзор {#overview}

<Admonition type="info">
Эта команда является временной и будет удалена в следующей мажорной версии (`[email protected]`).
Отличается от стандартной `moveTo` тем, что перемещает курсор относительно верхнего левого угла
элемента (как это было в `hermione@7`).
</Admonition>

Используйте команду `moveCursorTo`, чтобы переместить курсор мыши на смещение относительно указанного элемента.
Если смещение не указано, то курсор мыши будет перемещен в верхний левый угол элемента.

## Использование {#usage}

```javascript
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>
2 changes: 0 additions & 2 deletions docs/commands/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,6 @@ import Admonition from "@theme/Admonition";

- не проставлены связи между похожими командами: нет кластеризации команд;

- все команды описаны только на английском языке.

Тем не менее в наше описание пока ещё не вошли протоколо-специфичные команды. Соответствующие команды вы можете посмотреть на сайте WebDriverIO в разделе "[Protocols][webdriverio-protocols]".

Также в описаниях некоторых команд ссылки на отдельные рецепты все еще не локализованы и ведут на сайт WebDriverIO.
Expand Down
Original file line number Diff line number Diff line change
@@ -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}

```javascript
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
});
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# 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}

```javascript
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>
</table>

## Usage Examples {#examples}

```javascript
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:

```javascript
const parsedPage = await browser.runStep('parse page', async () => {
...
return someData;
});
```

[reporter]: ../../../html-reporter/html-reporter-setup
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# 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}

```javascript
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>
</table>

## Usage Examples {#examples}

```javascript
it("test", async ({ browser }) => {
await browser.setOrientation("landscape");
});
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import Admonition from "@theme/Admonition";

# moveCursorTo

<Admonition type="info">
This command is temporary and will be removed in the next major (`[email protected]`). 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`).
</Admonition>

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}

```javascript
await browser.$(selector).moveCursorTo({ xOffset, yOffset });
```

## Command Parameters {#parameters}

<table>
<thead>
<tr><td>**Name**</td><td>**Type**</td><td>**Description**</td></tr>
</thead>
<tbody>
<tr><td>xOffset</td><td>Number</td><td>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.</td></tr>
<tr><td>yOffset</td><td>Number</td><td>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.</td></tr>

</tbody>
</table>
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit fee3f3e

Please sign in to comment.