Docs for keep-browser and standalone api (#87)

feat(testplane-docs): docs for keep-browser and standalone api

Author: sonic16x

docs/command-line/index.mdx

@@ -30,6 +30,8 @@ Main command to run tests.
     --repl-on-fail [type]            open repl interface on test fail only (default: false)
     --devtools                       switches the browser to the devtools mode with using CDP protocol
     --local                          use automatically downloaded browsers and drivers, provided by Testplane
+    --keep-browser                   do not close browser session after test completion
+    --keep-browser-on-fail           do not close browser session when test fails
     -h, --help                       output usage information
 ```
 
@@ -184,6 +186,27 @@ testplane --repl --grep 'my test name' --browser chrome
     command documentation.
 </Admonition>
 
+#### Keep browser {#testplane-keep-browser}
+
+-   `--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.
+-   `--keep-browser-on-fail` - the same as the `--keep-browser` option, but the browser will only remain open if the tests fail.
+
+Example of console output with connection information to the browser:
+```
+[15:44:38 +0700] Testplane run has finished, but the browser won't be closed, because you passed the --keep-browser argument.
+[15:44:38 +0700] You may attach to this browser using the following capabilities:
+[15:44:38 +0700] {
+  "sessionId": "c69958b3f85b851f7bf83f27bb026d58",
+  "sessionCaps": {
+    "acceptInsecureCerts": false,
+    ...
+  },
+  "driverPid": 31745
+}
+[15:44:38 +0700] ✓ test example #0 [chrome:c69958b3f85b851f7bf83f27bb026d58, pid:31744] - 1676ms
+
+```
+
 #### Devtools {#testplane-devtools}
 
 Runs Testplane tests using [devtools automation protocol][webdriver-vs-cdp].

docs/reference/testplane-standalone-api.mdx

@@ -0,0 +1,68 @@
+# Testplane standalone api
+
+## Overview
+
+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.
+
+Please note: The Standalone API is currently unstable and its interface is subject to change. Please keep this in mind when using it.
+
+## Usage
+
+### Launch browser
+
+Launching the browser with the necessary parameters
+
+```typescript
+import { launchBrowser } from "testplane/unstable";
+
+// Launch a new browser with the given settings
+const browser = await launchBrowser({
+    desiredCapabilities: {
+        browserName: 'chrome',
+    },
+    headless: false,
+});
+
+// Navigate to the URL and perform necessary actions
+await browser.url("https://example.com");
+
+// !Important: terminate the session to prevent resource leaks (zombie processes)
+await browser.deleteSession();
+```
+
+More info about [launchBrowser](https://github.com/gemini-testing/testplane/blob/master/src/browser/standalone/launchBrowser.ts)
+
+### Attach to browser
+
+Attach to the existing browser with session params.
+You can get session params if run testplane with `--keep-browser` option, see [more](../command-line/index.mdx#testplane-keep-browser)
+
+```typescript
+import { attachToBrowser } from "testplane/unstable";
+
+// Attach to existing browser with session params
+const browser = await attachToBrowser({
+    sessionId: "f1bd2b2bc6563f82d2120c31f4b92c03",
+    sessionCaps: {
+        browserName: "chrome",
+        browserVersion: "137.0.7151.119",
+        setWindowRect: true,
+    },
+    sessionOpts: {
+        protocol: "http",
+        hostname: "127.0.0.1",
+        port: 62536,
+        path: "/",
+        strictSSL: true,
+    },
+    driverPid: 34985, // Very important parameter, need for kill driver process
+});
+
+// Navigate to the URL and perform necessary actions
+await browser.url("https://example.com");
+
+// !Important: terminate the session to prevent resource leaks (zombie processes)
+await browser.deleteSession();
+```
+
+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

@@ -30,6 +30,8 @@ import Admonition from "@theme/Admonition";
     --repl-on-fail [type]            open repl interface on test fail only (default: false)
     --devtools                       switches the browser to the devtools mode with using CDP protocol
     --local                          use automatically downloaded browsers and drivers, provided by Testplane
+    --keep-browser                   do not close browser session after test completion
+    --keep-browser-on-fail           do not close browser session when test fails
     -h, --help                       output usage information
 ```
 
@@ -185,6 +187,27 @@ testplane --repl --grep 'my test name' --browser chrome
     [switchToRepl][switch-to-repl].
 </Admonition>
 
+#### Keep browser {#testplane-keep-browser}
+
+-   `--keep-browser` - в этом режиме браузер не закроется по завершению выполнения тестов, в консоли будет выведена информация как подключиться к оставшемуся браузеру
+-   `--keep-browser-on-fail` - то же, что и опция `--keep-browser`, только браузер останется только в том случае, если тесты завершатся неуспешно
+
+Пример вывода в консоли c информацией для подключения к браузеру
+```
+[15:44:38 +0700] Testplane run has finished, but the browser won't be closed, because you passed the --keep-browser argument.
+[15:44:38 +0700] You may attach to this browser using the following capabilities:
+[15:44:38 +0700] {
+  "sessionId": "c69958b3f85b851f7bf83f27bb026d58",
+  "sessionCaps": {
+    "acceptInsecureCerts": false,
+    ...
+  },
+  "driverPid": 31745
+}
+[15:44:38 +0700] ✓ test example #0 [chrome:c69958b3f85b851f7bf83f27bb026d58, pid:31744] - 1676ms
+
+```
+
 #### Devtools {#testplane-devtools}
 
 Запускает тесты Testplane с использованием [протокола автоматизации devtools][webdriver-vs-cdp].

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

@@ -0,0 +1,68 @@
+# Testplane standalone api
+
+## Обзор
+
+Standalone API позволяет напрямую из вашего кода запустить новый экземпляр браузера или подключиться к уже работающему, а затем выполнить в нём необходимые действия.
+
+Внимание: на данный момент Standalone API находится в стадии разработки и его интерфейс может меняться. Пожалуйста, учитывайте это при использовании.
+
+## Использование
+
+### Запуск браузера
+
+Запуск браузера с необходимыми параметрами.
+
+```typescript
+import { launchBrowser } from "testplane/unstable";
+
+// Запуск браузера с необходимыми параметрами
+const browser = await launchBrowser({
+    desiredCapabilities: {
+        browserName: 'chrome',
+    },
+    headless: false,
+});
+
+// Переход по адресу и выполнение нужных действий
+await browser.url("https://example.com");
+
+// !Важно: завершить сессию, чтобы избежать утечки ресурсов (зависших процессов)
+await browser.deleteSession();
+```
+
+Подробнее о [launchBrowser](https://github.com/gemini-testing/testplane/blob/master/src/browser/standalone/launchBrowser.ts)
+
+### Подключение к браузеру
+
+Подключение к уже запущенному браузеру с помощью параметров сессии.
+Получить параметры сессии можно, запустив testplane с опцией `--keep-browser`, смотрите [подробнее](../command-line/index.mdx#testplane-keep-browser)
+
+```typescript
+import { attachToBrowser } from "testplane/unstable";
+
+// Attach to existing browser with session params
+const browser = await attachToBrowser({
+    sessionId: "f1bd2b2bc6563f82d2120c31f4b92c03",
+    sessionCaps: {
+        browserName: "chrome",
+        browserVersion: "137.0.7151.119",
+        setWindowRect: true,
+    },
+    sessionOpts: {
+        protocol: "http",
+        hostname: "127.0.0.1",
+        port: 62536,
+        path: "/",
+        strictSSL: true,
+    },
+    driverPid: 34985, // Очень важный параметр, нужен что бы завершить оставшиеся процессы
+});
+
+// Переход по адресу и выполнение нужных действий
+await browser.url("https://example.com");
+
+// !Важно: завершить сессию, чтобы избежать утечки ресурсов (зависших процессов)
+await browser.deleteSession();
+```
+
+Подробнее о [attachToBrowser](https://github.com/gemini-testing/testplane/blob/master/src/browser/standalone/attachToBrowser.ts)