Skip to content

Commit 8502bda

Browse files
sonic16xsonic16x
authored
Docs for keep-browser and standalone api (#87)
feat(testplane-docs): docs for keep-browser and standalone api
1 parent 950b099 commit 8502bda

4 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎docs/command-line/index.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ Main command to run tests.
3030
--repl-on-fail [type] open repl interface on test fail only (default: false)
3131
--devtools switches the browser to the devtools mode with using CDP protocol
3232
--local use automatically downloaded browsers and drivers, provided by Testplane
33+
--keep-browser do not close browser session after test completion
34+
--keep-browser-on-fail do not close browser session when test fails
3335
-h, --help output usage information
3436
```
3537
@@ -184,6 +186,27 @@ testplane --repl --grep 'my test name' --browser chrome
184186
command documentation.
185187
</Admonition>
186188
189+
#### Keep browser {#testplane-keep-browser}
190+
191+
- `--keep-browser` - in this mode, the browser will not close after the tests complete; the console will output information on how to connect to the remaining browser instance.
192+
- `--keep-browser-on-fail` - the same as the `--keep-browser` option, but the browser will only remain open if the tests fail.
193+
194+
Example of console output with connection information to the browser:
195+
```
196+
[15:44:38 +0700] Testplane run has finished, but the browser won't be closed, because you passed the --keep-browser argument.
197+
[15:44:38 +0700] You may attach to this browser using the following capabilities:
198+
[15:44:38 +0700] {
199+
"sessionId": "c69958b3f85b851f7bf83f27bb026d58",
200+
"sessionCaps": {
201+
"acceptInsecureCerts": false,
202+
...
203+
},
204+
"driverPid": 31745
205+
}
206+
[15:44:38 +0700] ✓ test example #0 [chrome:c69958b3f85b851f7bf83f27bb026d58, pid:31744] - 1676ms
207+
208+
```
209+
187210
#### Devtools {#testplane-devtools}
188211
189212
Runs Testplane tests using [devtools automation protocol][webdriver-vs-cdp].

‎docs/reference/testplane-standalone-api.mdx‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Testplane standalone api
2+
3+
## Overview
4+
5+
The Standalone API allows you to launch a new browser instance or connect to an existing one directly from your code, and then perform any required actions within it.
6+
7+
Please note: The Standalone API is currently unstable and its interface is subject to change. Please keep this in mind when using it.
8+
9+
## Usage
10+
11+
### Launch browser
12+
13+
Launching the browser with the necessary parameters
14+
15+
```typescript
16+
import { launchBrowser } from "testplane/unstable";
17+
18+
// Launch a new browser with the given settings
19+
const browser = await launchBrowser({
20+
desiredCapabilities: {
21+
browserName: 'chrome',
22+
},
23+
headless: false,
24+
});
25+
26+
// Navigate to the URL and perform necessary actions
27+
await browser.url("https://example.com");
28+
29+
// !Important: terminate the session to prevent resource leaks (zombie processes)
30+
await browser.deleteSession();
31+
```
32+
33+
More info about [launchBrowser](https://github.com/gemini-testing/testplane/blob/master/src/browser/standalone/launchBrowser.ts)
34+
35+
### Attach to browser
36+
37+
Attach to the existing browser with session params.
38+
You can get session params if run testplane with `--keep-browser` option, see [more](../command-line/index.mdx#testplane-keep-browser)
39+
40+
```typescript
41+
import { attachToBrowser } from "testplane/unstable";
42+
43+
// Attach to existing browser with session params
44+
const browser = await attachToBrowser({
45+
sessionId: "f1bd2b2bc6563f82d2120c31f4b92c03",
46+
sessionCaps: {
47+
browserName: "chrome",
48+
browserVersion: "137.0.7151.119",
49+
setWindowRect: true,
50+
},
51+
sessionOpts: {
52+
protocol: "http",
53+
hostname: "127.0.0.1",
54+
port: 62536,
55+
path: "/",
56+
strictSSL: true,
57+
},
58+
driverPid: 34985, // Very important parameter, need for kill driver process
59+
});
60+
61+
// Navigate to the URL and perform necessary actions
62+
await browser.url("https://example.com");
63+
64+
// !Important: terminate the session to prevent resource leaks (zombie processes)
65+
await browser.deleteSession();
66+
```
67+
68+
More info about [attachToBrowser](https://github.com/gemini-testing/testplane/blob/master/src/browser/standalone/attachToBrowser.ts)

‎i18n/ru/docusaurus-plugin-content-docs/current/command-line/index.mdx‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ import Admonition from "@theme/Admonition";
3030
--repl-on-fail [type] open repl interface on test fail only (default: false)
3131
--devtools switches the browser to the devtools mode with using CDP protocol
3232
--local use automatically downloaded browsers and drivers, provided by Testplane
33+
--keep-browser do not close browser session after test completion
34+
--keep-browser-on-fail do not close browser session when test fails
3335
-h, --help output usage information
3436
```
3537
@@ -185,6 +187,27 @@ testplane --repl --grep 'my test name' --browser chrome
185187
[switchToRepl][switch-to-repl].
186188
</Admonition>
187189
190+
#### Keep browser {#testplane-keep-browser}
191+
192+
- `--keep-browser` - в этом режиме браузер не закроется по завершению выполнения тестов, в консоли будет выведена информация как подключиться к оставшемуся браузеру
193+
- `--keep-browser-on-fail` - то же, что и опция `--keep-browser`, только браузер останется только в том случае, если тесты завершатся неуспешно
194+
195+
Пример вывода в консоли c информацией для подключения к браузеру
196+
```
197+
[15:44:38 +0700] Testplane run has finished, but the browser won't be closed, because you passed the --keep-browser argument.
198+
[15:44:38 +0700] You may attach to this browser using the following capabilities:
199+
[15:44:38 +0700] {
200+
"sessionId": "c69958b3f85b851f7bf83f27bb026d58",
201+
"sessionCaps": {
202+
"acceptInsecureCerts": false,
203+
...
204+
},
205+
"driverPid": 31745
206+
}
207+
[15:44:38 +0700] ✓ test example #0 [chrome:c69958b3f85b851f7bf83f27bb026d58, pid:31744] - 1676ms
208+
209+
```
210+
188211
#### Devtools {#testplane-devtools}
189212
190213
Запускает тесты Testplane с использованием [протокола автоматизации devtools][webdriver-vs-cdp].

‎i18n/ru/docusaurus-plugin-content-docs/current/reference/testplane-standalone-api.mdx‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Testplane standalone api
2+
3+
## Обзор
4+
5+
Standalone API позволяет напрямую из вашего кода запустить новый экземпляр браузера или подключиться к уже работающему, а затем выполнить в нём необходимые действия.
6+
7+
Внимание: на данный момент Standalone API находится в стадии разработки и его интерфейс может меняться. Пожалуйста, учитывайте это при использовании.
8+
9+
## Использование
10+
11+
### Запуск браузера
12+
13+
Запуск браузера с необходимыми параметрами.
14+
15+
```typescript
16+
import { launchBrowser } from "testplane/unstable";
17+
18+
// Запуск браузера с необходимыми параметрами
19+
const browser = await launchBrowser({
20+
desiredCapabilities: {
21+
browserName: 'chrome',
22+
},
23+
headless: false,
24+
});
25+
26+
// Переход по адресу и выполнение нужных действий
27+
await browser.url("https://example.com");
28+
29+
// !Важно: завершить сессию, чтобы избежать утечки ресурсов (зависших процессов)
30+
await browser.deleteSession();
31+
```
32+
33+
Подробнее о [launchBrowser](https://github.com/gemini-testing/testplane/blob/master/src/browser/standalone/launchBrowser.ts)
34+
35+
### Подключение к браузеру
36+
37+
Подключение к уже запущенному браузеру с помощью параметров сессии.
38+
Получить параметры сессии можно, запустив testplane с опцией `--keep-browser`, смотрите [подробнее](../command-line/index.mdx#testplane-keep-browser)
39+
40+
```typescript
41+
import { attachToBrowser } from "testplane/unstable";
42+
43+
// Attach to existing browser with session params
44+
const browser = await attachToBrowser({
45+
sessionId: "f1bd2b2bc6563f82d2120c31f4b92c03",
46+
sessionCaps: {
47+
browserName: "chrome",
48+
browserVersion: "137.0.7151.119",
49+
setWindowRect: true,
50+
},
51+
sessionOpts: {
52+
protocol: "http",
53+
hostname: "127.0.0.1",
54+
port: 62536,
55+
path: "/",
56+
strictSSL: true,
57+
},
58+
driverPid: 34985, // Очень важный параметр, нужен что бы завершить оставшиеся процессы
59+
});
60+
61+
// Переход по адресу и выполнение нужных действий
62+
await browser.url("https://example.com");
63+
64+
// !Важно: завершить сессию, чтобы избежать утечки ресурсов (зависших процессов)
65+
await browser.deleteSession();
66+
```
67+
68+
Подробнее о [attachToBrowser](https://github.com/gemini-testing/testplane/blob/master/src/browser/standalone/attachToBrowser.ts)

0 commit comments

Comments
 (0)