feat: pauseOn plugin with debug modes and CLI plugin arguments

.gitignore

@@ -26,4 +26,5 @@ package-lock.json
 yarn.lock
 /.vs
 typings/types.d.ts
-typings/promiseBasedTypes.d.ts
+typings/promiseBasedTypes.d.ts
+reflection/

docs/debugging.md

@@ -0,0 +1,288 @@
+---
+permalink: /debugging
+title: Debugging Tests
+---
+
+# Debugging Tests
+
+CodeceptJS provides powerful tools for debugging your tests at every level: from verbose output to interactive breakpoints with step-by-step execution.
+
+## Output Verbosity
+
+When something goes wrong, start by increasing the output level:
+
+```bash
+npx codeceptjs run --steps     # print each step
+npx codeceptjs run --debug     # print steps + debug info
+npx codeceptjs run --verbose   # print everything
+```
+
+| Flag | What you see |
+|------|-------------|
+| `--steps` | Each executed step (`I click`, `I see`, etc.) |
+| `--debug` | Steps + helper/plugin info, URLs, loaded config |
+| `--verbose` | Everything above + internal promise queue, retries, timeouts |
+
+We recommend **always using `--debug`** when developing tests.
+
+For full internal logs, use the `DEBUG` environment variable:
+
+```bash
+DEBUG=codeceptjs:* npx codeceptjs run
+```
+
+You can narrow it down to specific modules:
+
+```bash
+DEBUG=codeceptjs:recorder npx codeceptjs run    # promise chain only
+DEBUG=codeceptjs:pause npx codeceptjs run       # pause session only
+```
+
+## Interactive Pause
+
+The most powerful debugging tool in CodeceptJS is **interactive pause**. It stops test execution and opens a live shell where you can run steps directly in the browser.
+
+Add `pause()` anywhere in your test:
+
+```js
+Scenario('debug checkout', ({ I }) => {
+  I.amOnPage('/products')
+  I.click('Add to Cart')
+  pause()  // <-- test stops here, shell opens
+  I.click('Checkout')
+})
+```
+
+When the shell opens, you'll see:
+
+```
+ Interactive shell started
+ Use JavaScript syntax to try steps in action
+ - Press ENTER to run the next step
+ - Press TAB twice to see all available commands
+ - Type exit + Enter to exit the interactive shell
+ - Prefix => to run js commands
+```
+
+### Available Commands
+
+| Input | What it does |
+|-------|-------------|
+| `click('Login')` | Runs `I.click('Login')` — the `I.` prefix is added automatically |
+| `see('Welcome')` | Runs `I.see('Welcome')` |
+| `grabCurrentUrl()` | Runs a grab method and prints the result |
+| `=> myVar` | Evaluates JavaScript expression |
+| *ENTER* (empty) | Runs the next test step and pauses again |
+| `exit` or `resume` | Exits the shell and continues the test |
+| *TAB TAB* | Shows all available I.* methods |
+
+You can also pass variables into the shell:
+
+```js
+const userData = { name: 'John', email: 'john@test.com' }
+pause({ userData })
+// in shell: => userData.name
+```
+
+### Using Pause as a Stop Point
+
+`pause()` works as a **breakpoint** in your test. Place it before a failing step to inspect the page state:
+
+```js
+Scenario('fix login bug', ({ I }) => {
+  I.amOnPage('/login')
+  I.fillField('Email', 'user@test.com')
+  I.fillField('Password', 'secret')
+  pause()  // stop here, inspect the form before submitting
+  I.click('Sign In')
+  I.see('Dashboard')
+})
+```
+
+You can also add it in hooks:
+
+```js
+After(({ I }) => {
+  pause()  // pause after every test to inspect final state
+})
+```
+
+## Pause On 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.
+
+### Pause on Failure
+
+Automatically enters interactive pause when a step fails:
+
+```bash
+npx codeceptjs run -p pauseOn: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`
+
+### 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
+```
+
+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.
+
+### Pause on File (Breakpoint)
+
+Pauses when execution reaches a specific file:
+
+```bash
+npx codeceptjs run -p pauseOn:file:tests/login_test.js
+```
+
+With a specific line number:
+
+```bash
+npx codeceptjs run -p pauseOn:file:tests/login_test.js: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.
+
+### Pause on URL
+
+Pauses when the browser navigates to a matching URL:
+
+```bash
+npx codeceptjs run -p pauseOn:url:/users/1
+```
+
+Supports `*` wildcards:
+
+```bash
+npx codeceptjs run -p pauseOn:url:/api/*/edit
+npx codeceptjs run -p pauseOn:url:/checkout/*
+```
+
+This is useful when you want to inspect a specific page regardless of which test step navigates there.
+
+## IDE Debugging
+
+### VS Code
+
+You can use the built-in Node.js debugger in VS Code to set breakpoints in test files.
+
+Add this configuration to `.vscode/launch.json`:
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "codeceptjs",
+  "args": ["run", "--grep", "@your_test_tag", "--debug"],
+  "program": "${workspaceFolder}/node_modules/codeceptjs/bin/codecept.js"
+}
+```
+
+Set breakpoints in your test files, then press F5 to start debugging. You'll be able to step through code, inspect variables, and use the VS Code debug console — all while the browser is open and controlled by the test.
+
+Combine with `pause()` for the best experience: set a VS Code breakpoint to inspect JavaScript state, then add `pause()` to interact with the browser.
+
+### WebStorm
+
+```bash
+node $NODE_DEBUG_OPTION ./node_modules/.bin/codeceptjs run
+```
+
+### Node.js Inspector
+
+```bash
+node --inspect ./node_modules/.bin/codeceptjs run
+node --inspect-brk ./node_modules/.bin/codeceptjs run  # break on first line
+```
+
+## Debugging on Failure
+
+Several built-in plugins capture information when tests fail. These are most useful on CI where you can't use interactive debugging.
+
+### Screenshots on Failure
+
+Enabled by default. Saves a screenshot when a test fails:
+
+```js
+plugins: {
+  screenshotOnFail: {
+    enabled: true,
+    uniqueScreenshotNames: true,
+    fullPageScreenshots: true,
+  }
+}
+```
+
+Screenshots are saved in the `output` directory.
+
+### Page Info on Failure
+
+Captures URL, HTML errors, and browser console logs on failure:
+
+```js
+plugins: {
+  pageInfo: {
+    enabled: true,
+  }
+}
+```
+
+### Step-by-Step Report
+
+Generates a slideshow of screenshots taken after every step — a visual replay of what the test did:
+
+```js
+plugins: {
+  stepByStepReport: {
+    enabled: true,
+    deleteSuccessful: true,   // keep only failed tests
+    fullPageScreenshots: true,
+  }
+}
+```
+
+```bash
+npx codeceptjs run -p stepByStepReport
+```
+
+After the run, open `output/records.html` to browse through the slideshows.
+
+## AI-Powered Debugging
+
+### AI in Interactive Pause
+
+When AI is configured, the interactive pause shell accepts natural language commands:
+
+```
+ AI is enabled! (experimental) Write what you want and make AI run it
+
+I.$ fill the login form with test credentials and submit
+```
+
+AI reads the current page HTML and generates CodeceptJS steps. See [Testing with AI](/ai) for setup.
+
+### AI Trace Plugin
+
+The `aiTrace` plugin captures rich execution traces for AI analysis — screenshots, HTML snapshots, ARIA trees, browser logs, and network requests at every step:
+
+```js
+plugins: {
+  aiTrace: {
+    enabled: true,
+  }
+}
+```
+
+After a test run, trace files are generated in `output/trace_*/trace.md`. Feed these to an AI assistant (like Claude Code) for automated failure analysis. See [AI Trace Plugin](/aitrace) for details.
+
+### MCP Server
+
+CodeceptJS includes an [MCP server](/mcp) that allows AI agents to control tests programmatically — list tests, run them step by step, capture artifacts, and analyze results. This enables AI-driven debugging workflows where an agent can investigate failures autonomously.
+
+> AI agent integration and MCP server will be covered in detail on a dedicated page.

docs/heal.md

@@ -8,15 +8,40 @@ Browser and Mobile tests can fail for vareity of reasons. However, on a big proj
 
 ![](/img/healing.png)
 
-Let's start with an example the most basic healing recipe. If after a click test has failed, try to reload page, and continue.
+Let's start with a common scenario. If a user suddenly becomes unauthorized and is moved to a sign-in page, or receives an unauthorized message on the page, we can heal by navigating to the `/login` page and trying to enter credentials again.
+
+```js
+heal.addRecipe('loginOnUnauthorized', {
+  priority: 10,
+  steps: ['click', 'see', 'amOnPage'],
+  prepare: {
+    url: ({ I }) => I.grabCurrentUrl(),
+    html: ({ I }) => I.grabHTMLFrom('body'),
+  },
+  fn: async ({ url, error, step, html }) => {
+    if (!url.includes('/login') && !error.message.toLowerCase().includes('unauthorized') && !html.toLowerCase().includes('unauthorized')) return;
+
+    return ({ I }) => {
+      I.amOnPage('/login');
+      I.fillField('Email', 'test@example.com');
+      I.fillField('Password', '123456');
+      I.click('Sign in');
+      I[step.name](...step.args);
+    };
+  },
+});
+```
+
+Another example is a very basic healing recipe. If after a click test has failed, try to reload page, and continue.
 
 ```js
 heal.addRecipe('reload', {
   priority: 10,
   steps: ['click'],
-  fn: async () => {
+  fn: async ({ step }) => {
     return ({ I }) => {
       I.refreshPage();
+      I[step.name](...step.args);
     };
   },
 });
@@ -32,6 +57,7 @@ The example above is only one way a test can be healed. But you can define as ma
 
 There are some ideas where healing can be useful to you:
 
+* **Authorization**. If a user suddenly becomes unauthorized and is moved to a sign-in page, or receives an unauthorized message on the page, we can heal by navigating to the `/login` page and trying to enter credentials.
 * **Networking**. If a test depends on a remote resource, and fails because this resource is not available, you may try to send API request to restore that resource before throwing an error.
 * **Data Consistency**. A test may fail because you noticed the data glitch in a system. Instead of failing a test you may try to clean up the data and try again to proceed.
 * **UI Change**. If there is a planned UI migration of a component, for instance Button was changed to Dropdown. You can prepare test so if it fails clicking Button it can try to do so with Dropdown.
@@ -67,9 +93,9 @@ Require `recipes` file and add `heal` plugin to `codecept.conf` file:
 
 ```js
 
-require('./heal')
+import './heal';
 
-exports.config = {
+export const config = {
   // ...
   plugins: {
     heal: {
@@ -134,7 +160,8 @@ heal.addRecipe('reloadPageOnUserAccount', {
       // probably you should do something more sophisticated
       // to heal the test
       I.reloadPage();
-      I.wait(1); 
+      I.wait(1);
+      I[step.name](...stepArgs);
     };
   },
 });

lib/command/dryRun.js

@@ -20,8 +20,7 @@ export default async function (test, options) {
   if (config.plugins) {
     // disable all plugins by default, they can be enabled with -p option
     for (const plugin in config.plugins) {
-      // if `-p all` is passed, then enabling all plugins, otherwise plugins could be enabled by `-p customLocator,commentStep,tryTo`
-      config.plugins[plugin].enabled = options.plugins === 'all'
+      config.plugins[plugin].enabled = false
     }
   }