Merge branch '4.x' of github.com:codeceptjs/CodeceptJS into 4.x

Author: DavertMik

bin/mcp-server.js

@@ -107,6 +107,13 @@ After(({ I }) => {
 })
 ```
 
+### Pause Modes
+
+`pause()` adapts to who's driving the test:
+
+- **TTY (humans)** — when `process.stdin` is a terminal (running `npx codeceptjs run --debug` yourself), the readline REPL described above opens.
+- **MCP server (agent-driven debug)** — the MCP server registers an in-process pause handler before running tests, so when `pause()` fires inside a `run_test` invocation, control yields back to the agent. The agent drives the REPL through the [`pause` MCP tool](/mcp#pause). The same `I` container the test uses runs the agent's code, so artifacts (URL, ARIA, HTML, screenshot, console, storage) are captured against the live page.
+
 ## Pause Plugin
 
 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`.

docs/debugging.md

@@ -22,7 +22,7 @@ I.click({ role: 'button', name: 'Submit' }, '#login-form')
 
 The context narrows the search to one region of the page, and the semantic string says what the user actually clicks. This is **more precise than ARIA or CSS alone** because it combines structural scope with human-readable intent.
 
-Supported strategies: `css`, `xpath`, `id`, `name`, `role`, `frame`, `shadow`, `pw`. Shadow DOM and React selectors have their own pages — see [Shadow DOM](/shadow) and [React](/react). Playwright-specific locators (`_react`, `_vue`, `data-testid`) use the `pw` strategy: `{ pw: '_react=Button[name="Save"]' }`.
+Supported strategies: `css`, `xpath`, `id`, `name`, `role`, `frame`, `shadow`, `pw`. Shadow DOM and React selectors have their own pages — see [Shadow DOM](/shadow) and [React](/react). Playwright-specific locators use the `pw` strategy: `{ pw: '[data-testid="save"]' }`.
 
 ## Locator types at a glance
 

docs/locators.md

