Merge pull request #119 from gemini-testing/TESTPLANE-939

feat(selectivity): update docs (modes, reportPath, merge-dumps)

Author: KuznetsovRoman

docs/guides/selectivity.mdx

@@ -40,6 +40,8 @@ Let’s enable selectivity in a project with `chrome` and `firefox` browsers. Fo
 
 ```ts
 // testplane.config.ts
+import { SelectivityMode } from "testplane";
+
 const DEV_SERVER_PORT = 3050;
 
 export default {
@@ -53,7 +55,7 @@ export default {
         },
     },
     selectivity: {
-        enabled: true,
+        enabled: SelectivityMode.Enabled,
     },
 } satisfies import("testplane").ConfigInput;
 ```

docs/reference/cli.mdx

@@ -698,7 +698,29 @@ All options can be overridden via command-line flags or environment variables wi
 
 -   The default value.
 
-### Overriding with CLI option {#overriding-cli-settings}
+## `selectivity-merge-dumps` command {#selectivity-merge-dumps}
+
+This command is useful when its needed to merge selectivity dumps from multiple chunks into a single one.
+
+### Usage {#usage}
+
+```bash
+npx testplane selectivity-merge-dumps ./selectivity-chunk-1 ./selectivity-chunk-2 ./selectivity-chunk-3 ./selectivity-chunk-4 -d ./selectivity-full
+npx testplane selectivity-merge-dumps -d ./selectivity-full ./selectivity-chunk-1 ./selectivity-chunk-2 ./selectivity-chunk-3 ./selectivity-chunk-4
+npx testplane selectivity-merge-dumps ./selectivity-chunk-1 ./selectivity-chunk-2 ./selectivity-chunk-3 ./selectivity-chunk-4
+```
+
+### Command options {#options}
+
+You can specify destination directory with "-d" ("--destination") argument.
+
+It can be omitted. In this case "testDependenciesPath" from "selectivity" config section will be used.
+
+### Command arguments {#arguments}
+
+List of paths to selectivity report chunks
+
+## Overriding with CLI option {#overriding-cli-settings}
 
 To override a config setting with a CLI option, convert the full option path to `--kebab-case`.
 
@@ -714,7 +736,7 @@ It also works for nested properties. Example of overriding `browsers.firefox.ses
 testplane path/to/mytest.js --browsers-firefox-sessions-per-browser 7
 ```
 
-### Overriding with environment variable {#overriding-env-settings}
+## Overriding with environment variable {#overriding-env-settings}
 
 To override a setting with an environment variable, convert its full path to `snake_case` and add the `testplane_` prefix.
 
@@ -727,7 +749,7 @@ testplane_browsers_firefox_sessions_per_browser=7 testplane path/to/mytest.js
 
 Besides overriding config values, there also two extra environment variables: "TESTPLANE_SKIP_BROWSERS" and "TESTPLANE_SETS":
 
-#### TESTPLANE_SKIP_BROWSERS
+### TESTPLANE_SKIP_BROWSERS
 
 Skip the browsers specified in the config by passing the browser IDs. Multiple browser IDs should be separated by commas
 (spaces after commas are allowed).
@@ -736,7 +758,7 @@ Skip the browsers specified in the config by passing the browser IDs. Multiple b
 TESTPLANE_SKIP_BROWSERS=ie10,ie11 testplane
 ```
 
-#### TESTPLANE_SETS
+### TESTPLANE_SETS
 
 Runs only specified sets (CLI option `--set` alternative).
 

docs/reference/config/browsers.mdx

@@ -1038,9 +1038,13 @@ The section has the following parameters:
     <tbody>
         <tr>
             <td>`enabled`</td>
-            <td>`boolean`</td>
-            <td>`false`</td>
-            <td>Enables selective test execution.</td>
+            <td>`SelectivityMode`</td>
+            <td>`SelectivityMode.Disabled`</td>
+            <td>
+                Available modes: `SelectivityMode.Disabled`, `SelectivityMode.Enabled`, `SelectivityMode.ReadOnly`, `SelectivityMode.WriteOnly`.
+                In `ReadOnly` mode unchanged tests are skipped, but selectivity dump is not updated after successful run.
+                In `WriteOnly` mode all tests are run, but selectivity dump is updated after successful run.
+            </td>
         </tr>
         <tr>
             <td>`sourceRoot`</td>
@@ -1078,6 +1082,12 @@ The section has the following parameters:
                 or filters it completely if `falsy` value is returned
             </td>
         </tr>
+        <tr>
+            <td>`reportPath`</td>
+            <td>`string`</td>
+            <td>`""`</td>
+            <td>If set, selectivity JSON-report will be saved to specified file path.</td>
+        </tr>
     </tbody>
 </table>
 

i18n/ru/docusaurus-plugin-content-docs/current/guides/selectivity.mdx

@@ -40,6 +40,8 @@ export default {
 
 ```ts
 // testplane.config.ts
