Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(commands): add documentation about missing browser commands #23

Merged
merged 1 commit into from
Aug 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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}

```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
});
```
78 changes: 78 additions & 0 deletions docs/commands/browser/runStep.mdx
Original file line number Diff line number Diff line change
@@ -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
39 changes: 39 additions & 0 deletions docs/commands/browser/setOrientation.mdx
Original file line number Diff line number Diff line change
@@ -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");
});
```
83 changes: 83 additions & 0 deletions docs/commands/browser/switchToRepl.mdx
Original file line number Diff line number Diff line change
@@ -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
50 changes: 50 additions & 0 deletions docs/commands/element/moveCursorTo.mdx
Original file line number Diff line number Diff line change
@@ -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>
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}

```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
});
```
Loading
Loading