@@ -235,44 +235,85 @@ Capture the current state of the browser without performing any action. Useful f
 }
 ```
 
+### continue
+
+Release a paused test (one that called `pause()` during `run_test`) and let it run to completion. Returns the final reporter result.
+
+To inspect or manipulate state while the test is paused, use [`run_code`](#run_code) — it operates on the same container the test is using.
+
+**Parameters:**
+- `timeout` (optional): ms to wait for the test to finish after continuing (default 60000).
+
+**Returns:**
+```json
+{
+  "status": "completed",
+  "reporterJson": { "stats": { "tests": 1, "passes": 1, "failures": 0 }, "tests": [...] },
+  "error": null
+}
+```
+
+**Example flow:**
+
+```json
+{ "name": "run_test", "arguments": { "test": "checkout_test" } }
+// → { "status": "paused", "file": "...", "note": "..." }
+
+{ "name": "run_code", "arguments": { "code": "return await I.grabCurrentUrl()" } }
+// → { "status": "success", "returnValue": "http://...", "artifacts": { ... } }
+
+{ "name": "run_code", "arguments": { "code": "await I.click('Save')" } }
+// → { "status": "success", "artifacts": { ... } }
+
+{ "name": "continue", "arguments": {} }
+// → { "status": "completed", "reporterJson": { ... } }
+```
+
+**Notes:**
+- Pause runs in-process: `run_code` and the test share the same `I` / browser. There's no subprocess, no IPC.
+- `run_test` and `continue` wrap test execution in the same `withSilencedIO` helper that `run_step_by_step` uses, so step output doesn't interleave with the MCP JSON-RPC stream. Stdout/stderr are restored before each tool call returns.
+- TTY behaviour (`npx codeceptjs run --debug` at a terminal) is unchanged — `pause()` opens the readline REPL whenever `process.stdin.isTTY` is true.
+
 ### run_test
 
-Run a specific test by name or file path. Uses subprocess to run tests with isolation.
+Run a specific test by name or file path. Runs in-process so it shares the same `I` / browser as `run_code` and `snapshot`. If the test calls `pause()` — or if `pauseAt` is set and the Nth step completes — this tool returns early and the agent drives the session through `run_code` and `continue`.
 
 **Parameters:**
 - `test` (required): Test name or file path
 - `timeout` (optional): Timeout in milliseconds (default: 60000)
 - `config` (optional): Path to codecept.conf.js
+- `pauseAt` (optional): 1-based step index. The test pauses after the Nth step completes. Use this as a programmatic breakpoint without editing the test. Discover step indices via the `list` CLI (`--steps`) or via `run_step_by_step`.
 
-**Returns:**
+**Returns (test completed normally):**
 ```json
 {
-  "meta": {
-    "exitCode": 0,
-    "cli": "/path/to/codecept.js",
-    "root": "/project/root",
-    "configPath": "/path/to/codecept.conf.js",
-    "args": ["run", "--config", "...", "--reporter", "json", "test_file.js"],
-    "resolvedFile": "/full/path/to/test_file.js"
-  },
-  "reporterJson": {
-    "stats": {
-      "tests": 3,
-      "passes": 2,
-      "failures": 1
-    }
-  },
-  "stderr": "",
-  "rawStdout": ""
+  "status": "completed",
+  "file": "/path/to/test.js",
+  "reporterJson": { "stats": { "tests": 1, "passes": 1, "failures": 0 }, "tests": [...] },
+  "error": null
+}
+```
+
+**Returns (test reached `pause()` or `pauseAt`):**
+```json
+{
+  "status": "paused",
+  "file": "/path/to/test.js",
+  "pausedAfter": { "index": 3, "name": "I.click(\"Save\")", "status": "passed" },
+  "page": { "url": "https://example.com/checkout", "title": "Checkout", "contentSize": 18432 },
+  "suggestions": [
+    "Call snapshot to capture URL/HTML/ARIA/screenshot/console/storage at this point",
+    "Call run_code to inspect or manipulate state (e.g. return await I.grabText(\"h1\"))",
+    "Call continue to release the pause and let the test finish"
+  ]
 }
 ```
 
 **Features:**
 - Automatically resolves test names to file paths
 - Supports partial test name matching
-- Uses json reporter for structured output
-- Executes in subprocess for isolation
-- Includes stderr for debugging
+- Runs in-process; results assembled from CodeceptJS test events
+- Yields on `pause()` (or `pauseAt`) so the agent can inspect via `run_code` and release with `continue`
 
 **Example:**
 ```json
@@ -287,57 +328,52 @@ Run a specific test by name or file path. Uses subprocess to run tests with isol
 
 ### run_step_by_step
 
-Run a test step by step with detailed step information including timing and status. Generates AI-friendly trace files.
+Run a test interactively, pausing after every step. Returns a paused payload after the first step completes — the agent then calls `continue` to advance one step at a time, or `run_code` / `snapshot` to inspect state at any pause.
 
 **Parameters:**
 - `test` (required): Test name or file path
-- `timeout` (optional): Timeout in milliseconds (default: 60000)
+- `timeout` (optional): per-call timeout in milliseconds (default: 60000)
 - `config` (optional): Path to codecept.conf.js
 
-**Returns:**
+**Returns (after each step):**
 ```json
 {
-  "stepByStep": true,
-  "results": [
-    {
-      "test": "Navigate to homepage",
-      "file": "/path/to/test.js",
-      "traceFile": "file:///output/trace_Test_Name_abc123/trace.md",
-      "status": "completed",
-      "steps": [
-        {
-          "step": "I.amOnPage(\"/\")",
-          "status": "passed",
-          "time": 150
-        },
-        {
-          "step": "I.seeInTitle(\"Test App\")",
-          "status": "passed",
-          "time": 50
-        }
-      ]
-    }
+  "status": "paused",
+  "file": "/path/to/test.js",
+  "pausedAfter": { "index": 1, "name": "I.amOnPage(\"/\")", "status": "passed" },
+  "page": { "url": "http://localhost:8000/", "title": "Test App", "contentSize": 1832 },
+  "suggestions": [
+    "Call snapshot to capture URL/HTML/ARIA/screenshot/console/storage at this point",
+    "Call run_code to inspect or manipulate state ...",
+    "Call continue to release the pause and let the test run the next step (or finish)"
   ]
 }
 ```
 
