From 1eaf0e4201bf16a1d167e8d3d2e92969b4ac6f12 Mon Sep 17 00:00:00 2001
From: DudaGod <dudkevich@yandex-team.ru>
Date: Mon, 8 Jul 2024 23:46:49 +0300
Subject: [PATCH] docs: add info about "passive" option and "testplane.also.in"
 helper

---
 docs/config.md        |  7 +++++++
 docs/writing-tests.md | 21 +++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/docs/config.md b/docs/config.md
index fdcc56a4c..7114edc10 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -56,6 +56,7 @@
   - [region](#region)
   - [headless](#headless)
   - [isolation](#isolation)
+  - [passive](#passive)
 - [system](#system)
   - [debug](#debug)
   - [mochaOpts](#mochaopts)
@@ -197,6 +198,7 @@ Option name               | Description
 `region`                  | Ability to choose different datacenters for run in cloud service. Default value is `null`.
 `headless`                | Ability to run headless browser in cloud service. Default value is `null`.
 `isolation`               | Ability to execute tests in isolated clean-state environment ([incognito browser context](https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-createBrowserContext)). Default value is `false`, but `true` for chrome@93 and higher.
+`passive`                 | Ability to make browser passive. Tests are not run in passive browsers by default. Default value is `false`.
 
 #### desiredCapabilities
 **Required.** Used WebDriver [DesiredCapabilities](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities). For example,
@@ -491,6 +493,11 @@ Ability to run headless browser in cloud service. Default value is `null`. Can b
 ####  isolation
 Ability to execute tests in isolated clean-state environment ([incognito browser context](https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-createBrowserContext)). It means that `testsPerSession` can be set to `Infinity` in order to speed up tests execution and save browser resources. Currently works only in chrome@93 and higher. Default value is `null`, but `true` for chrome@93 and higher.
 
+#### passive
+Ability to make browser passive. Tests are not run in passive browsers by default. Using [testplane.also.in](./writing-tests.md#also) makes it possible to run test or suite before which it is specified.
+
+:warning: When using this option, you need to get rid of the [hermione-passive-browsers](https://github.com/gemini-testing/testplane-passive-browsers) plugin, since they work together incorrectly.
+
 ### system
 
 #### debug
diff --git a/docs/writing-tests.md b/docs/writing-tests.md
index 1040dcea4..4b5c6c1e6 100644
--- a/docs/writing-tests.md
+++ b/docs/writing-tests.md
@@ -174,6 +174,27 @@ it('should work another way', function() {
 ```
 The test will be processed in all browsers and **silently** skipped in `ie9`.
 
+### Also
+This feature allows you to run the specified suite or test in [passive browser](./config.md#passive).
+You can do this by using the global `testplane.also` helper. It supports the following methods:
+
+- `.in` – Adds matchers for browsers.
+
+These methods take the following arguments:
+
+- browser {String|RegExp|Array<String|RegExp>} — A matcher for browser(s) to enable test.
+
+For example:
+```js
+// ...
+testplane.also.in('yabro');
+
+it('should run in passive browser', function() {
+    return doSomething();
+});
+```
+The test will be run in passive browser "yabro" and in all other not passive browsers.
+
 ### Config overriding
 You can override some config settings for specific test, suite or hook via `testplane.config.*` notation.