codeceptjs 4.0.0-rc.20 → 4.0.0-rc.22

package/bin/mcp-server.js

@@ -60,9 +60,7 @@ function aiTraceHint() {
 }
 
 function applyMochaGrep(grep) {
-  if (!grep) return
-  const mocha = typeof container.mocha === 'function' ? container.mocha() : container.mocha
-  if (mocha && typeof mocha.grep === 'function') mocha.grep(grep)
+  if (grep) container.mocha().grep(grep)
 }
 
 function pauseAtMatcher(pauseAt) {
@@ -401,14 +399,16 @@ async function cancelRun() {
   abortRun = true
   if (typeof pendingRunCleanup === 'function') { try { pendingRunCleanup() } catch {} }
   if (pausedController) { try { pausedController.resolveContinue() } catch {} ; pausedController = null }
+
+  try { container.mocha().runner?.abort() } catch {}
+
   if (pendingRunPromise) {
-    try { await Promise.race([pendingRunPromise.catch(() => {}), new Promise(r => setTimeout(r, 5000))]) } catch {}
+    try { await pendingRunPromise.catch(() => {}) } catch {}
   }
   pendingRunPromise = null
   pendingRunResults = null
   pendingTestFile = null
   pendingStepInfo = null
-  abortRun = false
   return true
 }
 
@@ -1032,6 +1032,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               pendingRunCleanup = null
             }
 
