codeceptjs 4.0.0-rc.22 → 4.0.0-rc.24

package/docs/plugins/coverage.md

@@ -0,0 +1,39 @@
+---
+permalink: /plugins/coverage
+editLink: false
+sidebar: auto
+title: coverage
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## coverage
+
+Dumps code coverage from Playwright/Puppeteer after every test.
+
+#### Configuration
+
+```js
+plugins: {
+   coverage: {
+     enabled: true,
+     debug: true,
+     name: 'CodeceptJS Coverage Report',
+     outputDir: 'output/coverage'
+   }
+}
+```
+
+Possible config options, More could be found at [monocart-coverage-reports][1]
+
+*   `debug`: debug info. By default, false.
+*   `name`: coverage report name.
+*   `outputDir`: path to coverage report.
+*   `sourceFilter`: filter the source files.
+*   `sourcePath`: option to resolve a custom path.
+
+### Parameters
+
+*   `config` &#x20;
+
+[1]: https://github.com/cenfun/monocart-coverage-reports?tab=readme-ov-file#default-options

package/docs/plugins/customLocator.md

@@ -0,0 +1,119 @@
+---
+permalink: /plugins/customLocator
+editLink: false
+sidebar: auto
+title: customLocator
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## customLocator
+
+Creates a [custom locator][1] by using special attributes in HTML.
+
+If you have a convention to use `data-test-id` or `data-qa` attributes to mark active elements for e2e tests,
+you can enable this plugin to simplify matching elements with these attributes:
+
+```js
+// replace this:
+I.click({ css: '[data-test-id=register_button]');
+// with this:
+I.click('$register_button');
+```
+
+This plugin will create a valid XPath locator for you.
+
+#### Configuration
+
+*   `enabled` (default: `false`) should a locator be enabled
+*   `prefix` (default: `$`) sets a prefix for a custom locator.
+*   `attribute` (default: `data-test-id`) to set an attribute to be matched.
+*   `strategy` (default: `xpath`) actual locator strategy to use in query (`css` or `xpath`).
+*   `showActual` (default: false) show in the output actually produced XPath or CSS locator. By default shows custom locator value.
+
+#### Examples:
+
+Using `data-test` attribute with `$` prefix:
+
+```js
+// in codecept.conf.js
+plugins: {
+ customLocator: {
+   enabled: true,
+   attribute: 'data-test'
+ }
+}
+```
+
+In a test:
+
+```js
+I.seeElement('$user'); // matches => [data-test=user]
+I.click('$sign-up'); // matches => [data-test=sign-up]
+```
+
+Using `data-qa` attribute with `=` prefix:
+
+```js
+// in codecept.conf.js
+plugins: {
+ customLocator: {
+   enabled: true,
+   prefix: '=',
+   attribute: 'data-qa'
+ }
+}
+```
+
+In a test:
+
+```js
+I.seeElement('=user'); // matches => [data-qa=user]
+I.click('=sign-up'); // matches => [data-qa=sign-up]
+```
+
+Using `data-qa` OR `data-test` attribute with `=` prefix:
+
+```js
+// in codecept.conf.js
+plugins: {
+ customLocator: {
+   enabled: true,
+   prefix: '=',
+   attribute: ['data-qa', 'data-test'],
+   strategy: 'xpath'
+ }
+}
+```
+
+In a test:
+
+```js
+I.seeElement('=user'); // matches => //*[@data-qa=user or @data-test=user]
+I.click('=sign-up'); // matches => //*[data-qa=sign-up or @data-test=sign-up]
+```
+
+```js
+// in codecept.conf.js
+plugins: {
+ customLocator: {
+   enabled: true,
+   prefix: '=',
+   attribute: ['data-qa', 'data-test'],
+   strategy: 'css'
+ }
+}
+```
+
+In a test:
+
+```js
+I.seeElement('=user'); // matches => [data-qa=user],[data-test=user]
+I.click('=sign-up'); // matches => [data-qa=sign-up],[data-test=sign-up]
+```
+
+### Parameters
+
+*   `config` &#x20;
+
+[1]: https://codecept.io/locators#custom-locators

package/docs/plugins/customReporter.md

@@ -0,0 +1,16 @@
+---
+permalink: /plugins/customReporter
+editLink: false
+sidebar: auto
+title: customReporter
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## customReporter
+
+Sample custom reporter for CodeceptJS.
+
+### Parameters
+
+*   `config` &#x20;

package/docs/plugins/expose.md

@@ -0,0 +1,75 @@
+---
+permalink: /plugins/expose
+editLink: false
+sidebar: auto
+title: expose
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## 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:
+
+```js
+Scenario('listen for requests', async ({ I, page, browser }) => {
+  page.on('request', r => console.log(r.url()))
+  await page.evaluate(() => 1 + 1)
+  I.amOnPage('/')
+})
+```
+
+The injected value is a live proxy: every property access reads the *current*
+helper property, so mid-test reassignments (popups, `switchToNextTab`,
+`openNewTab`) are reflected automatically. Calls are not wrapped as
+CodeceptJS steps — `await page.evaluate(...)` runs as native Playwright.
+
+#### Configuration
+
+`inject` maps an injection name to a `HelperName.propertyName` string. A
+value with no dot is shorthand for "first configured browser helper that
+exposes this property" (allowed properties: `page`, `browser`,
+`browserContext`, `context`).
+
+```js
+plugins: {
+  expose: {
+    enabled: true,
+    inject: {
+      page: 'Playwright.page',
+      browser: 'Playwright.browser',
+      browserContext: 'Playwright.browserContext',
+      frame: 'Playwright.context',  // current frame set by switchTo
+      wdio: 'WebDriver.browser',
+    }
+  }
+}
+```
+
+Shorthand:
+
+```js
+plugins: {
+  expose: {
+    enabled: true,
+    inject: {
+      page: 'page',  // resolves to Playwright.page or Puppeteer.page
+    }
+  }
+}
+```
+
+#### Caveats
+
+*   The injected value is a `Proxy`, not the actual `Page`/`Browser` instance,
+    so `page instanceof Page` is `false`. Use duck typing instead.
+*   Cached method references lose the live binding. Call `page.click(...)`,
+    not `const click = page.click; click(...)`.
+*   In dry-run mode the underlying helper property is `undefined`; accessing
+    any property on the proxy returns `undefined` rather than throwing.
+
+### Parameters
+
+*   `config`   

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`