codeceptjs 4.0.2-beta.9 → 4.0.2

package/docs/plugins/aiTrace.md

@@ -0,0 +1,49 @@
+---
+permalink: /plugins/aiTrace
+editLink: false
+sidebar: auto
+title: aiTrace
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## 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.
+
+#### Configuration
+
+```js
+"plugins": {
+   "aiTrace": {
+     "enabled": true
+   }
+ }
+```
+
+Possible config options:
+
+*   `deleteSuccessful`: delete traces for successfully executed tests. Default: false.
+*   `fullPageScreenshots`: should full page screenshots be used. Default: false.
+*   `output`: a directory where traces should be stored. Default: `output`.
+*   `captureHTML`: capture HTML for each step. Default: true.
+*   `captureARIA`: capture ARIA snapshot for each step. Default: true.
+*   `captureBrowserLogs`: capture browser console logs. Default: true.
+*   `captureHTTP`: capture HTTP requests (requires `trace` or `recordHar` enabled in helper config). Default: true.
+*   `captureDebugOutput`: capture CodeceptJS debug output. Default: true.
+*   `ignoreSteps`: steps to ignore in trace. Array of RegExps is expected.
+*   `on`: trigger mode — `step` (default), `fail`, `test`, `file`, `url`.
+
+#### `on=` modes
+
+*   **step** — persist every step (default)
+*   **fail** — persist only the failed step
+*   **test** — persist only the last step of each test
+*   **file** — persist steps from `path=...[;line=...]`
+*   **url** — persist when the current URL matches `pattern=...`
+
+### Parameters
+
+*   `config` **any**  

package/docs/plugins/analyze.md

@@ -0,0 +1,66 @@
+---
+permalink: /plugins/analyze
+editLink: false
+sidebar: auto
+title: analyze
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## analyze
+
+Uses AI to analyze test failures and provide insights
+
+This plugin analyzes failed tests using AI to provide detailed explanations and group similar failures.
+When enabled with --ai flag, it generates reports after test execution.
+
+#### Usage
+
+```js
+// in codecept.conf.js
+exports.config = {
+  plugins: {
+    analyze: {
+      enabled: true,
+      clusterize: 5,
+      analyze: 2,
+      vision: false
+    }
+  }
+}
+```
+
+#### Configuration
+
+*   `clusterize` (number) - minimum number of failures to trigger clustering analysis. Default: 5
+*   `analyze` (number) - maximum number of individual test failures to analyze in detail. Default: 2
+*   `vision` (boolean) - enables visual analysis of test screenshots. Default: false
+*   `categories` (array) - list of failure categories for classification. Defaults to:
+    *   Browser connection error / browser crash
+    *   Network errors (server error, timeout, etc)
+    *   HTML / page elements (not found, not visible, etc)
+    *   Navigation errors (404, etc)
+    *   Code errors (syntax error, JS errors, etc)
+    *   Library & framework errors
+    *   Data errors (password incorrect, invalid format, etc)
+    *   Assertion failures
+    *   Other errors
+*   `prompts` (object) - customize AI prompts for analysis
+    *   `clusterize` - prompt for clustering analysis
+    *   `analyze` - prompt for individual test analysis
+
+#### Features
+
+*   Groups similar failures when number of failures >= clusterize value
+*   Provides detailed analysis of individual failures
+*   Analyzes screenshots if vision=true and screenshots are available
+*   Classifies failures into predefined categories
+*   Suggests possible causes and solutions
+
+### Parameters
+
+*   `config` **[Object][1]** Plugin configuration 
+
+Returns **void**&#x20;
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

package/docs/plugins/auth.md

