codeceptjs 4.0.2-beta.9 → 4.0.2

package/docs/plugins/heal.md

@@ -0,0 +1,44 @@
+---
+permalink: /plugins/heal
+editLink: false
+sidebar: auto
+title: heal
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## heal
+
+Self-healing tests with AI.
+
+Read more about healing in [Self-Healing Tests][1]
+
+```js
+plugins: {
+  heal: {
+   enabled: true,
+   on: 'fail',
+  }
+}
+```
+
+More config options are available:
+
+*   `healLimit` - how many steps can be healed in a single test (default: 2)
+*   `on` - trigger mode. `fail` (default), `file` (filter to a path), `url` (filter to a URL pattern).
+
+#### `on=` modes
+
+Heal always runs on step failures; `on=` narrows when it engages.
+
+*   **fail** — heal any failing step (default)
+*   **file** — heal only failures in `path=...[;line=...]`
+*   **url** — heal only failures when the current URL matches `pattern=...`
+
+`on=step` and `on=test` are not supported and are rejected with an error.
+
+### Parameters
+
+*   `config`   
+
+[1]: https://codecept.io/heal/

package/docs/plugins/junitReporter.md

@@ -0,0 +1,51 @@
+---
+permalink: /plugins/junitReporter
+editLink: false
+sidebar: auto
+title: junitReporter
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## junitReporter
+
+Generates a JUnit-compatible XML report after a test run.
+
+Unlike Mocha's `mocha-junit-reporter`, this plugin understands CodeceptJS steps and substeps.
+For every `<testcase>` it includes:
+
+*   `<properties>` — the test's meta information: every `meta` key from `Scenario('...', { meta })`, plus its `tags` and `retries`
+*   `<system-out>` — an indented step/substep log (substeps are nested under their meta step); only failed steps are marked
+*   `<failure>` — for failed tests: the error message, type, stack trace and (optionally) the step trace
+
+The produced file is consumable by Jenkins, GitLab CI, CircleCI, GitHub Actions test reporters, etc.
+
+#### Configuration
+
+```js
+"plugins": {
+   "junitReporter": {
+     "enabled": true
+   }
+ }
+```
+
+Possible config options:
+
+*   `outputName`: file name for the report. Default: `report.xml`.
+*   `output`: directory where the report is stored, relative to the project root. Default: the `output` directory.
+*   `testGroupName`: value of the `name` attribute on the root `<testsuites>` element. Default: `CodeceptJS`.
+*   `attachMeta`: add the test's meta information (`meta` keys, `tags`, `retries`) as `<properties>`. Default: true.
+*   `attachSteps`: add the step/substep log as `<system-out>`. Default: true.
+*   `stepsInFailure`: append the step trace to the `<failure>` body. Default: true.
+
+CLI examples:
+
+    npx codeceptjs run -p junitReporter
+    npx codeceptjs run -p junitReporter:outputName=junit.xml
+
+> ℹ When running with `run-workers`, steps are serialized between processes and substep nesting is flattened.
+
+### Parameters
+
+*   `config` **any**  

package/docs/plugins/pageInfo.md

@@ -0,0 +1,34 @@
+---
+permalink: /plugins/pageInfo
+editLink: false
+sidebar: auto
+title: pageInfo
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## pageInfo
+
+Collects information from web page after each failed test and adds it to the test as an artifact.
+It is suggested to enable this plugin if you run tests on CI and you need to debug failed tests.
+This plugin can be paired with `analyze` plugin to provide more context.
+
+It collects URL, HTML errors (by classes), and browser logs.
+
+Enable this plugin in config:
+
+```js
+plugins: {
+ pageInfo: {
+  enabled: true,
+}
+```
+
+Additional config options:
+
+*   `errorClasses` - list of classes to search for errors (default: `['error', 'warning', 'alert', 'danger']`)
+*   `browserLogs` - list of types of errors to search for in browser logs (default: `['error']`)
+
+### Parameters
+
+*   `config`   

package/docs/plugins/pause.md