+            abortRun = false
             let runError = null
             const runPromise = (async () => {
               try {
@@ -1126,6 +1127,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               pendingRunCleanup = null
             }
 
+            abortRun = false
             let runError = null
             const runPromise = (async () => {
               try {

package/docs/advanced.md

@@ -134,7 +134,7 @@ Feature('My feature', {key: val});
 Scenario('My scenario', {key: val},({ I }) => {});
 ```
 
-You can use this options for build your own [plugins](https://codecept.io/hooks/#plugins) with [event listners](https://codecept.io/hooks/#api). Example: 
+You can use these options to build your own [plugins](https://codecept.io/hooks#plugins) with [event listeners](https://codecept.io/architecture#events). Example: 
 
 ```js
   // for test

package/docs/agents.md

@@ -5,6 +5,38 @@ title: Agentic Testing
 
 # Agentic Testing
 
+## What Makes CodeceptJS Agent-friendly
+
+CodeceptJS 4 is designed for agent testing. It ships with its own MCP and official skills that teach agents best practices in test automation—how to write tests, choose locators, test them live in the browser, and refactor to page objects.
+
+Agents get full control over test and browser execution: 
+
+- **Full HTML access and ARIA snapshots.** Agents see buttons with icons, empty labels, and other elements Playwright MCP's accessibility tree omits.
+
+- **Query HTML directly with CSS, ARIA, Semantic Locators or XPath** Agents can freely run XPath or CSS to efficiently search over HTML.
+
+- **Browser logs and page state as files.** Agents read via native filesystem tools instead of extra requests, eliminating redundant context dumps.
+
+- **Same locators for tests and agents.** Tests and agent scripts share identical selectors. No elements by reference indexes, no clicks by coordinates. Agents inherit battle-tested patterns without guessing.
+
+- **Testing-first framework, not browser control.** CodeceptJS is built for testing, so agents stay focused on test scenarios instead of raw browser commands.
+
+CodeceptJS is token-efficient: it stores HTML, ARIA, logs, and HTTP request data as files instead of streaming them through MCP. Agents read these files with their native shell tools—no extra API calls, no redundant context.
+
+## The loop
+
+Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
+
+1. **Open the page.** Run a stub test (new work) or set a breakpoint at the failing step (fix). The browser lands at the right starting point and yields control to the agent.
+2. **Read the page.** MCP saves HTML, ARIA, and screenshot of the page to files (and the agent can call the `snapshot` tool to refresh them). The agent reads those files before deciding what to try next, controlling its token usage.
+3. **Run a CodeceptJS command.** The agent tries `I.*` commands like `I.click('Add to cart')`, `I.fillField('Email', secret(process.env.EMAIL))`, `I.see('Confirmed')`. On success, that line goes into the test — same syntax.
+4. **Check the result.** The response after each command shows the new page state. If the URL changed and the modal opened, the line goes into the verified sequence. If not, the agent reads the page again and tries a different locator or a wait.
+5. **Move forward.** The agent looks at the new state and chooses the next command. Steps 2–4 repeat until the scenario is whole.
+6. **Commit to the file.** The agent edits the test — replaces `pause()` (new tests) or the broken line (fixes) with the verified sequence — then reruns end-to-end and reads the trace to confirm.
+
+
+## How It Works
+
 CodeceptJS ships an **MCP server and a skillset** that lets an AI agent (Claude Code, Cursor, Codex, others) write and fix tests by driving the real browser. The agent runs the same `I.*` commands the test does, reads how the page responds, and only commits the lines that succeeded.
 
 ## Why MCP
@@ -30,16 +62,6 @@ This lets the agent get a test working in one iteration. The agent can live-writ
 
 The MCP server is the agent-facing equivalent of the `pause()` REPL — same access, driven by tool calls instead of keystrokes. Full tool reference at [/mcp](/mcp).
 
-## The loop
-
-Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
-
-1. **Open the page.** Run a stub test (new work) or set a breakpoint at the failing step (fix). The browser lands at the right starting point and yields control to the agent.
-2. **Read the page.** MCP saves HTML, ARIA, and screenshot of the page to files (and the agent can call the `snapshot` tool to refresh them). The agent reads those files before deciding what to try next, controlling its token usage.
-3. **Run a CodeceptJS command.** The agent tries `I.*` commands like `I.click('Add to cart')`, `I.fillField('Email', secret(process.env.EMAIL))`, `I.see('Confirmed')`. On success, that line goes into the test — same syntax.
-4. **Check the result.** The response after each command shows the new page state. If the URL changed and the modal opened, the line goes into the verified sequence. If not, the agent reads the page again and tries a different locator or a wait.
-5. **Move forward.** The agent looks at the new state and chooses the next command. Steps 2–4 repeat until the scenario is whole.
-6. **Commit to the file.** The agent edits the test — replaces `pause()` (new tests) or the broken line (fixes) with the verified sequence — then reruns end-to-end and reads the trace to confirm.
 
 ## How the agent reads the page
 

package/docs/architecture.md

@@ -0,0 +1,219 @@
+---
+permalink: /architecture
+title: Architecture
+---
+
+# CodeceptJS Architecture
+
+How CodeceptJS runs a test, and the internal modules you build [plugins, listeners, and helpers](/hooks) against.
+
+## How a Test Runs
+
+CodeceptJS is built on top of [Mocha](https://mochajs.org). A run goes through these stages:
+
+1. **Load.** CodeceptJS reads the config, builds the [container](#container) (helpers, support objects, plugins), and runs the `bootstrap` hook. `event.all.before` fires.
+2. **Suite.** For each suite, `event.suite.before` fires. Helper `_beforeSuite` hooks run.
+3. **Test.** For each test: `event.test.started` fires; `Before` hooks from helpers (`_before`) and from the suite run, then `event.test.before` fires; the scenario function runs; `event.test.passed` or `event.test.failed` fires; `After` hooks run; `event.test.after` and then `event.test.finished` fire.
+4. **Step.** Each `I.*` call inside a scenario becomes a step. It is *scheduled* onto the [recorder](#the-recorder) — `event.step.before` fires — then executed: `event.step.started`, `event.step.passed` or `event.step.failed`, `event.step.after`, `event.step.finished`.
+5. **Finish.** `event.suite.after` fires after each suite, `event.all.after` after the last one, and `event.all.result` when results are printed. The `teardown` hook runs.
+
+The key idea is step 4: **a scenario doesn't execute its steps as it runs** — it queues them. `I.click()` returns immediately; the [recorder](#the-recorder) runs the queued action later. This is why scenarios rarely need `await`, and why anything that injects async work has to go through the recorder.
+
+## The Internal API
+
+CodeceptJS exposes its internals as named exports of the `codeceptjs` package. Import only what you need:
+
+```js
+import { recorder, event, output, container, config } from 'codeceptjs'
+```
+
+| Export | What it is |
+| --- | --- |
+| [`codecept`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/codecept.js) | the test runner class |
+| [`config`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/config.js) | the loaded configuration |
+| [`container`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/container.js) | dependency-injection container: helpers, support objects, plugins, the Mocha instance |
+| [`recorder`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/recorder.js) | the global promise chain that orders every step |
+| [`event`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/event.js) | the event dispatcher and the names of all lifecycle events |
+| [`output`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/output.js) | the printer used for all console output |
+| [`helper`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/helper.js) | the base class every helper extends |
+| [`actor`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/actor.js) | the base class behind the `I` object |
+
+> Older code relied on a global `codeceptjs` object (`const { recorder } = codeceptjs`). That global only exists under `noGlobals: false`, the deprecated 3.x default — prefer named imports.
+
+The [API reference](https://github.com/codeceptjs/CodeceptJS/tree/master/docs/api) on GitHub documents these modules; the source is the final word.
+
+## The Recorder
+
+The recorder is a single global promise chain. Every step a scenario "calls" is appended to it, and the chain runs the steps one after another. To run your own async code at the right point in a test, append it to the recorder too:
+
+```js
+import { event, recorder } from 'codeceptjs'
+
+event.dispatcher.on(event.test.before, () => {
+  recorder.add('seed fixture data', async () => {
+    await api.post('/users', { name: 'john', email: 'john@example.com' })
+  })
+})
+```
+
+- `recorder.add(name, fn)` — append `fn` (async, or returning a promise) to the chain. The name shows up in `--verbose` output.
+- `recorder.startUnlessRunning()` — start a chain if none is running. Call it before `add()` from a listener that may fire outside a running chain, such as `event.all.before`.
+- `recorder.retry({ retries, when })` — retry failing steps that match `when`. See [conditional retries](/helpers#conditional-retries).
+
+Run tests with `--verbose` to watch the recorder schedule and execute each entry.
+
+## Container
+
+The container resolves helpers and support objects by name:
+
+```js
+import { container } from 'codeceptjs'
+
+const helpers = container.helpers()          // every helper, keyed by name
+const { Playwright } = container.helpers()   // one helper
+const support = container.support()          // every support object
+const { UserPage } = container.support()     // one page object
+const plugins = container.plugins()          // enabled plugins
+const mocha = container.mocha()              // the current Mocha instance
+```
+
+Add objects at runtime — useful from a `bootstrap` script:
+
+```js
+import { container } from 'codeceptjs'
+import UserPage from './pages/user.js'
+
+container.append({
+  helpers: { MyHelper: new MyHelper({ host: 'http://example.com' }) },
+  support: { UserPage },
+})
+```
+
+## Events
+
+`event.dispatcher` is a Node `EventEmitter`. Attach listeners to it from a [plugin](/hooks#plugins) or `bootstrap` script.
+
+Events are **sync** or **async**:
+
+- **sync** — fires the moment the action happens. Do synchronous work only.
+- **async** — fires when the action is *scheduled*. To do async work in the right order, queue it with `recorder.add()`.
+
+| Event | Kind | When |
+| --- | --- | --- |
+| `event.all.before` | — | before any test runs |
+| `event.suite.before(suite)` | async | before a suite |
+| `event.test.started(test)` | sync | at the very start of a test |
+| `event.test.before(test)` | async | after `Before` hooks from helpers and the test are run |
+| `event.test.passed(test)` | sync | test passed |
+| `event.test.failed(test, err)` | sync | test failed |
+| `event.test.skipped(test)` | sync | test skipped |
+| `event.test.after(test)` | async | after each test |
+| `event.test.finished(test)` | sync | test finished |
+| `event.suite.after(suite)` | async | after a suite |
+| `event.step.before(step)` | async | step scheduled for execution |
+| `event.step.started(step)` | sync | step starts executing |
+| `event.step.passed(step)` | sync | step passed |
+| `event.step.failed(step, err)` | sync | step failed |
+| `event.step.after(step)` | async | after a step |
+| `event.step.finished(step)` | sync | step finished |
+| `event.step.comment(step)` | sync | a comment such as `I.say(...)` |
+| `event.bddStep.before(step)` / `event.bddStep.after(step)` | async | around a Gherkin step |
+| `event.hook.started(hook)` / `event.hook.passed` / `event.hook.failed` / `event.hook.finished` | sync | around `Before` / `After` / `BeforeSuite` / `AfterSuite` hooks |
+| `event.all.after` | — | after all tests |
+| `event.all.result(result)` | — | when results are printed |
+| `event.all.failures(failures)` | — | when a run reports failures |
+| `event.workers.before` / `event.workers.after` / `event.workers.result(result)` | — | around a [parallel run](/parallel) (parent process only) |
+
+The [built-in listeners](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/listener) are working examples — every reporter and several plugins are listeners.
+
+### Test object
+
+Test events pass a test object with these fields:
+
+- `title` — the test title
+- `body` — the test function as a string
+- `opts` — test options such as `retries` (see [test options](/advanced#test-options))
+- `pending` — `true` while scheduled, `false` once finished
+- `tags` — array of [tags](/test-structure#tags) for this test
+- `artifacts` — files attached to this test (screenshots, videos, …), shared across reporters
+- `file` — path to the test file
+- `steps` — executed steps (only on `test.passed`, `test.failed`, `test.finished`)
+- `skipInfo` — present when the test was skipped: `{ message, description }`
+
+### Step object
+
+Step events pass a step object with these fields:
+
+- `name` — the step name, such as `see` or `click`
+- `actor` — the current actor, usually `I`
+- `helper` — the helper instance that executes this step
+- `helperMethod` — the helper method, usually the same as `name`
+- `status` — `passed` or `failed`
+- `prefix` — for a step inside a `within` block, the within text (e.g. `Within .js-signup-form`)
+- `args` — the arguments passed to the step
+
+## Config
+
+```js
+import { config } from 'codeceptjs'
+
+config.get()                       // the full config object
+config.get('myKey')                // one value
+config.get('myKey', 'fallback')    // one value, with a default
+```
+
+## Output
+
+Output has four verbosity levels, each toggled by a CLI flag:
+
+| Level | Flag | Use |
+| --- | --- | --- |
+| default | — | `output.print` — basic information |
+| steps | `--steps` | step execution |
+| debug | `--debug` | steps plus `output.debug` |
+| verbose | `--verbose` | debug plus `output.log` (internal logs and recorder activity) |
+
+```js
+import { output } from 'codeceptjs'
+
+output.print('basic information')
+output.debug('debug information')
+output.log('verbose logging information')
+```
+
+Use these instead of `console.log` so messages respect the chosen verbosity.
+
+## Helpers and the Actor
+
+The `I` object is an **actor** assembled from the enabled helpers. Each `I.method()` call delegates to the matching helper method and is wrapped as a step. Methods whose names start with `_` are private to the helper and not exposed on `I`. To add your own actions, write a [custom helper](/helpers).
+
+## Running CodeceptJS from Code
+
+CodeceptJS can be driven from your own script. Create the runner with a config and options, initialize it, then bootstrap, load tests, and run:
+
+```js
+import { codecept as Codecept } from 'codeceptjs'
+
+const config = { helpers: { Playwright: { browser: 'chromium', url: 'http://localhost' } } }
+const opts = { steps: true }
+
+const codecept = new Codecept(config, opts)
+codecept.init(import.meta.dirname)   // the test root directory
+
+try {
+  await codecept.bootstrap()
+  codecept.loadTests('**/*_test.js')
+  await codecept.run()               // pass a test file path to run only that file
+} catch (err) {
+  console.error(err)
+  process.exitCode = 1
+} finally {
+  await codecept.teardown()
+}
+```
+
+> To run tests inside workers from a script, see [parallel execution](/parallel).
+
+---
+
+**See also:** [Extending CodeceptJS](/hooks) · [Custom Helpers](/helpers) · [Plugins](/plugins) · [Bootstrap & Teardown](/bootstrap)