feat(plugins): unify screenshot/pause/aiTrace/heal under shared on= parameter (#5542)

* update docs

* updated docs, added browser plugin

* feat(plugins): unify screenshot/pause/aiTrace/heal under shared on= parameter

Adds a shared lib/utils/pluginParser.js with key=value parsing (`:` and `;`
separators) and a `resolveTrigger` helper. Renames screenshotOnFail → screenshot
and consolidates pauseOn/pauseOnFail → pause; aiTrace and heal grow `on=` filters.
Old plugin names live on as deprecated alias shims that warn and forward.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(plugins): drop pauseOn/stepByStepReport, fold slides into screenshot

- Remove lib/plugin/pauseOn.js (never shipped in a public release).
- Remove lib/plugin/stepByStepReport.js; slideshow generation moves into the
  screenshot plugin behind slides=true (e.g. -p screenshot:on=step;slides=true)
  with a modern, vanilla-CSS dark UI — no Bootstrap, no jQuery.
- Drop the redundant screenshot blocks from the acceptance test configs; the
  default in lib/config.js already enables screenshot with on=fail.
- Strip allure mentions from plugin code and plugin docs; refresh PR template,
  migration guide, debugging guide, plugins index, and commands docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(plugins): centralize on= validation in resolveTrigger

resolveTrigger now takes { name, validModes }, performs the unknown-mode
and missing-path/pattern checks itself, prints the error via output.error,
and returns null. Each plugin shrinks to one call + early-return; heal
passes its narrower mode list as { validModes: ['fail', 'file', 'url'] }.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: DavertMik <davert@testomat.io>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.github/PULL_REQUEST_TEMPLATE.md

@@ -13,18 +13,17 @@ Applicable helpers:
 
 Applicable plugins:
 
-- [ ] allure
+- [ ] aiTrace
 - [ ] autoDelay
 - [ ] autoLogin
 - [ ] customLocator
-- [ ] pauseOnFail
+- [ ] pause
 - [ ] coverage
+- [ ] heal
 - [ ] retryFailedStep
-- [ ] screenshotOnFail
+- [ ] screenshot
 - [ ] selenoid
-- [ ] stepByStepReport
 - [ ] stepTimeout
-- [ ] wdio
 - [ ] subtitles
 
 ## Type of change

docs/commands.md

@@ -115,10 +115,10 @@ Plugins listed via `-p` are activated even when their config has `enabled: false
 A few examples:
 
 ```sh
-npx codeceptjs run -p pauseOnFail                  # pause on first failure
-npx codeceptjs run -p pauseOn:step                 # pause before every step
-npx codeceptjs run -p pauseOn:url:/checkout/*      # pause on URL match
-npx codeceptjs run -p stepByStepReport             # produce a step-by-step HTML report
+npx codeceptjs run -p pause                              # pause on first failure (default on=fail)
+npx codeceptjs run -p pause:on=step                      # pause before every step
+npx codeceptjs run -p pause:on=url:pattern=/checkout/*   # pause on URL match
+npx codeceptjs run -p "screenshot:on=step;slides=true"   # produce a step-by-step HTML report
 ```
 
 ### Browser Control

docs/configuration.md

@@ -194,13 +194,14 @@ import { setCommonPlugins } from '@codeceptjs/configure'
 setCommonPlugins()
 ```
 
-| Plugin             | Default        | Notes                                                                          |
-| :----------------- | :------------- | :----------------------------------------------------------------------------- |
-| `retryFailedStep`  | enabled        | Retry steps that fail with transient errors                                    |
-| `screenshotOnFail` | enabled        | Capture a screenshot when a test fails                                         |
-| `pauseOn`          | registered     | Pause on failure / step / file / URL — `-p pauseOn:fail`, `-p pauseOn:step`, `-p pauseOn:file:tests/login_test.js`, `-p pauseOn:url:/checkout/*` |
-| `browser`          | registered     | CLI overrides for browser helpers — `-p browser:show`, `-p browser:browser=firefox`, see [commands](/commands#browser-control) |
-| `aiTrace`          | registered     | Capture AI traces — `-p aiTrace`                                               |
+| Plugin            | Default        | Notes                                                                          |
+| :---------------- | :------------- | :----------------------------------------------------------------------------- |
+| `retryFailedStep` | enabled        | Retry steps that fail with transient errors                                    |
+| `screenshot`      | enabled        | Screenshot on `fail` (default) / `test` / `step` / `file` / `url`              |
+| `pause`           | registered     | Pause on failure / step / file / URL — `-p pause:on=fail`, `-p pause:on=step`, `-p pause:on=file:path=tests/login_test.js`, `-p pause:on=url:pattern=/checkout/*` |
+| `browser`         | registered     | CLI overrides for browser helpers — `-p browser:show`, `-p browser:browser=firefox`, see [commands](/commands#browser-control) |
+| `aiTrace`         | registered     | Capture AI traces — `-p aiTrace`, narrow with `on=fail|test|step|file|url`     |
+| `heal`            | registered     | Self-heal failing steps — `-p heal`, narrow with `on=file|url`                 |
 
 > `eachElement`, `tryTo`, and `retryTo` are no longer plugins in 4.x — import them from `codeceptjs/effects`.
 

docs/debugging.md

@@ -107,28 +107,30 @@ After(({ I }) => {
 })
 ```
 
-## Pause On Plugin
+## Pause Plugin
 
-For automated debugging without modifying test code, use the `pauseOn` plugin. It pauses tests based on different triggers, controlled entirely from the command line.
+For automated debugging without modifying test code, use the `pause` plugin. It pauses tests based on different triggers, controlled entirely from the command line. The default is `on=fail`.
 
 ### Pause on Failure
 
 Automatically enters interactive pause when a step fails:
 
 ```bash
-npx codeceptjs run -p pauseOn:fail
+npx codeceptjs run -p pause
+# or, explicit:
+npx codeceptjs run -p pause:on=fail
 ```
 
 This is the most common debug workflow — run your tests, and when one fails, you land in the interactive shell with the browser in the exact state of the failure. You can inspect elements, try different selectors, and figure out what went wrong.
 
-> The older `pauseOnFail` plugin still works: `npx codeceptjs run -p pauseOnFail`
+> The legacy `pauseOnFail` plugin still works as a deprecated alias.
 
 ### Pause on Every Step
 
 Enters interactive pause at the start of the test. Use *ENTER* to advance step by step:
 
 ```bash
-npx codeceptjs run -p pauseOn:step
+npx codeceptjs run -p pause:on=step
 ```
 
 This gives you full step-by-step execution. After each step, you're back in the interactive shell where you can inspect the page before pressing ENTER to continue.
@@ -138,13 +140,13 @@ This gives you full step-by-step execution. After each step, you're back in the
 Pauses when execution reaches a specific file:
 
 ```bash
-npx codeceptjs run -p pauseOn:file:tests/login_test.js
+npx codeceptjs run -p pause:on=file:path=tests/login_test.js
 ```
 
 With a specific line number:
 
 ```bash
-npx codeceptjs run -p pauseOn:file:tests/login_test.js:43
+npx codeceptjs run -p pause:on=file:path=tests/login_test.js;line=43
 ```
 
 This works like a breakpoint — the test runs normally until it hits a step defined at that file and line, then opens the interactive shell.
@@ -154,14 +156,14 @@ This works like a breakpoint — the test runs normally until it hits a step def
 Pauses when the browser navigates to a matching URL:
 
 ```bash
-npx codeceptjs run -p pauseOn:url:/users/1
+npx codeceptjs run -p pause:on=url:pattern=/users/1
 ```
 
 Supports `*` wildcards:
 
 ```bash
-npx codeceptjs run -p pauseOn:url:/api/*/edit
-npx codeceptjs run -p pauseOn:url:/checkout/*
+npx codeceptjs run -p pause:on=url:pattern=/api/*/edit
+npx codeceptjs run -p pause:on=url:pattern=/checkout/*
 ```
 
 This is useful when you want to inspect a specific page regardless of which test step navigates there.
@@ -243,15 +245,16 @@ Enabled by default. Saves a screenshot when a test fails:
 
 ```js
 plugins: {
-  screenshotOnFail: {
+  screenshot: {
     enabled: true,
+    on: 'fail',
     uniqueScreenshotNames: true,
     fullPageScreenshots: true,
   }
 }
 ```
 
-Screenshots are saved in the `output` directory.
+Screenshots are saved in the `output` directory. The same plugin also supports `on=test`, `on=step`, `on=file`, and `on=url` to capture screenshots in other situations.
 
 ### Page Info on Failure
 
@@ -267,20 +270,22 @@ plugins: {
 
 ### Step-by-Step Report
 
-Generates a slideshow of screenshots taken after every step — a visual replay of what the test did:
+Generates a slideshow of screenshots taken after every step — a visual replay of what the test did. Set `slides: true` on the `screenshot` plugin (with `on=step`):
 
 ```js
 plugins: {
-  stepByStepReport: {
+  screenshot: {
     enabled: true,
+    on: 'step',
+    slides: true,
     deleteSuccessful: true,   // keep only failed tests
     fullPageScreenshots: true,
   }
 }
 ```
 
 ```bash
-npx codeceptjs run -p stepByStepReport
+npx codeceptjs run -p screenshot:on=step;slides=true
 ```
 
 After the run, open `output/records.html` to browse through the slideshows.

docs/migration-4.md

@@ -187,10 +187,21 @@ plugins: {
 
 Inject `login` and call `login('admin')` — same as before.
 
+### Renamed Plugins
+
+4.x unifies four plugins (`screenshot`, `pause`, `aiTrace`, `heal`) under a shared `on=` parameter. The old names live on as deprecated aliases that emit a warning and forward to the new plugin.
+
+| Old plugin          | New plugin                       | Notes                                              |
+| :------------------ | :------------------------------- | :------------------------------------------------- |
+| `screenshotOnFail`  | `screenshot`                     | Default `on='fail'`, same behavior                 |
+| `pauseOnFail`       | `pause`                          | Default `on='fail'`, same behavior                 |
+| `stepByStepReport`  | `screenshot` with `slides: true` | Use `on=step` to capture every step                |
+
 ### New Plugins You Can Enable
 
 - **`aiTrace`** — captures failure traces (DOM, console, network, screenshots) for AI debugging. See [AI Trace](/aitrace).
-- **`pauseOn`** — pauses execution on a chosen event or on failure. See [Debugging](/debugging).
+- **`pause`** — pauses execution on a chosen event or on failure. See [Debugging](/debugging).
+- **`heal`** — self-heals failing steps with AI; narrow with `on=file|url`.
 
 ## 5. Update Removed and Changed APIs
 
@@ -455,13 +466,16 @@ I.fillField('input', 'x', step.opts({ elementIndex: -1 }))
 `-p` accepts colon-chained arguments, so plugins can be enabled and configured from the command line without editing config:
 
 ```bash
-npx codeceptjs run -p pauseOn:fail              # pause on every failure
-npx codeceptjs run -p pauseOn:url:/checkout/*   # pause when URL matches
-npx codeceptjs run -p browser:show              # force visible browser
+npx codeceptjs run -p pause                                   # pause on every failure
+npx codeceptjs run -p pause:on=url:pattern=/checkout/*        # pause when URL matches
+npx codeceptjs run -p screenshot:on=step                      # screenshot every step
+npx codeceptjs run -p browser:show                            # force visible browser
 npx codeceptjs run -p browser:browser=firefox:windowSize=1024x768
-npx codeceptjs run -p plugin1,plugin2:arg       # multiple plugins
+npx codeceptjs run -p plugin1,plugin2:arg                     # multiple plugins
 ```
 
+Each argument after the plugin name is a `key=value` pair. `:` separates pairs. `;` is an inline alternative for visually grouping related pairs (e.g. `path=...;line=...`). Reserved keys: `on`, `path`, `line`, `pattern`.
+
 The `browser` plugin is new in 4.x — it overrides the active browser helper (Playwright, Puppeteer, WebDriver, Appium) from the CLI, useful for ad-hoc local runs and CI matrices. See [Commands](/commands).
 
 The old `-p all` magic keyword is gone (it conflicted with the colon syntax). Enable specific plugins explicitly: `-p pluginA,pluginB`.

docs/plugins.md

@@ -595,47 +595,42 @@ Additional config options:
 
 *   `config`   (optional, default `{}`)
 
-## pauseOn
+## pause
 
-Pauses test execution in different modes. Unlike `pauseOnFail`, this plugin supports
-multiple triggers for pausing and is controlled via CLI arguments.
+Pauses test execution interactively. Replaces the legacy `pauseOnFail` plugin.
+Default `on=fail` matches the old `pauseOnFail` behavior.
 
-Enable it via `-p` option with a mode:
-
-    npx codeceptjs run -p pauseOn:fail
-    npx codeceptjs run -p pauseOn:step
-    npx codeceptjs run -p pauseOn:file:tests/login_test.js
-    npx codeceptjs run -p pauseOn:file:tests/login_test.js:43
-    npx codeceptjs run -p pauseOn:url:/users/*
-
-#### Modes
-
-*   **fail** — pause when a step fails (same as `pauseOnFail` plugin)
-*   **step** — pause before first step, use `next` to advance step-by-step
-*   **file** — pause when execution reaches a specific file (and optionally line)
-*   **url** — pause when the browser URL matches a pattern (supports `*` wildcards)
+```js
+plugins: {
+  pause: {
+    enabled: false,
+    on: 'fail',
+  }
+}
+```
 
-### Parameters
+#### `on=` modes
 
-*   `config`   (optional, default `{}`)
+*   **fail** — pause when a step fails (default)
+*   **test** — pause after each test
+*   **step** — pause before the first step (interactive walk-through)
+*   **file** — pause when execution reaches `path=...[;line=...]`
+*   **url** — pause when the current URL matches `pattern=...`
 
-## pauseOnFail
+CLI examples:
 
-Automatically launches [interactive pause][5] when a test fails.
+    npx codeceptjs run -p pause
+    npx codeceptjs run -p pause:on=step
+    npx codeceptjs run -p pause:on=file:path=tests/login_test.js
+    npx codeceptjs run -p pause:on=file:path=tests/login_test.js;line=43
+    npx codeceptjs run -p pause:on=url:pattern=/users/*
 
-Useful for debugging flaky tests on local environment.
-Add this plugin to config file:
+> The legacy `pauseOnFail` plugin remains as a deprecated alias that emits a
+> deprecation warning and forwards to `pause` with `on=fail`.
 
-```js
-plugins: {
-  pauseOnFail: {},
-}
-```
-
-Unlike other plugins, `pauseOnFail` is not recommended to be enabled by default.
-Enable it manually on each run via `-p` option:
+### Parameters
 
-    npx codeceptjs run -p pauseOnFail
+*   `config`   (optional, default `{}`)
 
 ## retryFailedStep
 
@@ -705,70 +700,60 @@ Scenario('scenario tite', { disableRetryFailedStep: true }, () => {
 
 *   `config`  
 
-## screenshotOnFail
-
-Creates screenshot on failure. Screenshot is saved into `output` directory.
+## screenshot
 
-Initially this functionality was part of corresponding helper but has been moved into plugin since 1.4
+Saves screenshots from the browser at points triggered by `on=`. Replaces the
+legacy `screenshotOnFail` plugin. Default `on=fail` preserves the old behavior.
 
 This plugin is **enabled by default**.
 
-#### Configuration
-
-Configuration can either be taken from a corresponding helper (deprecated) or a from plugin config (recommended).
-
 ```js
 plugins: {
-   screenshotOnFail: {
-     enabled: true
-   }
+  screenshot: {
+    enabled: true,
+    on: 'fail',
+  }
 }
 ```
 
-Possible config options:
-
-*   `uniqueScreenshotNames`: use unique names for screenshot. Default: false.
-*   `fullPageScreenshots`: make full page screenshots. Default: false.
-
-### Parameters
+#### `on=` modes
 
-*   `config`  
-
-## stepByStepReport
-
-![step-by-step-report][6]
+*   **fail** — screenshot when a test fails (default)
+*   **test** — screenshot at the end of every test
+*   **step** — screenshot after every step
+*   **file** — screenshot for steps in `path=...[;line=...]`
+*   **url** — screenshot when the current URL matches `pattern=...`
 
-Generates step by step report for a test.
-After each step in a test a screenshot is created. After test executed screenshots are combined into slideshow.
-By default, reports are generated only for failed tests.
+CLI examples:
 
-Run tests with plugin enabled:
+    npx codeceptjs run -p screenshot
+    npx codeceptjs run -p screenshot:on=step
+    npx codeceptjs run -p screenshot:on=step;slides=true
+    npx codeceptjs run -p screenshot:on=file:path=tests/login_test.js
+    npx codeceptjs run -p screenshot:on=url:pattern=/users/*
 
-    npx codeceptjs run --plugins stepByStepReport
+Possible config options:
 
-#### Configuration
+*   `uniqueScreenshotNames`: use unique names for screenshot. Default: false.
+*   `fullPageScreenshots`: make full page screenshots. Default: false.
+*   `slides`: generate a step-by-step slideshow report (works with `on=step|file|url`). Replaces the legacy `stepByStepReport` plugin. Default: false.
+*   `deleteSuccessful`: when `slides=true`, drop slideshow folders for passing tests. Default: true.
+*   `animateSlides`: when `slides=true`, animate transitions between slides. Default: true.
+*   `ignoreSteps`: when `slides=true`, RegExps of step names to skip in the slideshow.
 
-```js
-"plugins": {
-   "stepByStepReport": {
-     "enabled": true
-   }
-}
-```
+#### Step-by-step slideshow
 
-Possible config options:
+`screenshot:on=step;slides=true` writes a per-test `record_<hash>/index.html`
+slideshow and a top-level `records.html` index. The output is a self-contained
+HTML page with keyboard / dot navigation — no external assets, no JavaScript
+frameworks.
 
-*   `deleteSuccessful`: do not save screenshots for successfully executed tests. Default: true.
-*   `animateSlides`: should animation for slides to be used. Default: true.
-*   `ignoreSteps`: steps to ignore in report. Array of RegExps is expected. Recommended to skip `grab*` and `wait*` steps.
-*   `fullPageScreenshots`: should full page screenshots be used. Default: false.
-*   `output`: a directory where reports should be stored. Default: `output`.
-*   `screenshotsForAllureReport`: If Allure plugin is enabled this plugin attaches each saved screenshot to allure report. Default: false.
-*   \`disableScreenshotOnFail : Disables the capturing of screeshots after the failed step. Default: true.
+> The legacy `screenshotOnFail` plugin remains as a deprecated alias. The legacy
+> `stepByStepReport` plugin has been replaced by `screenshot:slides=true`.
 
 ### Parameters
 
-*   `config` **any**&#x20;
+*   `config` &#x20;
 
 ## stepTimeout