@@ -0,0 +1,43 @@
+---
+permalink: /plugins/pause
+editLink: false
+sidebar: auto
+title: pause
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## pause
+
+Pauses test execution interactively. Replaces the legacy `pauseOnFail`
+plugin. The default `on=fail` matches the old `pauseOnFail` behavior.
+
+#### Configuration
+
+```js
+plugins: {
+  pause: {
+    enabled: false,
+    on: 'fail',
+  }
+}
+```
+
+#### `on=` modes
+
+*   **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 browser URL matches `pattern=...`
+
+CLI examples:
+
+    npx codeceptjs run -p pause
+    npx codeceptjs run -p pause:on=step
+    npx codeceptjs run -p pause:on=file:path=tests/login_test.js;line=43
+    npx codeceptjs run -p pause:on=url:pattern=/users/*
+
+### Parameters
+
+*   `config`   

package/docs/plugins/pauseOnFail.md

@@ -0,0 +1,18 @@
+---
+permalink: /plugins/pauseOnFail
+editLink: false
+sidebar: auto
+title: pauseOnFail
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## pauseOnFail
+
+Starts an interactive pause when a test fails.
+
+**Deprecated:** use the `pause` plugin with `on: 'fail'`, which is the default behavior.
+
+### Parameters
+
+*   `config`   

package/docs/plugins/retryFailedStep.md

@@ -0,0 +1,75 @@
+---
+permalink: /plugins/retryFailedStep
+editLink: false
+sidebar: auto
+title: retryFailedStep
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## retryFailedStep
+
+Retries each failed step in a test.
+
+Add this plugin to config file:
+
+```js
+plugins: {
+    retryFailedStep: {
+       enabled: true
+    }
+}
+```
+
+Run tests with plugin enabled:
+
+    npx codeceptjs run --plugins retryFailedStep
+
+#### Configuration:
+
+*   `retries` - number of retries (by default 3),
+*   `factor` - The exponential factor to use. Default is 1.5.
+*   `minTimeout` - The number of milliseconds before starting the first retry. Default is 150.
+*   `maxTimeout` - The maximum number of milliseconds between two retries. Default is 10000.
+*   `randomize` - Randomizes the timeouts by multiplying with a factor from 1 to 2. Default is false.
+*   `defaultIgnoredSteps` - an array of steps to be ignored for retry. Includes:
+    *   `amOnPage`
+    *   `wait*`
+    *   `send*`
+    *   `execute*`
+    *   `run*`
+    *   `have*`
+*   `ignoredSteps` - an array for custom steps to ignore on retry. Use it to append custom steps to ignored list.
+    You can use step names or step prefixes ending with `*`. As such, `wait*` will match all steps starting with `wait`.
+    To append your own steps to ignore list - copy and paste a default steps list. Regexp values are accepted as well.
+*   `deferToScenarioRetries` - when enabled (default), step retries are automatically disabled if scenario retries are configured to avoid excessive total retries.
+
+#### Example
+
+```js
+plugins: {
+    retryFailedStep: {
+        enabled: true,
+        ignoredSteps: [
+          'scroll*', // ignore all scroll steps
+          /Cookie/, // ignore all steps with a Cookie in it (by regexp)
+        ]
+    }
+}
+```
+
+#### Disable Per Test
+
+This plugin can be disabled per test. In this case you will need to add `step.retry()` to all flaky steps:
+
+Use scenario configuration to disable plugin for a test
+
+```js
+Scenario('scenario tite', { disableRetryFailedStep: true }, () => {
+   // test goes here
+})
+```
+
+### Parameters
+
+*   `config` &#x20;

package/docs/plugins/screencast.md

@@ -0,0 +1,55 @@
+---
+permalink: /plugins/screencast
+editLink: false
+sidebar: auto
+title: screencast
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## screencast
+
+Records WebM video of tests using Playwright's screencast API.
+
+When `captions` is enabled, action annotations are burned into the video;
+when `subtitles` is enabled, a standalone `.srt` is also produced. Default
+`on=fail` keeps videos for failed tests only; `on=test` keeps every test's
+video.
+
+Note: enabling Playwright's helper-level `video: true` together with this
+plugin produces two independent recordings (`output/videos/*.webm` from the
+helper, `output/screencast/*.webm` from this plugin).
+
+#### Configuration
+
+```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
+
+Other 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. Default: true.
+*   `size`: pass-through `{ width, height }` for `screencast.start`.
+*   `quality`: pass-through 0–100 for `screencast.start`.
+
+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
+
+### Parameters
+
+*   `config`   

package/docs/plugins/screenshot.md

@@ -0,0 +1,58 @@
+---
+permalink: /plugins/screenshot
+editLink: false
+sidebar: auto
+title: screenshot
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## screenshot
+
+Saves screenshots from the browser at points triggered by `on=`.
+
+Replaces the legacy `screenshotOnFail` plugin. Default `on=fail` preserves the
+old behavior (screenshot when a test fails). Pass `slides=true` (with `on=step`)
+to generate a step-by-step slideshow report — replaces the legacy
+`stepByStepReport` plugin.
+
+#### Configuration
+
+```js
+plugins: {
+  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 browser URL matches `pattern=...`
+
+Other config options:
+
+*   `uniqueScreenshotNames`: use unique names for screenshot. Default: false.
+*   `fullPageScreenshots`: make full page screenshots. Default: false.
+*   `disableScreenshots`: legacy switch to skip the plugin entirely.
+*   `slides`: generate a step-by-step slideshow report (requires `on=step`). Default: false.
+*   `deleteSuccessful`: when `slides=true`, drop slideshow directories of 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.
+
+CLI examples:
+
+    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/*
+
+### Parameters
+
+*   `config`   

package/docs/plugins/screenshotOnFail.md

@@ -0,0 +1,18 @@
+---
+permalink: /plugins/screenshotOnFail
+editLink: false
+sidebar: auto
+title: screenshotOnFail
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## screenshotOnFail
+
+Saves a screenshot when a test fails.
+
+**Deprecated:** use the `screenshot` plugin with `on: 'fail'`, which is the default behavior.
+
+### Parameters
+
+*   `config`   

package/docs/plugins/stepTimeout.md

@@ -0,0 +1,65 @@
+---
+permalink: /plugins/stepTimeout
+editLink: false
+sidebar: auto
+title: stepTimeout
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## stepTimeout
+
+Set timeout for test steps globally.
+
+Add this plugin to config file:
+
+```js
+plugins: {
+    stepTimeout: {
+       enabled: true
+    }
+}
+```
+
+Run tests with plugin enabled:
+
+    npx codeceptjs run --plugins stepTimeout
+
+#### Configuration:
+
+*   `timeout` - global step timeout, default 150 seconds
+
+*   `overrideStepLimits` - whether to use timeouts set in plugin config to override step timeouts set in code with `I.action(..., step.timeout(x))`, default false
+
+*   `noTimeoutSteps` - an array of steps with no timeout. Default:
+
+    *   `amOnPage`
+    *   `wait*`
+
+    you could set your own noTimeoutSteps which would replace the default one.
+
+*   `customTimeoutSteps` - an array of step actions with custom timeout. Use it to override or extend noTimeoutSteps.
+    You can use step names or step prefixes ending with `*`. As such, `wait*` will match all steps starting with `wait`.
+
+#### Example
+
+```js
+plugins: {
+    stepTimeout: {
+        enabled: true,
+        overrideStepLimits: true,
+        noTimeoutSteps: [
+          'scroll*', // ignore all scroll steps
+          /Cookie/, // ignore all steps with a Cookie in it (by regexp)
+        ],
+        customTimeoutSteps: [
+          ['myFlakyStep*', 1],
+          ['scrollWhichRequiresTimeout', 5],
+        ]
+    }
+}
+```
+
+### Parameters
+
+*   `config` &#x20;

package/docs/plugins.md

@@ -0,0 +1,87 @@
+---
+permalink: /plugins
+editLink: false
+sidebar: auto
+title: Plugins
+---
+
+# Plugins
+
+CodeceptJS bundles the following plugins. Each plugin has its own page with full configuration reference.
+
+## [aiTrace](/plugins/aiTrace)
+
+Generates AI-friendly trace files for debugging with AI agents. This plugin creates a markdown file with test execution logs and links to all artifacts (screenshots, HTML, ARIA snapshots, browser logs, HTTP requests) for each step.
+
+## [analyze](/plugins/analyze)
+
+Uses AI to analyze test failures and provide insights
+
+## [auth](/plugins/auth)
+
+Logs user in for the first test and reuses session for next tests. Works by saving cookies into memory or file. If a session expires automatically logs in again.
+
+## [autoDelay](/plugins/autoDelay)
+
+Sometimes it takes some time for a page to respond to user's actions. Depending on app's performance this can be either slow or fast.
+
+## [browser](/plugins/browser)
+
+Overrides browser helper config from the command line. Works for all browser helpers (Playwright, Puppeteer, WebDriver, Appium) without touching `codecept.conf`.
+
+## [coverage](/plugins/coverage)
+
+Dumps code coverage from Playwright/Puppeteer after every test.
+
+## [customLocator](/plugins/customLocator)
+
+Creates a [custom locator][1] by using special attributes in HTML.
+
+## [customReporter](/plugins/customReporter)
+
+Sample custom reporter for CodeceptJS.
+
+## [expose](/plugins/expose)
+
+Exposes properties from helper instances as injectable test arguments. Use it to access the underlying Playwright/Puppeteer `page`, the wdio `browser` client, or any other helper internal directly from a Scenario:
+
+## [heal](/plugins/heal)
+
+Self-healing tests with AI.
+
+## [junitReporter](/plugins/junitReporter)
+
+Generates a JUnit-compatible XML report after a test run.
+
+## [pageInfo](/plugins/pageInfo)
+
+Collects information from web page after each failed test and adds it to the test as an artifact. It is suggested to enable this plugin if you run tests on CI and you need to debug failed tests. This plugin can be paired with `analyze` plugin to provide more context.
+
+## [pause](/plugins/pause)
+
+Pauses test execution interactively. Replaces the legacy `pauseOnFail` plugin. The default `on=fail` matches the old `pauseOnFail` behavior.
+
+## [pauseOnFail](/plugins/pauseOnFail)
+
+Starts an interactive pause when a test fails.
+
+## [retryFailedStep](/plugins/retryFailedStep)
+
+Retries each failed step in a test.
+
+## [screencast](/plugins/screencast)
+
+Records WebM video of tests using Playwright's screencast API.
+
+## [screenshot](/plugins/screenshot)
+
+Saves screenshots from the browser at points triggered by `on=`.
+
+## [screenshotOnFail](/plugins/screenshotOnFail)
+
+Saves a screenshot when a test fails.
+
+## [stepTimeout](/plugins/stepTimeout)
+
+Set timeout for test steps globally.
+