-**Trace Files:**
-- Generated in `{output_dir}/trace_{TestName}_{hash}/`
-- Includes screenshots (PNG), page HTML, ARIA snapshots, console logs
-- `trace.md` file provides structured summary for AI analysis
-- Named with test title and hash for uniqueness
+**Returns (after the last step):**
+```json
+{ "status": "completed", "file": "...", "reporterJson": { "stats": {...}, "tests": [...] } }
+```
 
-**Example:**
+**Flow:**
 ```json
-{
-  "name": "run_step_by_step",
-  "arguments": {
-    "test": "authentication_test",
-    "timeout": 90000
-  }
-}
+{ "name": "run_step_by_step", "arguments": { "test": "checkout_test" } }
+// → { "status": "paused", "pausedAfter": { "index": 1, ... } }
+
+{ "name": "snapshot", "arguments": {} }
+// → full artifact bundle for step 1
+
+{ "name": "continue", "arguments": {} }
+// → { "status": "paused", "pausedAfter": { "index": 2, ... } }
+
+{ "name": "continue", "arguments": {} }
+// → ... and so on, until { "status": "completed", "reporterJson": {...} }
 ```
 
+For a one-shot breakpoint (pause once at a specific step rather than every step), use `run_test` with `pauseAt: N` instead.
+
+For per-step trace artifacts written to disk (HTML / ARIA / screenshot / console / storage per step) without the interactive flow, enable the `aiTrace` plugin.
+
 ### start_browser
 
 Start the browser session (initializes CodeceptJS container).

docs/mcp.md