+import { SelectivityMode } from "testplane";
+
 const DEV_SERVER_PORT = 3050;
 
 export default {
@@ -53,7 +55,7 @@ export default {
         },
     },
     selectivity: {
-        enabled: true,
+        enabled: SelectivityMode.Enabled,
     },
 } satisfies import("testplane").ConfigInput;
 ```

i18n/ru/docusaurus-plugin-content-docs/current/reference/cli.mdx

@@ -700,7 +700,29 @@ TESTPLANE_BROWSERS_PATH=~/.testplane npx testplane install-deps
 
 -   Значение по умолчанию.
 
-### Переопределение с помощью CLI опции {#overriding-cli-settings}
+## Команда `selectivity-merge-dumps` {#selectivity-merge-dumps}
+
+Эта команда полезна, когда необходимо объединить дампы селективности из нескольких частей (чанков) в один.
+
+### Использование {#usage}
+
+```bash
+npx testplane selectivity-merge-dumps ./selectivity-chunk-1 ./selectivity-chunk-2 ./selectivity-chunk-3 ./selectivity-chunk-4 -d ./selectivity-full
+npx testplane selectivity-merge-dumps -d ./selectivity-full ./selectivity-chunk-1 ./selectivity-chunk-2 ./selectivity-chunk-3 ./selectivity-chunk-4
+npx testplane selectivity-merge-dumps ./selectivity-chunk-1 ./selectivity-chunk-2 ./selectivity-chunk-3 ./selectivity-chunk-4
+```
+
+### Опции команды {#options}
+
+Вы можете указать директорию, в которую будет записан результат, с помощью аргумента "-d" ("--destination").
+
+Его можно не указывать. В этом случае будет использован "testDependenciesPath" из секции конфигурации "selectivity".
+
+### Аргументы команды {#arguments}
+
+Список путей к частям (чанкам) отчета селективности
+
+## Переопределение с помощью CLI опции {#overriding-cli-settings}
 
 Чтобы переопределить настройку в конфигурации с помощью опции CLI, преобразуйте полный путь параметра в `--kebab-case`.
 
@@ -716,7 +738,7 @@ testplane path/to/mytest.js --base-url http://example.com
 testplane path/to/mytest.js --browsers-firefox-sessions-per-browser 7
 ```
 
-### Переопределение с помощью переменной окружения {#overriding-env-settings}
+## Переопределение с помощью переменной окружения {#overriding-env-settings}
 
 Чтобы переопределить настройку с помощью переменной окружения, преобразуйте её полный путь в `snake_case` и добавьте префикс `testplane_`.
 
@@ -729,15 +751,15 @@ testplane_browsers_firefox_sessions_per_browser=7 testplane path/to/mytest.js
 
 Кроме переопределения значений конфигурации, существуют также две дополнительные переменные окружения: "TESTPLANE_SKIP_BROWSERS" и "TESTPLANE_SETS":
 
-#### TESTPLANE_SKIP_BROWSERS
+### TESTPLANE_SKIP_BROWSERS
 
 Пропустить браузеры, указанные в конфигурации, путем передачи идентификаторов браузеров. Несколько идентификаторов браузеров должны быть разделены запятыми (после запятых разрешены пробелы).
 
 ```bash
 TESTPLANE_SKIP_BROWSERS=ie10,ie11 testplane
 ```
 
-#### TESTPLANE_SETS
+### TESTPLANE_SETS
 
 Запускает только указанные наборы (альтернатива опции CLI `--set`).
 

i18n/ru/docusaurus-plugin-content-docs/current/reference/config/browsers.mdx

@@ -1042,9 +1042,13 @@ export = {
     <tbody>
         <tr>
             <td>`enabled`</td>
-            <td>`boolean`</td>
-            <td>`false`</td>
-            <td>Включает селективность запуска тестов.</td>
+            <td>`SelectivityMode`</td>
+            <td>`SelectivityMode.Disabled`</td>
+            <td>
+                Доступные режимы: `SelectivityMode.Disabled`, `SelectivityMode.Enabled`, `SelectivityMode.ReadOnly`, `SelectivityMode.WriteOnly`.
+                В режиме `ReadOnly`, нетронутые тесты не запускаются, но дамп селективности не обновляется после успешного запуска.
+                В режиме `WriteOnly` запускаются все тесты, но дамп селективности обновляетя после успешного запуска.
+            </td>
         </tr>
         <tr>
             <td>`sourceRoot`</td>
@@ -1081,6 +1085,12 @@ export = {
                 или полностью игнорирует зависимость, если возвращено `falsy` значение
             </td>
         </tr>
+        <tr>
+            <td>`reportPath`</td>
+            <td>`string`</td>
+            <td>`""`</td>
+            <td>Если указано, JSON-отчет о селективности будет сохранен в соответствующий файл.</td>
+        </tr>
     </tbody>
 </table>