@@ -0,0 +1,241 @@
+---
+permalink: /plugins/auth
+editLink: false
+sidebar: auto
+title: auth
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## 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.
+
+> For better development experience cookies can be saved into file, so a session can be reused while writing tests.
+
+#### Usage
+
+1.  Enable this plugin and configure as described below
+2.  Define user session names (example: `user`, `editor`, `admin`, etc).
+3.  Define how users are logged in and how to check that user is logged in
+4.  Use `login` object inside your tests to log in:
+
+```js
+// inside a test file
+// use login to inject auto-login function
+Feature('Login');
+
+Before(({ login }) => {
+   login('user'); // login using user session
+});
+
+// Alternatively log in for one scenario.
+Scenario('log me in', ( { I, login } ) => {
+   login('admin');
+   I.see('I am logged in');
+});
+```
+
+#### Configuration
+
+*   `saveToFile` (default: false) - save cookies to file. Allows to reuse session between execution.
+*   `inject` (default: `login`) - name of the login function to use
+*   `users` - an array containing different session names and functions to:
+    *   `login` - sign in into the system
+    *   `check` - check that user is logged in
+    *   `fetch` - to get current cookies (by default `I.grabCookie()`)
+    *   `restore` - to set cookies (by default `I.amOnPage('/'); I.setCookie(cookie)`)
+
+#### How It Works
+
+1.  `restore` method is executed. It should open a page and set credentials.
+2.  `check` method is executed. It should reload a page (so cookies are applied) and check that this page belongs to logged-in user. When you pass the second args `session`, you could perform the validation using passed session.
+3.  If `restore` and `check` were not successful, `login` is executed
+4.  `login` should fill in login form
+5.  After successful login, `fetch` is executed to save cookies into memory or file.
+
+#### Example: Simple login
+
+```js
+auth: {
+  enabled: true,
+  saveToFile: true,
+  inject: 'login',
+  users: {
+    admin: {
+      // loginAdmin function is defined in `steps_file.js`
+      login: (I) => I.loginAdmin(),
+      // if we see `Admin` on page, we assume we are logged in
+      check: (I) => {
+         I.amOnPage('/');
+         I.see('Admin');
+      }
+    }
+  }
+}
+```
+
+#### Example: Multiple users
+
+```js
+auth: {
+  enabled: true,
+  saveToFile: true,
+  inject: 'loginAs', // use `loginAs` instead of login
+  users: {
+    user: {
+      login: (I) => {
+         I.amOnPage('/login');
+         I.fillField('email', 'user@site.com');
+         I.fillField('password', '123456');
+         I.click('Login');
+      },
+      check: (I) => {
+         I.amOnPage('/');
+         I.see('User', '.navbar');
+      },
+    },
+    admin: {
+      login: (I) => {
+         I.amOnPage('/login');
+         I.fillField('email', 'admin@site.com');
+         I.fillField('password', '123456');
+         I.click('Login');
+      },
+      check: (I) => {
+         I.amOnPage('/');
+         I.see('Admin', '.navbar');
+      },
+    },
+  }
+}
+```
+
+#### Example: Keep cookies between tests
+
+If you decide to keep cookies between tests you don't need to save/retrieve cookies between tests.
+But you need to login once work until session expires.
+For this case, disable `fetch` and `restore` methods.
+
+```js
+helpers: {
+   WebDriver: {
+     // config goes here
+     keepCookies: true; // keep cookies for all tests
+   }
+},
+plugins: {
+   auth: {
+     users: {
+       admin: {
+         login: (I) => {
+           I.amOnPage('/login');
+           I.fillField('email', 'admin@site.com');
+           I.fillField('password', '123456');
+           I.click('Login');
+         },
+         check: (I) => {
+           I.amOnPage('/dashboard');
+           I.see('Admin', '.navbar');
+         },
+         fetch: () => {}, // empty function
+         restore: () => {}, // empty funciton
+       }
+    }
+  }
+}
+```
+
+#### Example: Getting sessions from local storage
+
+If your session is stored in local storage instead of cookies you still can obtain sessions.
+
+```js
+plugins: {
+   auth: {
+    admin: {
+      login: (I) => I.loginAsAdmin(),
+      check: (I) => I.see('Admin', '.navbar'),
+      fetch: (I) => {
+        return I.executeScript(() => localStorage.getItem('session_id'));
+      },
+      restore: (I, session) => {
+        I.amOnPage('/');
+        I.executeScript((session) => localStorage.setItem('session_id', session), session);
+      },
+    }
+  }
+}
+```
+
+#### Tips: Using async function in the auth
+
+If you use async functions in the auth plugin, login function should be used with `await` keyword.
+
+```js
+auth: {
+  enabled: true,
+  saveToFile: true,
+  inject: 'login',
+  users: {
+    admin: {
+      login: async (I) => {  // If you use async function in the auth plugin
+         const phrase = await I.grabTextFrom('#phrase')
+         I.fillField('username', 'admin'),
+         I.fillField('password', 'password')
+         I.fillField('phrase', phrase)
+      },
+      check: (I) => {
+         I.amOnPage('/');
+         I.see('Admin');
+      },
+    }
+  }
+}
+```
+
+```js
+Scenario('login', async ( {I, login} ) => {
+  await login('admin') // you should use `await`
+})
+```
+
+#### Tips: Using session to validate user
+
+Instead of asserting on page elements for the current user in `check`, you can use the `session` you saved in `fetch`
+
+```js
+auth: {
+  enabled: true,
+  saveToFile: true,
+  inject: 'login',
+  users: {
+    admin: {
+      login: async (I) => {  // If you use async function in the auth plugin
+         const phrase = await I.grabTextFrom('#phrase')
+         I.fillField('username', 'admin'),
+         I.fillField('password', 'password')
+         I.fillField('phrase', phrase)
+      },
+      check: (I, session) => {
+         // Throwing an error in `check` will make CodeceptJS perform the login step for the user
+         if (session.profile.email !== the.email.you.expect@some-mail.com) {
+              throw new Error ('Wrong user signed in');
+        }
+      },
+    }
+  }
+}
+```
+
+```js
+Scenario('login', async ( {I, login} ) => {
+  await login('admin') // you should use `await`
+})
+```
+
+### Parameters
+
+*   `config` &#x20;