@@ -478,11 +478,47 @@ When a test fails and video was enabled a video file is shown under the `artifac
 
 Open video and use it to debug a failed test case. Video helps when running tests on CI. Configure your CI system to enable artifacts storage for `output/video` and review videos of failed test case to understand failures.
 
-It is recommended to enable [subtitles](https://codecept.io/plugins/#subtitles) plugin which will generate subtitles from steps in `.srt` format. Subtitles file will be saved into after a video file so video player (like VLC) would load them automatically:
+## Screencast
+
+For richer evidence than helper-level `video`, enable the [`screencast`](https://codecept.io/plugins/#screencast) plugin. It uses Playwright's `page.screencast` API (Playwright >= 1.59) to record WebM video with optional burned-in action captions and a standalone `.srt` subtitle track.
+
+```js
+plugins: {
+  screencast: {
+    enabled: true,
+    on: 'fail',
+  }
+}
+```
+
+`on: 'fail'` (default) deletes the recording when the test passes; `on: 'test'` keeps every test's video.
+
+`captions: true` (default) burns `I.click()` / `I.fillField()` annotations into the video via `page.screencast.showActions()`. `subtitles: true` writes a standalone `.srt` file alongside the video — VLC and most players auto-load it.
+
+```js
+plugins: {
+  screencast: {
+    enabled: true,
+    on: 'test',
+    captions: true,
+    subtitles: true,
+  }
+}
+```
 
 ![](https://user-images.githubusercontent.com/220264/131644090-38d1ca55-1ba1-41fa-8fd1-7dea2b7ae995.png)
 
-## Trace <Badge text="Since 3.1" type="warning"/>
+CLI usage:
+
+    npx codeceptjs run -p screencast
+    npx codeceptjs run -p screencast:on=test
+    npx codeceptjs run -p screencast:on=test;captions=false;subtitles=true
+
+The recording is attached to the test as `test.artifacts.screencast`; the `.srt` (when enabled) is attached as `test.artifacts.subtitle`.
+
+> Enabling helper-level `video: true` **and** the `screencast` plugin produces two independent recordings (one in `output/videos/`, one in `output/screencast/`). Pick one.
+
+## Trace 
 
 If video is not enough to descover why a test failed a [trace](https://playwright.dev/docs/trace-viewer/) can be recorded.
 

docs/playwright.md

@@ -700,6 +700,47 @@ Scenario('scenario tite', { disableRetryFailedStep: true }, () => {
 
 *   `config`  
 
+## screencast
+
+Records WebM video of tests using Playwright's screencast API (Playwright >= 1.59).
+When `captions` is enabled, action annotations are burned into the video; when
+`subtitles` is enabled, a standalone `.srt` file is also produced.
+
+```js
+plugins: {
+  screencast: {
+    enabled: true,
+    on: 'fail',
+  }
+}
+```
+
+#### `on=` modes
+
+*   **fail** — record while running; delete on pass, keep on fail (default)
+*   **test** — record and keep every test's video
+
+CLI examples:
+
+    npx codeceptjs run -p screencast
+    npx codeceptjs run -p screencast:on=test
+    npx codeceptjs run -p screencast:on=test;captions=false;subtitles=true
+
+Possible config options:
+
+*   `captions`: burn-in action overlays via `page.screencast.showActions()`. Default: true.
+*   `subtitles`: also write a standalone `.srt` file alongside the video. Default: false.
+*   `video`: record a video. With `video=false, subtitles=true`, only the `.srt` is produced (next to `test.artifacts.video` if a helper recorded one). Default: true.
+*   `size`: pass-through `{ width, height }` for `screencast.start`.
+*   `quality`: pass-through 0–100 for `screencast.start`.
+
+> Enabling Playwright's helper-level `video: true` and this plugin together
+> produces two independent recordings. Pick one.
+
+### Parameters
+
+*   `config`  
+
 ## screenshot
 
 Saves screenshots from the browser at points triggered by `on=`. Replaces the
@@ -812,20 +853,6 @@ plugins: {
 
 *   `config`  
 
-## subtitles
-
-Automatically captures steps as subtitle, and saves it as an artifact when a video is found for a failed test
-
-#### Configuration
-
-```js
-plugins: {
- subtitles: {
-   enabled: true
- }
-}
-```
-
 [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
 [2]: https://github.com/cenfun/monocart-coverage-reports?tab=readme-ov-file#default-options

docs/plugins.md

@@ -57,8 +57,10 @@ export const config = {
     retryFailedStep: {
       enabled: false,
     },
-    subtitles: {
+    screencast: {
       enabled: true,
+      on: 'test',
+      subtitles: true,
     },
     aiTrace: {
       enabled: true,

examples/codecept.config.js

@@ -36,7 +36,7 @@ import MultipleElementsFound from './errors/MultipleElementsFound.js'
 import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefused.js'
 import Popup from './extras/Popup.js'
 import Console from './extras/Console.js'
-import { findReact, findVue, findByPlaywrightLocator } from './extras/PlaywrightReactVueLocator.js'
+import { findReact, findByPlaywrightLocator } from './extras/PlaywrightReactVueLocator.js'
 import { dropFile } from './scripts/dropFile.js'
 import WebElement from '../element/WebElement.js'
 import { selectElement } from './extras/elementSelection.js'
@@ -4223,13 +4223,10 @@ async function findByRole(context, locator) {
 }
 
 async function findElements(matcher, locator) {
-  // Check if locator is a Locator object with react/vue type, or a raw object with react/vue property
   const isReactLocator = locator.type === 'react' || (locator.locator && locator.locator.react) || locator.react
-  const isVueLocator = locator.type === 'vue' || (locator.locator && locator.locator.vue) || locator.vue
   const isPwLocator = locator.type === 'pw' || (locator.locator && locator.locator.pw) || locator.pw
 
   if (isReactLocator) return findReact(matcher, locator)
-  if (isVueLocator) return findVue(matcher, locator)
   if (isPwLocator) return findByPlaywrightLocator.call(this, matcher, locator)
 
   // Handle role locators with text/exact options (e.g., {role: 'button', text: 'Submit', exact: true})
@@ -4245,7 +4242,6 @@ async function findElements(matcher, locator) {
 
 async function findElement(matcher, locator) {
   if (locator.react) return findReact(matcher, locator)
-  if (locator.vue) return findVue(matcher, locator)
   if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
 
   locator = new Locator(locator, 'css')