codeceptjs 4.0.2-beta.9 → 4.0.2

package/docs/els.md

@@ -0,0 +1,328 @@
+## Element Access
+
+The `els` module provides low-level element manipulation functions for CodeceptJS tests, allowing for more granular control over element interactions and assertions. Elements are wrapped in a unified `WebElement` class that provides a consistent API across all helpers (Playwright, WebDriver, Puppeteer).
+
+> **Note:** For a comprehensive guide on element-based testing patterns and best practices, see [Element-Based Testing](element-based-testing.md).
+
+### Usage
+
+Import the els functions in your test file:
+
+```js
+import { element, eachElement, expectElement, expectAnyElement, expectAllElements } from 'codeceptjs/els'
+```
+
+## element
+
+The `element` function allows you to perform custom operations on the first matching element found by a locator. It provides a low-level way to interact with elements when the built-in helper methods aren't sufficient.
+
+### Syntax
+
+```js
+element(purpose, locator, fn);
+// or
+element(locator, fn);
+```
+
+### Parameters
+
+- `purpose` (optional) - A string describing the operation being performed. If omitted, a default purpose will be generated from the function.
+- `locator` - A locator string/object to find the element(s).
+- `fn` - An async function that receives the element as its argument and performs the desired operation. `el` argument is a `WebElement` wrapper providing a consistent API across all helpers.
+
+### Returns
+
+Returns the result of the provided async function executed on the first matching element.
+
+### Example
+
+```js
+Scenario('my test', async ({ I }) => {
+  // combine element function with standard steps:
+  I.amOnPage('/cart');
+
+  // but use await every time you use element function
+  await element(
+    // with explicit purpose
+    'check custom attribute',
+    '.button',
+    async el => await el.getAttribute('data-test'),
+  );
+
+  // or simply
+  await element('.button', async el => {
+    return await el.isEnabled();
+  });
+});
+```
+
+### Notes
+
+- Only works with helpers that implement the `_locate` method
+- The function will only operate on the first element found, even if multiple elements match the locator
+- The provided callback must be an async function
+- Throws an error if no helper with `_locate` method is enabled
+
+## eachElement
+
+The `eachElement` function allows you to perform operations on each element that matches a locator. It's useful for iterating through multiple elements and performing the same operation on each one.
+
+### Syntax
+
+```js
+eachElement(purpose, locator, fn);
+// or
+eachElement(locator, fn);
+```
+
+### Parameters
+
+- `purpose` (optional) - A string describing the operation being performed. If omitted, a default purpose will be generated from the function.
+- `locator` - A locator string/object to find the element(s).
+- `fn` - An async function that receives two arguments:
+  - `el` - The current element being processed
+  - `index` - The index of the current element in the collection
+
+### Returns
+
+Returns a promise that resolves when all elements have been processed. If any element operation fails, the function will throw the first encountered error.
+
+### Example
+
+```js
+Scenario('my test', async ({ I }) => {
+  // combine element function with standard steps:
+  I.click('/hotels');
+
+  // iterate over elements but don't forget to put await
+  await eachElement(
+    'validate list items', // explain your actions for future review
+    '.list-item', // locator
+    async (el, index) => {
+      const text = await el.getText();
+      console.log(`Item ${index}: ${text}`);
+    },
+  );
+
+  // Or simply check if all checkboxes are checked
+  await eachElement('input[type="checkbox"]', async el => {
+    const checked = await el.getProperty('checked');
+    if (!checked) {
+      throw new Error('Found unchecked checkbox');
+    }
+  });
+});
+```
+
+### Notes
+
+- Only works with helpers that implement the `_locate` method
+- The function will process all elements that match the locator
+- The provided callback must be an async function
+- If an operation fails on any element, the error is logged and the function continues processing remaining elements
+- After all elements are processed, if any errors occurred, the first error is thrown
+- Throws an error if no helper with `_locate` method is enabled
+
+## expectElement
+
+The `expectElement` function allows you to perform assertions on the first element that matches a locator. It's designed for validating element properties or states and will throw an assertion error if the condition is not met.
+
+### Syntax
+
+```js
+expectElement(locator, fn);
+```
+
+### Parameters
+
+- `locator` - A locator string/object to find the element(s).
+- `fn` - An async function that receives the element as its argument and should return a boolean value:
+  - `true` - The assertion passed
+  - `false` - The assertion failed
+
+### Returns
+
+Returns a promise that resolves when the assertion is complete. Throws an assertion error if the condition is not met.
+
+### Example
+
+```js
+// Check if a button is enabled
+await expectElement('.submit-button', async el => {
+  return await el.isEnabled();
+});
+
+// Verify element has specific text content
+await expectElement('.header', async el => {
+  const text = await el.getText();
+  return text === 'Welcome';
+});
+
+// Check for specific attribute value
+await expectElement('#user-profile', async el => {
+  const role = await el.getAttribute('role');
+  return role === 'button';
+});
+```
+
+### Notes
+
+- Only works with helpers that implement the `_locate` method
+- The function will only check the first element found, even if multiple elements match the locator
+- The provided callback must be an async function that returns a boolean
+- The assertion message will include both the locator and the function used for validation
+- Throws an error if no helper with `_locate` method is enabled
+
+## expectAnyElement
+
+The `expectAnyElement` function allows you to perform assertions where at least one element from a collection should satisfy the condition. It's useful when you need to verify that at least one element among many matches your criteria.
+
+### Syntax
+
+```js
+expectAnyElement(locator, fn);
+```
+
+### Parameters
+
+- `locator` - A locator string/object to find the element(s).
+- `fn` - An async function that receives the element as its argument and should return a boolean value:
+  - `true` - The assertion passed for this element
+  - `false` - The assertion failed for this element
+
+### Returns
+
+Returns a promise that resolves when the assertion is complete. Throws an assertion error if no elements satisfy the condition.
+
+### Example
+
+```js
+Scenario('validate any element matches criteria', async ({ I }) => {
+  // Navigate to the page
+  I.amOnPage('/products');
+
+  // Check if any product is marked as "in stock"
+  await expectAnyElement('.product-item', async el => {
+    const status = await el.getAttribute('data-status');
+    return status === 'in-stock';
+  });
+
+  // Verify at least one price is below $100
+  await expectAnyElement('.price-tag', async el => {
+    const price = await el.getText();
+    return parseFloat(price.replace('$', '')) < 100;
+  });
+
+  // Check if any button in the list is enabled
+  await expectAnyElement('.action-button', async el => {
+    return await el.isEnabled();
+  });
+});
+```
+
+### Notes
+
+- Only works with helpers that implement the `_locate` method
+- The function will check all matching elements until it finds one that satisfies the condition
+- Stops checking elements once the first matching condition is found
+- The provided callback must be an async function that returns a boolean
+- Throws an assertion error if no elements satisfy the condition
+- Throws an error if no helper with `_locate` method is enabled
+
+## expectAllElements
+
+The `expectAllElements` function verifies that every element matching the locator satisfies the given condition. It's useful when you need to ensure that all elements in a collection meet specific criteria.
+
+### Syntax
+
+```js
+expectAllElements(locator, fn);
+```
+
+### Parameters
+
+- `locator` - A locator string/object to find the element(s).
+- `fn` - An async function that receives the element as its argument and should return a boolean value:
+  - `true` - The assertion passed for this element
+  - `false` - The assertion failed for this element
+
+### Returns
+
+Returns a promise that resolves when all assertions are complete. Throws an assertion error as soon as any element fails the condition.
+
+### Example
+
+```js
+Scenario('validate all elements meet criteria', async ({ I }) => {
+  // Navigate to the page
+  I.amOnPage('/dashboard');
+
+  // Verify all required fields have the required attribute
+  await expectAllElements('.required-field', async el => {
+    const required = await el.getAttribute('required');
+    return required !== null;
+  });
+
+  // Check if all checkboxes in a form are checked
+  await expectAllElements('input[type="checkbox"]', async el => {
+    const checked = await el.getProperty('checked');
+    return checked === true;
+  });
+
+  // Verify all items in a list have non-empty text
+  await expectAllElements('.list-item', async el => {
+    const text = await el.getText();
+    return text.trim().length > 0;
+  });
+
+  // Ensure all buttons in a section are enabled
+  await expectAllElements('#action-section button', async el => {
+    return await el.isEnabled();
+  });
+});
+```
+
+### Notes
+
+- Only works with helpers that implement the `_locate` method
+- The function checks every element that matches the locator
+- Fails fast: stops checking elements as soon as one fails the condition
+- The provided callback must be an async function that returns a boolean
+- The assertion message will include which element number failed (e.g., "element #2 of...")
+- Throws an error if no helper with `_locate` method is enabled
+
+## WebElement API
+
+Elements passed to your callbacks are wrapped in a `WebElement` class that provides a consistent API across all helpers. For complete documentation of the WebElement API, see [WebElement](WebElement.md).
+
+Quick reference of available methods:
+
+```js
+await element('.my-element', async el => {
+  // Get element information
+  const text = await el.getText()
+  const attr = await el.getAttribute('data-value')
+  const prop = await el.getProperty('value')
+  const html = await el.getInnerHTML()
+
+  // Check state
+  const visible = await el.isVisible()
+  const enabled = await el.isEnabled()
+  const exists = await el.exists()
+
+  // Interactions
+  await el.click()
+  await el.type('text')
+
+  // Child elements
+  const child = await el.$('.child')
+  const children = await el.$$('.child')
+
+  // Position
+  const box = await el.getBoundingBox()
+
+  // Native access
+  const helper = el.getHelper()
+  const native = el.getNativeElement()
+})
+```

