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>

Author: DavertMik

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 stepByStepReport                   # 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` and `pauseOn` plugins still work as deprecated aliases.
 
 ### 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
 

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                 |
+| `pauseOn`           | `pause`      | Use `on=fail|test|step|file|url` instead           |
+
 ### 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 `pauseOn` and `pauseOnFail`
+plugins. 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)
-
-### Parameters
+```js
+plugins: {
+  pause: {
+    enabled: false,
+    on: 'fail',
+  }
+}
+```
 
-*   `config`   (optional, default `{}`)
+#### `on=` modes
 
-## pauseOnFail
+*   **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=...`
 
-Automatically launches [interactive pause][5] when a test fails.
+CLI examples:
 
-Useful for debugging flaky tests on local environment.
-Add this plugin to config file:
+    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/*
 
-```js
-plugins: {
-  pauseOnFail: {},
-}
-```
+> The legacy `pauseOn` and `pauseOnFail` plugins remain as deprecated aliases
+> that translate to the new syntax and emit a deprecation warning.
 
-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,31 +700,44 @@ 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',
+  }
 }
 ```
 
+#### `on=` modes
+
+*   **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=...`
+
+CLI examples:
+
+    npx codeceptjs run -p screenshot
+    npx codeceptjs run -p screenshot:on=step
+    npx codeceptjs run -p screenshot:on=file:path=tests/login_test.js
+    npx codeceptjs run -p screenshot:on=url:pattern=/users/*
+
 Possible config options:
 
 *   `uniqueScreenshotNames`: use unique names for screenshot. Default: false.
 *   `fullPageScreenshots`: make full page screenshots. Default: false.
 
+> The legacy `screenshotOnFail` plugin remains as a deprecated alias.
+
 ### Parameters
 
 *   `config`  

docs/tutorial.md

@@ -153,13 +153,13 @@ Please note, that you shouldn't use a real credit card number here. Good news, y
 Run the test with next command:
 
 ```
-npx codeceptjs run --debug -p pauseOnFail
+npx codeceptjs run --debug -p pause
 ```
 
 What are special options here?
 
 * `--debug` flag is used to output additional information to the console, such as the details of each step in the test, the values of variables, and the results of test assertions. This can help you to identify and fix any issues in your tests.
-* `-p pauseOnFail` option is also used to keep the browser opened even if a test fails. It will help us to identify to which point test was executed and what can be improved.
+* `-p pause` option is also used to keep the browser opened even if a test fails (default `on=fail`). It will help us to identify to which point test was executed and what can be improved.
 
 Add more test steps if needed, update locators, and notify business owners that all that purchases are made by you so your collegues won't call you in the night asking when you want to get a coffee cup 😀 Also the good idea is to run tests on staging website, to not interfere with business process.
 

lib/config.js

@@ -15,8 +15,9 @@ const defaultConfig = {
   hooks: [],
   gherkin: {},
   plugins: {
-    screenshotOnFail: {
-      enabled: true, // will be disabled by default in 2.0
+    screenshot: {
+      enabled: true,
+      on: 'fail',
     },
   },
   stepTimeout: 0,