Merge pull request #126 from gemini-testing/TESTPLANE-981

docs(selectivity): mapSourceMapUrl + recover failed docs

Author: KuznetsovRoman

docs/guides/selectivity.mdx

@@ -17,7 +17,10 @@ After a file changes, on the next run only those tests that depend on the change
 
 <Admonition type="info">
     If at least one test fails, then on the next run all the same tests will be executed again —
-    Testplane will "remember" the new state only after a fully successful run.
+    Testplane will "remember" the new state only after a fully successful run. However, you can use
+    [`saveIncompleteDumpOnFail`][selectivity-config] to save the dump even on failure and then
+    complete it by re-running only the failed tests. See [Recovering from a failed selectivity
+    run](#recovering-incomplete-dump) below.
 </Admonition>
 
 ## Setup
@@ -222,9 +225,53 @@ You can also disable selectivity manually using an environment variable:
 testplane_selectivity_enabled=false # disable
 ```
 
+## Recovering from a failed selectivity run {#recovering-incomplete-dump}
+
+By default, if any test fails during a Testplane run, the selectivity dump is **not updated**. This means that if you ran Testplane to collect a selectivity dump (e.g. in CI) and only a few tests failed, you would need to re-run the **entire** test suite just to get a valid dump.
+
+The `saveIncompleteDumpOnFail` option solves this problem. Here is the step-by-step workflow:
+
+### 1. Run Testplane with `saveIncompleteDumpOnFail: true`
+
+Enable selectivity in `enabled` or `writeOnly` mode with `saveIncompleteDumpOnFail: true` in your config:
+
+```typescript
+selectivity: {
+    enabled: true, // or "writeOnly"
+    saveIncompleteDumpOnFail: true,
+}
+```
+
+Run Testplane as usual. If some tests fail, the dump will still be saved — but it is in an **incomplete state**. An incomplete dump may incorrectly skip some of the failed tests, so it should **not** be used directly for selective runs.
+
+### 2. Re-run only the failed tests
+
+Use the [`--last-failed-only`][last-failed] flag to re-run only the tests that failed:
+
+```bash
+npx testplane --last-failed-only
+```
+
+Make sure `saveIncompleteDumpOnFail: true` is still set in the config. This run will only execute the previously failed tests and update the incomplete dump with their results.
+
+### 3. Repeat until all tests pass
+
+You can repeat step 2 multiple times if needed — for example, if some tests are flaky and fail again. Each subsequent `--last-failed-only` run updates the dump incrementally.
+
+### 4. Dump is complete
+
+Once a run succeeds with no failures, the dump is considered **complete** and can safely be used for selective test execution.
+
+<Admonition type="warning">
+    Do not use the incomplete dump (saved after a failed run) for selective test execution. An
+    incomplete dump may skip tests that actually need to be re-run. Always complete the dump by
+    re-running failed tests until the run is fully successful.
+</Admonition>
+
 ## Configuration
 
 Additional information about selectivity configuration is provided in the [browsers-selectivity][selectivity-config] section of the documentation.
 
 [dev-server]: ../../reference/config/dev-server
 [selectivity-config]: ../../reference/config/browsers#selectivity
+[last-failed]: ../../reference/config/last-failed

docs/reference/config/browsers.mdx

@@ -1075,11 +1075,33 @@ The section has the following parameters:
         </tr>
         <tr>
             <td>`mapDependencyRelativePath`</td>
-            <td>`null | (dependency: { scope: "browser" | "testplane", relativePath: string }) => string | void`</td>
+            <td>`null | (dependency: { scope: "browser" | "testplane", relativePath: string }) => string | boolean | void`</td>
             <td>`null`</td>
             <td>
-                Callback, which accepts test dependency path in POSIX style and maps it to another path
-                or filters it completely if `falsy` value is returned
+                Callback, which accepts test dependency path in POSIX style and maps it to another path.
+                Return a mapped `string` path to remap, `true` to keep the original path unchanged,
+                or a falsy value (`false`, `undefined`, `void`) to filter the dependency out completely.
+            </td>
+        </tr>
+        <tr>
+            <td>`mapSourceMapUrl`</td>
+            <td>`null | (assetInfo: { type: "css" | "js", sourceUrl: string, sourceMapUrl: string }) => string | boolean | void`</td>
+            <td>`null`</td>
+            <td>
+                Callback to filter or remap source map URLs before they are fetched.
+                Return a mapped `string` URL to remap, `true` to keep the original URL unchanged,
+                or a falsy value to skip the asset entirely (both the script/style and its source map will be ignored).
+            </td>
+        </tr>
+        <tr>
+            <td>`saveIncompleteDumpOnFail`</td>
+            <td>`boolean`</td>
+            <td>`false`</td>
+            <td>
+                When `true`, selectivity dump is saved even if some tests failed.
+                This allows you to later rerun only the failed tests with
+                [`--last-failed-only`][last-failed] to complete the dump without re-running the entire suite.
+                See the [guide on recovering from a failed selectivity run][selectivity-incomplete-dump-guide].
             </td>
         </tr>
         <tr>
@@ -1133,6 +1155,44 @@ The section has the following parameters:
 }
 ```
 
+### `mapSourceMapUrl` examples {#mapSourceMapUrl_examples}
+
+#### Filter out third-party scripts {#mapSourceMapUrl_example_filter}
+
+```ts
+{
+    selectivity: {
+        enabled: true,
+        mapSourceMapUrl({ type, sourceUrl, sourceMapUrl }) {
+            // Skip analytics and tracking scripts
+            if (sourceUrl.includes("analytics") || sourceUrl.includes("tracking")) {
+                return false;
+            }
+
+            return true;
+        },
+    }
+}
+```
+
+#### Remap source map URL to a local server {#mapSourceMapUrl_example_remap}
+
+```ts
+{
+    selectivity: {
+        enabled: true,
+        mapSourceMapUrl({ type, sourceUrl, sourceMapUrl }) {
+            // Redirect source map fetching to a local server
+            if (sourceMapUrl.startsWith("https://cdn.example.com/")) {
+                return sourceMapUrl.replace("https://cdn.example.com/", "http://localhost:3000/");
+            }
+
+            return true;
+        },
+    }
+}
+```
+
 <Admonition type="info">
     You should not specify `node_modules` in `disableSelectivityPatterns`, as this will cause a
     significant slowdown. Instead, it is recommended to specify Testplane configuration files and
@@ -1207,3 +1267,5 @@ export = {
 [restoreState]: ../../../commands/browser/restoreState
 [getState]: ../../../commands/browser/getState
 [url-resolve]: https://nodejs.org/api/url.html#urlresolvefrom-to
+[last-failed]: ../last-failed
+[selectivity-incomplete-dump-guide]: ../../../guides/selectivity#recovering-incomplete-dump

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

@@ -17,7 +17,10 @@ import Admonition from "@theme/Admonition";
 
 <Admonition type="info">
     Если хотя бы один тест упадет, то при следующем прогоне будут запущены все те же тесты —
-    Testplane "запомнит" новое состояние только после полностью успешного прогона.
+    Testplane "запомнит" новое состояние только после полностью успешного прогона. Однако вы можете
+    использовать [`saveIncompleteDumpOnFail`][selectivity-config] для сохранения дампа даже при
+    падении и затем дополнить его, перезапустив только упавшие тесты. См. [Восстановление после
+    неудачного прогона селективности](#recovering-incomplete-dump) ниже.
 </Admonition>
 
 ## Настройка
@@ -222,9 +225,53 @@ selectivity: {
 testplane_selectivity_enabled=false # отключить
 ```
 
+## Восстановление после неудачного прогона селективности {#recovering-incomplete-dump}
+
+По умолчанию, если хотя бы один тест упал во время прогона Testplane, дамп селективности **не обновляется**. Это означает, что если вы запускали Testplane для сбора дампа селективности (например, в CI) и упало лишь несколько тестов, вам пришлось бы перезапускать **весь** набор тестов для получения валидного дампа.
+
+Опция `saveIncompleteDumpOnFail` решает эту проблему. Вот пошаговый процесс:
+
+### 1. Запустите Testplane с `saveIncompleteDumpOnFail: true`
+
+Включите селективность в режиме `enabled` или `writeOnly` с `saveIncompleteDumpOnFail: true` в конфигурации:
+
+```typescript
+selectivity: {
+    enabled: true, // или "writeOnly"
+    saveIncompleteDumpOnFail: true,
+}
+```
+
+Запустите Testplane как обычно. Если некоторые тесты упадут, дамп все равно будет сохранен — но в **неполном состоянии**. Неполный дамп может некорректно пропускать некоторые из упавших тестов, поэтому его **нельзя** использовать напрямую для селективных прогонов.
+
+### 2. Перезапустите только упавшие тесты
+
+Используйте флаг [`--last-failed-only`][last-failed] для перезапуска только упавших тестов:
+
+```bash
+npx testplane --last-failed-only
+```
+
+Убедитесь, что `saveIncompleteDumpOnFail: true` по-прежнему установлен в конфигурации. Этот запуск выполнит только ранее упавшие тесты и обновит неполный дамп их результатами.
+
+### 3. Повторяйте до полного успеха
+
+Вы можете повторять шаг 2 несколько раз — например, если некоторые тесты нестабильны и падают снова. Каждый последующий запуск с `--last-failed-only` инкрементально обновляет дамп.
+
+### 4. Дамп готов
+
+Как только прогон завершится без падений, дамп считается **полным** и может безопасно использоваться для селективного запуска тестов.
+
+<Admonition type="warning">
+    Не используйте неполный дамп (сохраненный после неудачного прогона) для селективного запуска
+    тестов. Неполный дамп может пропускать тесты, которые на самом деле нужно перезапустить. Всегда
+    дополняйте дамп, перезапуская упавшие тесты до полностью успешного прогона.
+</Admonition>
+
 ## Конфигурация
 
 Дополнительная информация о конфигурации селективности описана в разделе [browsers-selectivity][selectivity-config] документации.
 
 [dev-server]: ../../reference/config/dev-server
 [selectivity-config]: ../../reference/config/browsers#selectivity
+[last-failed]: ../../reference/config/last-failed

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

@@ -1078,11 +1078,33 @@ export = {
         </tr>
         <tr>
             <td>`mapDependencyRelativePath`</td>
-            <td>`null | (dependency: { scope: "browser" | "testplane", relativePath: string }) => string | void`</td>
+            <td>`null | (dependency: { scope: "browser" | "testplane", relativePath: string }) => string | boolean | void`</td>
             <td>`null`</td>
             <td>
-                Коллбэк, который принимает путь зависимости теста в стиле POSIX и преобразует его в другой путь
-                или полностью игнорирует зависимость, если возвращено `falsy` значение
+                Коллбэк, который принимает путь зависимости теста в стиле POSIX и преобразует его в другой путь.
+                Верните строку `string` для переназначения пути, `true` для сохранения исходного пути без изменений,
+                или falsy-значение (`false`, `undefined`, `void`) для полного исключения зависимости.
+            </td>
+        </tr>
+        <tr>
+            <td>`mapSourceMapUrl`</td>
+            <td>`null | (assetInfo: { type: "css" | "js", sourceUrl: string, sourceMapUrl: string }) => string | boolean | void`</td>
+            <td>`null`</td>
+            <td>
+                Коллбэк для фильтрации или переназначения URL-адресов source map перед их загрузкой.
+                Верните строку `string` для переназначения URL, `true` для сохранения исходного URL без изменений,
+                или falsy-значение для полного пропуска ресурса (и скрипт/стиль, и его source map будут проигнорированы).
+            </td>
+        </tr>
+        <tr>
+            <td>`saveIncompleteDumpOnFail`</td>
+            <td>`boolean`</td>
+            <td>`false`</td>
+            <td>
+                Если `true`, дамп селективности сохраняется даже при падении некоторых тестов.
+                Это позволяет затем перезапустить только упавшие тесты с помощью
+                [`--last-failed-only`][last-failed] для дополнения дампа без полного перезапуска всех тестов.
+                См. [руководство по восстановлению после неудачного прогона селективности][selectivity-incomplete-dump-guide].
             </td>
         </tr>
         <tr>
@@ -1136,6 +1158,44 @@ export = {
 }
 ```
 
+### Примеры `mapSourceMapUrl` {#mapSourceMapUrl_examples}
+
+#### Фильтрация сторонних скриптов {#mapSourceMapUrl_example_filter}
+
+```ts
+{
+    selectivity: {
+        enabled: true,
+        mapSourceMapUrl({ type, sourceUrl, sourceMapUrl }) {
+            // Пропускаем скрипты аналитики и трекинга
+            if (sourceUrl.includes("analytics") || sourceUrl.includes("tracking")) {
+                return false;
+            }
+
+            return true;
+        },
+    }
+}
+```
+
+#### Переназначение URL source map на локальный сервер {#mapSourceMapUrl_example_remap}
+
+```ts
+{
+    selectivity: {
+        enabled: true,
+        mapSourceMapUrl({ type, sourceUrl, sourceMapUrl }) {
+            // Перенаправляем загрузку source map на локальный сервер
+            if (sourceMapUrl.startsWith("https://cdn.example.com/")) {
+                return sourceMapUrl.replace("https://cdn.example.com/", "http://localhost:3000/");
+            }
+
+            return true;
+        },
+    }
+}
+```
+
 <Admonition type="info">
     В `disableSelectivityPatterns` не стоит указывать `node_modules` - это приведет к ощутимому
     замедлению. Вместо этого, рекомендуется указать конфигурационные файлы Testplane и исходный код
@@ -1209,3 +1269,5 @@ export = {
 [saveState]: .../../../../../commands/browser/saveState
 [restoreState]: .../../../../../commands/browser/restoreState
 [getState]: .../../../../../commands/browser/getState
+[last-failed]: ../last-failed
+[selectivity-incomplete-dump-guide]: ../../../guides/selectivity#recovering-incomplete-dump