package/docs/environment-variables.md

@@ -0,0 +1,131 @@
+---
+permalink: /environment-variables
+title: Environment Variables
+---
+
+# Environment Variables
+
+CodeceptJS reads several environment variables that change runtime behavior. They are useful for tuning CI runs, enabling extra logging, configuring the MCP server, or wiring values into the generated `codecept.conf.js`.
+
+This page is a reference for every `process.env.*` switch CodeceptJS reads or sets internally.
+
+## Quick Reference
+
+| Variable | Category | Default | Purpose |
+| :--- | :--- | :--- | :--- |
+| `profile` | Test execution | _unset_ | Profile name forwarded from `--profile`; readable from config and helpers. |
+| `CI` | Test execution | _unset_ | Auto-set by every CI provider; enables CI-aware behavior. |
+| `DONT_FAIL_ON_EMPTY_RUN` | Test execution | _unset_ | When set, do not fail CI if zero tests were executed. |
+| `RUNS_WITH_WORKERS` | Workers | _unset_ | Set to `true` while running in workers; read by helpers/plugins to branch behavior. |
+| `CODECEPT_WORKER_TIMEOUT` | Workers | `5m` | Hung-worker watchdog timeout. Accepts [ms](https://github.com/vercel/ms) strings (`30s`, `2m`, `1h`). |
+| `CODECEPT_AUTO_EXIT_TIMEOUT` | Workers | `2000` | Time in ms allowed for helper cleanup before forced `process.exit`. Set to `0` to disable. |
+| `DEBUG` | Debug | _unset_ | `debug` package namespace filter, e.g. `codeceptjs:*`, `codeceptjs:heal`. |
+| `HEADLESS` | Init template | _unset_ | Read by `setHeadlessWhen()` in the generated config to toggle headless mode. |
+| `BASE_URL` | Init template | `http://localhost` | Default URL written into the generated Playwright config. |
+
+## Test Execution
+
+### `profile`
+
+Set automatically when you pass `--profile <name>` to `run`, `run-workers`, `run-rerun`, `run-multiple`, or `interactive`. The value is available inside `codecept.conf.js`, helpers, and plugins via `process.env.profile`, which is the standard way to switch configuration based on environment:
+
+```js
+exports.config = {
+  helpers: {
+    Playwright: {
+      url: process.env.profile === 'staging' ? 'https://staging.example.com' : 'http://localhost:3000',
+    },
+  },
+}
+```
+
+### `CI`
+
+A de-facto standard variable exported by every major CI provider (GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis, etc.). CodeceptJS uses it for two CI-aware behaviors:
+
+- Extends the polling timeout for `submittedData()` to 60s (vs 2s locally).
+- Fails the run with exit code `1` if no tests were executed (see `DONT_FAIL_ON_EMPTY_RUN`).
+
+You should not need to set this manually.
+
+### `DONT_FAIL_ON_EMPTY_RUN`
+
+By default, when `CI` is set and no tests are executed (e.g. an over-restrictive `--grep`), CodeceptJS fails the run to surface false-positive green builds. Set `DONT_FAIL_ON_EMPTY_RUN=true` to keep the run green even when nothing ran.
+
+```yaml
+# .github/workflows/tests.yml
+env:
+  DONT_FAIL_ON_EMPTY_RUN: 'true'
+```
+
+## Workers
+
+### `RUNS_WITH_WORKERS`
+
+Automatically set to `'true'` while a `run-workers` invocation is active and reset to `'false'` when it finishes. Read it from helpers or plugins when you need to behave differently in worker mode — for example, to disable an interactive feature or change reporter output:
+
+```js
+if (process.env.RUNS_WITH_WORKERS === 'true') {
+  // running in a worker thread
+}
+```
+
+Do not set this manually.
+
+### `CODECEPT_WORKER_TIMEOUT`
+
+Per-worker hung-process watchdog. If a worker produces no output for this duration, it is auto-terminated and reported as failed. Accepts any string parsed by the [`ms`](https://github.com/vercel/ms) package: `30s`, `2m`, `5m`, `1h`. Defaults to `5m`.
+
+```sh
+CODECEPT_WORKER_TIMEOUT=10m npx codeceptjs run-workers 4
+```
+
+### `CODECEPT_AUTO_EXIT_TIMEOUT`
+
+Time in **milliseconds** that CodeceptJS waits for helper `_cleanup()` hooks to complete before calling `process.exit()`. Defaults to `2000`. Set to `0` to disable the auto-exit and let the Node event loop drain naturally — useful when long-running async work (e.g. report uploads) must complete after the test run.
+
+```sh
+CODECEPT_AUTO_EXIT_TIMEOUT=0 npx codeceptjs run
+```
+
+## Debug
+
+### `DEBUG`
+
+Standard [`debug`](https://www.npmjs.com/package/debug) package selector. CodeceptJS emits debug output under the `codeceptjs:*` namespace. Useful namespaces:
+
+| Namespace | Source |
+| :--- | :--- |
+| `codeceptjs:*` | All internal logs |
+| `codeceptjs:recorder` | Recorder/promise queue |
+| `codeceptjs:event` | Event dispatcher |
+| `codeceptjs:container` | DI container |
+| `codeceptjs:steps` | Step lifecycle |
+| `codeceptjs:exit` | Exit listener |
+| `codeceptjs:timeout` | Global timeout listener |
+| `codeceptjs:pause` | Interactive pause |
+| `codeceptjs:ai` | AI features |
+| `codeceptjs:heal` | Heal plugin |
+| `codeceptjs:analyze` | Analyze plugin |
+| `codeceptjs:retryFailedStep` | retryFailedStep plugin |
+| `codeceptjs:bdd` | Gherkin/BDD |
+
+```sh
+DEBUG="codeceptjs:*" npx codeceptjs run --verbose
+DEBUG="codeceptjs:heal" npx codeceptjs run
+DEBUG="codeceptjs:retryFailedStep" npx codeceptjs run
+```
+
+When `DEBUG` includes a `codeceptjs:` selector, the `heal` plugin keeps healing enabled in `--debug` mode (which otherwise disables it).
+
+## Init Template
+
+These variables are read by the configuration scaffolded by `codeceptjs init`. They have no effect unless your project's generated `codecept.conf.js` references them.
+
+### `HEADLESS`
+
+Read by [`setHeadlessWhen()`](https://www.npmjs.com/package/@codeceptjs/configure) in the generated config. When truthy, the browser starts headless. The init template wires this in so you can run `HEADLESS=true npx codeceptjs run` on CI without changing the config.
+
+### `BASE_URL`
+
+The init template uses `BASE_URL` (falling back to `http://localhost`) as the Playwright `url` value. After scaffolding, edit the generated config to change this default.

package/docs/examples.md

@@ -0,0 +1,160 @@
+---
+permalink: /examples
+layout: Section
+sidebar: false
+title: Examples
+editLink: false
+---
+
+# Examples
+
+> Add your own examples to our [Wiki Page](https://github.com/codeceptjs/CodeceptJS/wiki/Examples)
+
+## [TodoMVC Examples](https://github.com/codecept-js/examples)
+
+![](https://github.com/codecept-js/examples/raw/master/todo.png)
+
+Playground repository where you can run tests in different helpers on a basic single-page website.
+
+Tests repository demonstrate usage of
+
+- Playwright helper
+- Puppeteer helper
+- WebDriver helper
+- Toggle headless mode with env variables
+- PageObjects
+- Cucumber syntax
+
+## [Basic Examples](https://github.com/Codeception/CodeceptJS/tree/master/examples)
+
+CodeceptJS repo contains basic tests (both failing and passing) just to show how it works.
+Our team uses it to test new features and run simple scenarios.
+
+## [CodeceptJS Cucumber E2E Framework](https://github.com/gkushang/codeceptjs-e2e)
+
+This repository contains complete E2E framework for CodeceptJS with Cucumber and SauceLabs Integration
+
+- CodecepJS-Cucumber E2E Framework
+- Saucelabs Integration
+- Run Cross Browser tests in Parallel on SauceLabs with a simple command
+- Run tests on `chrome:headless`
+- Page Objects
+- `Should.js` Assertion Library
+- Uses `wdio` service (selenium-standalone, sauce)
+- Allure HTML Reports
+- Uses shared Master configuration
+- Sample example and feature files of GitHub Features
+
+## [Enterprise Grade Tests](https://github.com/uc-cdis/gen3-qa)
+
+Complex testing solution by [Gen3](https://github.com/uc-cdis/gen3-qa)
+
+Includes
+
+- classical CodeceptJS tests
+- BDD tests
+- Jenkins integration
+- Complex Before/BeforeSuite scripts and more
+
+## [Testing Single Page Application](https://github.com/bugiratracker/codeceptjs-demo)
+
+End 2 end tests for Task management app (currently offline).
+
+Tests repository demonstrate usage of
+
+- Puppeteer helper
+- ApiDataFactory helper
+- autoLogin plugin
+- Dynamic config with profiles
+
+## [Practical E2E Tests](https://gitlab.com/paulvincent/codeceptjs-e2e-testing)
+
+Examples from the book [Practical End 2 End Testing with CodeceptJS](https://leanpub.com/codeceptjs/) by **Paul Vincent Beigang**.
+
+This repository demonstrates usage of:
+
+- dynamic config with profiles
+- testing WYSIWYG editor
+- GitLab CI
+
+## [Amazon Tests v2](https://gitlab.com/thanhnguyendh/codeceptjs-wdio-services)
+
+Testing Amazon website using Selenium WebDriver.
+
+This repository demonstrates usage of:
+
+- WebDriver helper
+- Page Objects
+- wdio services (selenium-standalone)
+- Parallel execution
+- GitLab CI setup
+
+## [Tests with Docker Compose](https://github.com/mathesouza/codeceptjs-docker-compose)
+
+Running CodeceptJS tests with Docker Compose
+
+This repository demonstrates usage of:
+
+- CodeceptJS Docker image
+- WebDriver helper
+- Allure plugin
+
+## [AngularJS Example Tests](https://github.com/armno/angular-e2e-codeceptjs-example)
+
+Based on [Setting up End-to-End Testing in Angular Project with CodeceptJS](https://medium.com/@armno/setting-up-end-to-end-testing-in-angular-project-with-codeceptjs-ac1784de3420) post by Armno Prommarak.
+
+This repository demonstrates usage of
+
+- Puppeteer helper
+- Working with Angular CLI
+
+## [REST Example Tests](https://github.com/PeterNgTr/codeceptjs-rest-demo)
+
+This repository demonstrates usage of
+
+- REST helper
+
+## [Automation Starter](https://github.com/sjorrillo/automation-starter)
+
+The purpose of this application is for learning the basics and how to use good practices and useful tools in automation.
+
+- Puppeteer helper
+- Working with gherkin, also it has type definitions and to be able to use them inside when, given and then make sure you add `declare function inject(): { I: CodeceptJS.I, [key: string]: any; };`in the `steps.d.ts`file
+- Linting `airbnb-base`, `codeceptjs/codeceptjs` and full ES6 support
+
+## [Example for using: Puppeteer, Gherkin, Allure with parallel execution](https://github.com/SchnuckySchuster/codeceptJSExample)
+
+This is a ready to use example that shows how to integrate CodeceptJS with Puppeteer and Allure as reporting tool.
+
+- detailed ReadMe
+- tests written in cucumber alongside tests written in the codeceptJS DSL
+- puppeteer helper example
+- test steps, pages, fragments
+- examples for sequential and parallel execution
+- generation of allure test results
+
+## [Example for Advanced REST API testing: TypeScript, Axios, CodeceptJS, Jest Expect, Docker, Allure, Mock-Server, Prettier + Eslint, pre-commit, Jest Unit Tests ](https://github.com/EgorBodnar/rest-axios-codeceptjs-allure-docker-test-example)
+
+One button example with built-in mocked backend.
+
+If you already have a UI testing solution based on the CodeceptJS and you need to implement advanced REST API testing you can just extend your existing framework. Use this implementation as an example.
+This is necessary if all integrations with TMS and CI/CD are already configured, and you do not want to reconnect and configure the plugins and libraries used for the new test runner. Use CodeceptJS!
+
+- Easy run
+- Detailed README
+- Well documented mocked backend's REST API endpoints
+- HTTP request client with session support and unit tests
+- Exemplary code control
+- Ready to launch in a CI/CD system as is
+- OOP, Test data models and builders, endpoint decorators
+
+## [Playwright fun with CodeceptJS](https://github.com/PeterNgTr/codeceptjs-playwright-fun)
+
+- Tests are written in TS
+- CI/CD with Github Actions
+- Page Object Model is applied
+- ReportPortal Integration
+
+## How to
+
+- Create a plugin with TS [link](https://github.com/reutenkoivan/codeceptjs-plugins/tree/main/packages/html-snapshot-on-fail)