package/docs/plugins/autoDelay.md

@@ -0,0 +1,48 @@
+---
+permalink: /plugins/autoDelay
+editLink: false
+sidebar: auto
+title: autoDelay
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## 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.
+
+For instance, if you click a button and nothing happens - probably JS event is not attached to this button yet
+Also, if you fill field and input validation doesn't accept your input - maybe because you typed value too fast.
+
+This plugin allows to slow down tests execution when a test running too fast.
+It puts a tiny delay for before and after action commands.
+
+Commands affected (by default):
+
+*   `click`
+*   `fillField`
+*   `checkOption`
+*   `pressKey`
+*   `doubleClick`
+*   `rightClick`
+
+#### Configuration
+
+```js
+plugins: {
+   autoDelay: {
+     enabled: true
+   }
+}
+```
+
+Possible config options:
+
+*   `methods`: list of affected commands. Can be overridden
+*   `delayBefore`: put a delay before a command. 100ms by default
+*   `delayAfter`: put a delay after a command. 200ms by default
+
+### Parameters
+
+*   `config` &#x20;

package/docs/plugins/browser.md

@@ -0,0 +1,41 @@
+---
+permalink: /plugins/browser
+editLink: false
+sidebar: auto
+title: browser
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## browser
+
+Overrides browser helper config from the command line. Works for all browser helpers
+(Playwright, Puppeteer, WebDriver, Appium) without touching `codecept.conf`.
+
+Enable it via `-p` option with one or more colon-chained args:
+
+    npx codeceptjs run -p browser:show
+    npx codeceptjs run -p browser:hide
+    npx codeceptjs run -p browser:browser=firefox
+    npx codeceptjs run -p browser:windowSize=1024x768:video=false
+    npx codeceptjs run -p browser:hide:browser=webkit:windowSize=800x600
+
+#### Args
+
+*   **show** — force visible browser
+*   **hide** — force headless (also injects `--headless` into WebDriver chrome/firefox capability args)
+*   **`<key>=<value>`** — set `helpers.<eachBrowserHelper>.<key> = <value>`. Three keys
+    get per-helper translation via `setBrowserConfig`:
+    *   `browser=<name>` — Puppeteer receives `product`, Playwright receives `browser`
+    *   `windowSize=WxH` — also adds `--window-size=W,H` chromium/chrome args
+    *   `show=true|false` — toggles `show` on Playwright/Puppeteer; injects/strips
+        `--headless` in WebDriver chrome/firefox capability args
+
+Values stay as strings. `true` / `false` are coerced to booleans.
+
+Requires `@codeceptjs/configure` to be installed; if missing, the plugin
+logs a hint and skips the override.
+
+### Parameters
+
+*   `config`   

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`