codeceptjs 4.0.0-rc.2 → 4.0.0-rc.20

package/docs/commands.md

@@ -0,0 +1,352 @@
+---
+permalink: /commands
+title: Commands
+---
+
+# Commands
+
+## Run
+
+Executes tests. Requires `codecept.conf.js` config to be present in provided path.
+
+---
+
+Run all tests from current dir
+
+```sh
+npx codeceptjs run
+```
+
+Load config and run tests from `test` dir
+
+```sh
+npx codeceptjs run -c test
+```
+
+Run only tests with "signin" word in name
+
+```sh
+npx codeceptjs run --grep "signin"
+```
+
+Run all tests without "@IEOnly" word in name
+
+```sh
+npx codeceptjs run --grep "@IEOnly" --invert
+```
+
+Run single test [path to codecept.js] [test filename]
+
+```sh
+npx codeceptjs run github_test.js
+```
+
+Run single test with steps printed
+
+```sh
+npx codeceptjs run github_test.js --steps
+```
+
+Run test files in shuffled order
+
+```sh
+npx codeceptjs run --shuffle
+```
+
+Run single test in debug mode (see more in [debugging](#Debugging) section)
+
+```sh
+npx codeceptjs run github_test.js --debug
+```
+
+Select config file manually (`-c` or `--config` option)
+
+```sh
+npx codeceptjs run -c my.codecept.conf.js
+npx codeceptjs run --config path/to/codecept.conf.js
+```
+
+Override config on the fly. Provide valid JSON which will be merged into current config:
+
+```sh
+npx codeceptjs run --override '{ "helpers": {"WebDriver": {"browser": "chrome"}}}'
+```
+
+Run tests and produce xunit report:
+
+```sh
+npx codeceptjs run --reporter xunit
+```
+
+Use any of [Mocha reporters](https://github.com/mochajs/mocha/tree/master/lib/reporters) used.
+
+#### Debugging 
+
+Run single test in debug mode
+
+```sh
+npx codeceptjs run --debug
+```
+
+Run test with internal logs printed.
+
+```sh
+npx codeceptjs run --verbose
+```
+
+Display complete debug output including scheduled promises
+
+```
+DEBUG=codeceptjs:* npx codeceptjs run
+```
+
+## Plugin Arguments
+
+`run`, `run-workers`, `run-multiple`, `run-rerun` and `dry-run` accept a `-p` (`--plugins`) flag to enable plugins on the command line, with optional arguments per plugin. Tokens are colon-chained per plugin, comma-separated across plugins:
+
+```sh
+npx codeceptjs run -p <name>                       # enable plugin
+npx codeceptjs run -p <name>:<arg1>:<arg2>         # enable + pass args
+npx codeceptjs run -p <plugin1>,<plugin2>:<arg>    # multiple plugins
+```
+
+Plugins listed via `-p` are activated even when their config has `enabled: false` (or no `enabled` flag). This is the supported way to switch a plugin on for a single run without editing `codecept.conf`.
+
+A few examples:
+
+```sh
+npx codeceptjs run -p pause                              # pause on first failure (default on=fail)
+npx codeceptjs run -p pause:on=step                      # pause before every step
+npx codeceptjs run -p pause:on=url:pattern=/checkout/*   # pause on URL match
+npx codeceptjs run -p "screenshot:on=step;slides=true"   # produce a step-by-step HTML report
+```
+
+### Browser Control
+
+The built-in `browser` plugin overrides browser-helper config from the CLI — works for Playwright, Puppeteer, WebDriver and Appium without editing `codecept.conf`.
+
+```sh
+npx codeceptjs run -p browser:show                       # force visible browser
+npx codeceptjs run -p browser:hide                       # force headless
+npx codeceptjs run -p browser:browser=firefox            # switch engine
+npx codeceptjs run -p browser:windowSize=1024x768        # set viewport
+npx codeceptjs run -p browser:hide:browser=webkit:windowSize=800x600
+```
+
+Tokens after `browser:` are either flags (`show`, `hide`) or `key=value` pairs. Three keys get per-helper translation:
+
+- `browser=<name>` — Puppeteer receives `product`, Playwright/WebDriver receive `browser`. Validated per helper (`chromium`/`webkit`/`firefox` for Playwright, `chrome`/`firefox` for Puppeteer).
+- `show=true|false` (or the `show`/`hide` flag) — sets `show` on Playwright/Puppeteer; injects/strips `--headless` in WebDriver chrome/firefox capability args.
+- `windowSize=WxH` — sets `windowSize` on every helper; also adds `--window-size=W,H` to chromium/chrome args for Playwright/Puppeteer.
+
+Anything else (`-p browser:video=false:waitForTimeout=10000`) is shallow-merged onto every browser helper present in config. Values are coerced (`true`/`false` → boolean, digits → Number, otherwise string).
+
+## Run Workers
+
+Run tests in parallel threads. CodeceptJS supports different distribution strategies for optimal performance.
+
+```bash
+# Run with 3 workers using default strategy (pre-assign tests)
+npx codeceptjs run-workers 3
+
+# Run with pool mode for dynamic test distribution (recommended)
+npx codeceptjs run-workers 3 --by pool
+
+# Run with suite distribution
+npx codeceptjs run-workers 3 --by suite
+
+# Pool mode with filtering
+npx codeceptjs run-workers 4 --by pool --grep "@smoke"
+```
+
+**Test Distribution Strategies:**
+
+- `--by test` (default): Pre-assigns individual tests to workers
+- `--by suite`: Pre-assigns entire test suites to workers  
+- `--by pool`: Dynamic distribution for optimal load balancing (recommended for best performance)
+
+The pool mode provides the best load balancing by maintaining tests in a shared pool and distributing them dynamically as workers become available. This prevents workers from sitting idle and ensures optimal CPU utilization, especially when tests have varying execution times.
+
+See [Parallel Execution](/parallel) documentation for more details.
+
+## Run Rerun <Badge text="Since 3.3.6" type="warning"/>
+
+Run tests multiple times to detect and fix flaky tests.
+
+```
+npx codeceptjs run-rerun
+```
+
+For this command configuration is required:
+
+```js
+{
+  // inside codecept.conf.js
+  rerun: {
+    // how many times all tests should pass
+    minSuccess: 2,
+
+    // how many times to try to rerun all tests
+    maxReruns: 4,
+  }
+}
+```
+
+Use Cases:
+
+* `minSuccess: 1, maxReruns: 5` - run all tests no more than 5 times, until first successful run.
+* `minSuccess: 3, maxReruns: 5` - run all tests no more than 5 times, until reaching 3 successfull runs.
+* `minSuccess: 10, maxReruns: 10` - run all tests exactly 10 times, to check their stability.
+
+
+## Dry Run
+
+Prints test scenarios without executing them
+
+```
+npx codeceptjs dry-run
+```
+
+When passed `--steps` or `--debug` option runs tests, disabling all plugins and helpers, so you can get step-by-step report with no tests actually executed.
+
+```
+npx codeceptjs dry-run --steps
+```
+
+If a plugin needs to be enabled in `dry-run` mode, pass its name in `-p` option:
+
+```
+npx codeceptjs dry-run --steps -p allure
+```
+
+If some plugins need to be enabled in `dry-run` mode, pass its name in `-p` option:
+
+```
+npx codeceptjs dry-run --steps -p allure,customLocator
+```
+
+If all plugins need to be enabled in `dry-run` mode, pass its name in `-p` option:
+
+```
+npx codeceptjs dry-run --steps -p all
+```
+
+To enable bootstrap script in dry-run mode, pass in `--bootstrap` option when running with `--steps` or `--debug`
+
+```
+npx codeceptjs dry-run --steps --bootstrap
+```
+
+## Run Multiple
+
+> ⚠️ prefer using run-workers instead
+
+Run multiple suites. Unlike `run-workers` spawns processes to execute tests.
+[Requires additional configuration](/advanced#multiple-browsers-execution) and can be used to execute tests in multiple browsers.
+
+```sh
+npx codeceptjs run-multiple smoke:chrome regression:firefox
+```
+
+## Init
+
+Creates `codecept.conf.js` file in current directory:
+
+```sh
+npx codeceptjs init
+```
+
+Or in provided path
+
+```sh
+npx codecept init test
+```
+
+## Migrate
+
+Migrate your current `codecept.json` to `codecept.conf.js`
+
+```sh
+npx codeceptjs migrate
+```
+
+## Shell
+
+Interactive shell. Allows to try `I.` commands in runtime
+
+```sh
+npx codeceptjs shell
+```
+
+## Generators
+
+Create new test
+
+```sh
+npx codeceptjs generate:test
+```
+
+Create new pageobject
+
+```sh
+npx codeceptjs generate:pageobject
+```
+
+Create new helper
+
+```sh
+npx codeceptjs generate:helper
+```
+
+## TypeScript Definitions
+
+TypeScript Definitions allows IDEs to provide autocompletion when writing tests.
+
+```sh
+npx codeceptjs def
+npx codeceptjs def --config path/to/codecept.conf.js
+```
+
+After doing that IDE should provide autocompletion for `I` object inside `Scenario` and `within` blocks.
+
+Add optional parameter `output` (or shortcut `-o`), if you want to place your definition file in specific folder:
+
+```sh
+npx codeceptjs def --output ./tests/typings
+npx codeceptjs def -o ./tests/typings
+```
+
+## List Commands
+
+Prints all available methods of `I` to console.
+
+```sh
+npx codeceptjs list
+```
+
+Use `-c` to point at a specific config (same as `run`):
+
+```sh
+npx codeceptjs list -c ./test/acceptance/codecept.Playwright.js
+```
+
+Add `--docs` to print full documentation (description, examples, `@param` annotations) below each action — pulled from helper JSDoc and `docs/webapi/*` snippets:
+
+```sh
+npx codeceptjs list --docs
+```
+
+Use `--action` to show docs for a single action. The `I.` prefix is optional and `--docs` is implied:
+
+```sh
+npx codeceptjs list --action amOnPage
+npx codeceptjs list --action I.click -c ./test/acceptance/codecept.Playwright.js
+```
+
+## Local Environment Information
+
+Prints debugging information concerning the local environment
+
+```sh
+npx codeceptjs info
+```

package/docs/community-helpers.md

@@ -0,0 +1,63 @@
+---
+permalink: /community-helpers
+title: Community Helpers
+editLink: false
+---
+
+# Community Helpers
+> Share your helpers at our [Wiki Page](https://github.com/codeceptjs/CodeceptJS/wiki/Community-Helpers)
+
+Here is the list of helpers created by our community.
+Please **add your own** by editing this page.
+## Webhooks
+
+* [codeceptjs-webhook-helper](https://github.com/onemolegames/codeceptjs-webhook-helper) - to check webhook calls during the tests.
+
+## Email Checking
+
+* [MailCatcher](https://gist.github.com/schmkr/026732dfa1627b927ff3a08dc31ee884) - to check emails via Mailcatcher locally.
+* [codeceptjs-mailhog-helper](https://github.com/tsuemura/codeceptjs-mailhog-helper) - to check emails via Mailhog locally.
+* [codeceptjs-testmailapp-helper](https://github.com/pavkam/codeceptjs-testmailapp-helper) - to check emails via Testmail.app service.
+* [codeceptjs-mailosaurhelper](https://github.com/yurkovychv/codeceptjs-mailosaur) - to check emails via [Mailosaur](https://mailosaur.com/) service.
+
+## Data Sources
+
+* [codeceptjs-httpmock](https://github.com/testphony/codeceptjs-httpMock) -  a helper which wraps mockttp library to manage http mock in tests.
+* [codeceptjs-http](https://github.com/testphony/codeceptjs-http) - a helper which wraps then-request library to process HTTP requests. It's alternative helper that provides more flexible request management.
+* [codeceptjs-dbhelper](https://github.com/thiagodp/codeceptjs-dbhelper) - allows you to execute queries or commands to databases using database-js. 
+
+## Cloud Providers
+* [codeceptjs-saucehelper](https://github.com/puneet0191/codeceptjs-saucehelper/) - a helper which updates `Test Names` & `Test Results` on Saucelabs 
+* [codeceptjs-bshelper](https://github.com/PeterNgTr/codeceptjs-bshelper) - a helper which updates `Test Names` & `Test Results` on Browserstack 
+* [codeceptjs-tbhelper](https://github.com/testingbot/codeceptjs-tbhelper) - a helper which updates `Test Names` & `Test Results` on TestingBot 
+
+## Visual-Testing
+* [codeceptjs-resemblehelper](https://github.com/puneet0191/codeceptjs-resemblehelper) - a helper which helps with visual testing using resemble.js. 
+* [codeceptjs-applitoolshelper](https://www.npmjs.com/package/codeceptjs-applitoolshelper) - a helper which helps interaction with [Applitools](https://applitools.com)
+* [codeceptjs-pixelmatchhelper](https://github.com/stracker-phil/codeceptjs-pixelmatchhelper) - a helper that integrates pixelmatch for visual testing. 
+
+## Reporters
+* [codeceptjs-rphelper](https://github.com/reportportal/agent-js-codecept) is a CodeceptJS helper which can publish tests results on ReportPortal after execution.
+* [codeceptjs-xray-helper](https://www.npmjs.com/package/codeceptjs-xray-helper) is a CodeceptJS helper which can publish tests results on [XRAY](https://confluence.xpand-it.com/display/XRAYCLOUD/Import+Execution+Results+-+REST).
+* [codeceptjs-xray-cloud-helper](https://www.npmjs.com/package/codeceptjs-xray-cloud-helper) is a helper that automatically retrieves the result of CodeceptJS tests and sends them to XRAY/JIRA(cloud version) via [XRAY Cloud API](https://docs.getxray.app/display/XRAYCLOUD/Import+Execution+Results+-+REST+v2#ImportExecutionResultsRESTv2-XrayJSONresults).
+* [codeceptjs-slack-reporter](https://www.npmjs.com/package/codeceptjs-slack-reporter) Get a Slack notification when one or more scenarios fail.
+* [codeceptjs-browserlogs-plugin](https://github.com/pavkam/codeceptjs-browserlogs-plugin) Record the browser logs for failed tests.
+* [codeceptjs-testrail](https://github.com/PeterNgTr/codeceptjs-testrail) - a plugin to integrate with [Testrail](https://www.gurock.com/testrail)
+* [codeceptjs-monocart-coverage](https://github.com/cenfun/codeceptjs-monocart-coverage) - a plugin to generate coverage reports, it integrate with [monocart coverage reports](https://github.com/cenfun/monocart-coverage-reports)
+
+## Browser request control
+* [codeceptjs-resources-check](https://github.com/luarmr/codeceptjs-resources-check) Load a URL with Puppeteer and listen to the requests while the page is loading. Enabling count the number or check the sizes of the requests.
+
+## Assertion & Validations
+* [codeceptjs-chai](https://www.npmjs.com/package/codeceptjs-chai) is a CodeceptJS helper which wraps
+[chai](https://www.chaijs.com/) library to complete chai assertion steps with CodeceptJS logging.
+
+## Other
+
+* [codeceptjs-cmdhelper](https://github.com/thiagodp/codeceptjs-cmdhelper) allows you to run commands in the terminal/console
+* [eslint-plugin-codeceptjs](https://www.npmjs.com/package/eslint-plugin-codeceptjs) Eslint rules for CodeceptJS.
+* [codeceptjs-datalayer-helper](https://github.com/kobenguyent/codeceptjs-datalayer-helper) CodeceptJS DataLayer helper helps you to get the datalayer JavaScript array that is used to store information and send this data to the tag manager.
+* [codeceptjs-a11y-helper](https://github.com/kobenguyent/codeceptjs-a11y-helper) accessibility tests integrated with CodeceptJS - Playwright-axe
+* [codeceptjs-lighthouse-helper](https://github.com/kobenguyent/codeceptjs-lighthouse-helper) lighthouse audit integrated with CodeceptJS - Playwright
+* [Snowplow Data analytics](https://www.npmjs.com/package/@viasat/codeceptjs-snowplow-helper) - Test your Snowplow events implementations with CodeceptJS and Snowplow Micro.
+* [codeceptjs-failure-logger](https://github.com/kobenguyent/codeceptjs-failure-logger) - Log failed CodeceptJS tests to file

package/docs/configuration.md

@@ -0,0 +1,230 @@
+---
+permalink: /configuration
+title: Configuration
+---
+
+# Configuration
+
+CodeceptJS configuration is set in `codecept.conf.js` file.
+
+After running `codeceptjs init` it should be saved in test root.
+
+| Name                 | Type                                                         | Description                                                                                                                                                                                                                                                                                                                                                                          |
+| :------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bootstrap?`         | (() => `Promise`<`void`\>) \| `boolean` \| `string`          | [Execute code before](https://codecept.io/bootstrap/) tests are run. Can be either JS module file or async function: `bootstrap: async () => server.launch(), ` or `bootstrap: 'bootstrap.js', `                                                                                                                                                                                     |
+| `bootstrapAll?`      | (() => `Promise`<`void`\>) \| `boolean` \| `string`          | [Execute code before launching tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)                                                                                                                                                                                                                                                                      |
+| `gherkin?`           | { `features`: `string` \| `string`[] ; `steps`: `string`[] } | Enable [BDD features](https://codecept.io/bdd/#configuration). Sample configuration: `gherkin: {   features: "./features/*.feature",   steps: ["./step_definitions/steps.js"] } `                                                                                                                                                                                                    |
+| `gherkin.features`   | `string` \| `string`[]                                       | load feature files by pattern. Multiple patterns can be specified as array                                                                                                                                                                                                                                                                                                           |
+| `gherkin.steps`      | `string`[]                                                   | load step definitions from JS files                                                                                                                                                                                                                                                                                                                                                  |
+| `grep?`              | `string`                                                     | Pattern to filter tests by name. This option is useful if you plan to use multiple configs for different environments. To execute only tests with @firefox tag use `grep: '@firefox' `                                                                                                                                                                                               |
+| `helpers?`           | {}                                                           | Enable and configure helpers: `helpers: {   Playwright: {     url: 'https://mysite.com',     browser: 'firefox'   } } `                                                                                                                                                                                                                                                              |
+| `include?`           | `any`                                                        | Include page objects to access them via dependency injection `I: "./custom_steps.js", loginPage: "./pages/Login.js", User: "./pages/User.js", ` Configured modules can be injected by name in a Scenario: `Scenario('test', { I, loginPage, User }) `                                                                                                                                |
+| `mocha?`             | `any`                                                        | [Mocha test runner options](https://mochajs.org/#configuring-mocha-nodejs), additional [reporters](https://codecept.io/reports/#xml) can be configured here. Example: `mocha: {   "mocha-junit-reporter": {      stdout: "./output/console.log",      options: {        mochaFile: "./output/result.xml",        attachments: true //add screenshot for a failed test      }   } } ` |
+| `noGlobals?`         | `boolean`                                                    | Disable registering global functions (Before, Scenario, etc). Not recommended                                                                                                                                                                                                                                                                                                        |
+| `output`             | `string`                                                     | Where to store failure screenshots, artifacts, etc `output: './output' `                                                                                                                                                                                                                                                                                                             |
+| `plugins?`           | `any`                                                        | Enable CodeceptJS plugins. Example: `plugins: {   autoDelay: {     enabled: true   }  } `                                                                                                                                                                                                                                                                                            |
+| `require?`           | `string`[]                                                   | [Require additional JS modules](https://codecept.io/configuration/#require) Example: `require: ["should"]`                                                                                                                                                                                                                                                                           |
+| `teardown?`          | (() => `Promise`<`void`\>) \| `boolean` \| `string`          | [Execute code after tests](https://codecept.io/bootstrap/) finished. Can be either JS module file or async function: `teardown: async () => server.stop(), ` or `teardown: 'teardown.js', `                                                                                                                                                                                          |
+| `teardownAll?`       | (() => `Promise`<`void`\>) \| `boolean` \| `string`          | [Execute JS code after finishing tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)                                                                                                                                                                                                                                                                    |
+| `tests`              | `string`                                                     | Pattern to locate CodeceptJS tests. Allows to enter glob pattern or an Array<string> of patterns to match tests / test file names. For tests in JavaScript: `tests: 'tests/**.test.js' ` For tests in TypeScript: `tests: 'tests/**.test.ts' `                                                                                                                                       |
+| `timeout?`           | `number`                                                     | Set default tests timeout in seconds. Tests will be killed on no response after timeout. `timeout: 20, `                                                                                                                                                                                                                                                                             |
+| `translation?`       | `string`                                                     | Enable [localized test commands](https://codecept.io/translation/)                                                                                                                                                                                                                                                                                                                   |
+| `maskSensitiveData?` | `boolean`                                                    | Enable to mask Sensitive Data in console.                                                                                                                                                                                                                                                                                                                                            |
+
+## Require
+
+Requires modules before running tests. This is useful for:
+- **Assertion libraries:** e.g., `'should'` instead of manually requiring it in each test
+- **TypeScript loaders:** Enable TypeScript test files in ESM or CommonJS projects
+- **Setup modules:** Initialize testing environment
+- **Custom modules:** With relative paths like `"require": ["./lib/setup"]`
+
+### TypeScript Support
+
+#### For ESM Projects (CodeceptJS 4.x)
+
+Use modern loaders that support ES Modules:
+
+**Using tsx (recommended - fast, zero config):**
+
+```typescript
+// codecept.conf.ts
+export const config = {
+  tests: './**/*_test.ts',
+  require: ['tsx/cjs'],  // ← Modern TypeScript loader
+  helpers: {},
+  include: {},
+}
+```
+
+**Using ts-node/esm:**
+
+```typescript
+// codecept.conf.ts
+export const config = {
+  tests: './**/*_test.ts',
+  require: ['ts-node/esm'],  // ← Established TypeScript loader
+  helpers: {},
+  include: {},
+}
+```
+
+> **Note:** For ts-node/esm, you need a tsconfig.json with ESM configuration. See [TypeScript documentation](/typescript) for details.
+
+#### For CommonJS Projects (CodeceptJS 3.x)
+
+Use the CommonJS loader:
+
+```javascript
+// codecept.conf.js
+exports.config = {
+  tests: './*_test.ts',
+  require: ['ts-node/register'],  // ← CommonJS TypeScript loader
+  helpers: {},
+  include: {},
+}
+```
+
+### Multiple Requires
+
+You can combine multiple modules:
+
+```typescript
+// codecept.conf.ts
+export const config = {
+  tests: ['./**/*_test.ts', './smoke_test.ts'],
+  require: [
+    'tsx/cjs',           // TypeScript loader
+    'should',            // Assertion library
+    './lib/testSetup'    // Custom setup
+  ],
+  helpers: {},
+  include: {},
+}
+```
+
+Modules are loaded in the order specified, before any tests run.
+
+## Dynamic Configuration
+
+By default `codecept.json` is used for configuration. You can override its values in runtime by using `--override` or `-o` option in command line, passing valid JSON as a value:
+
+```sh
+codeceptjs run -o '{ "helpers": {"WebDriver": {"browser": "firefox"}}}'
+```
+
+You can also switch to JS configuration format for more dynamic options.
+Create `codecept.conf.js` file and make it export `config` property.
+
+See the config example:
+
+```js
+export const config = {
+  helpers: {
+    WebDriver: {
+      // load variables from the environment and provide defaults
+      url: process.env.CODECEPT_URL || 'http://localhost:3000',
+
+      user: process.env.CLOUDSERVICE_USER,
+      key: process.env.CLOUDSERVICE_KEY,
+
+      coloredLogs: true,
+      waitForTimeout: 10000,
+    },
+  },
+
+  // don't build monolithic configs
+  mocha: require('./mocha.conf.js') || {},
+  include: {
+    I: './src/steps_file.js',
+    loginPage: './src/pages/login_page',
+    dashboardPage: new DashboardPage(),
+  },
+
+  // here goes config as it was in codecept.conf.ts
+  // ....
+}
+```
+
+(Don't copy-paste this config, it's just demo)
+
+If you prefer to store your configuration files in a different location, or with a different name, you can do that with `--config` or `-c:
+
+```sh
+codeceptjs run --config=./path/to/my/config.js
+```
+
+## Common Configuration Patterns
+
+> 📺 [Watch this material](https://www.youtube.com/watch?v=onBnfo_rJa4&t=4s) on YouTube
+
+[`@codeceptjs/configure`](https://github.com/codeceptjs/configure) ships with CodeceptJS as a dependency and contains shared recipes for common configuration patterns. It lets you set meta-configuration that's independent of the active helper.
+
+Toggle headless/headed mode, change window size, etc.:
+
+```js
+import { setHeadlessWhen, setWindowSize } from '@codeceptjs/configure'
+
+setHeadlessWhen(process.env.CI)
+setWindowSize(1600, 1200)
+
+export const config = {
+  // ...
+}
+```
+
+For one-shot bundles use `setBrowserConfig` — pass any subset of `{ browser, show, windowSize, url, ... }` and the right per-helper translation happens automatically (Puppeteer receives `product` for `browser`, WebDriver gets `--headless` injected, etc.). Keys whose value is `undefined` are skipped, so unset env vars don't clobber existing config:
+
+```js
+import { setBrowserConfig } from '@codeceptjs/configure'
+
+setBrowserConfig({
+  browser: process.env.BROWSER,        // optional engine override
+  show: !process.env.HEADLESS,         // headed unless HEADLESS is set
+  windowSize: '1280x720',
+  url: process.env.URL,                // overrides helper.url when set
+})
+```
+
+`setCommonPlugins()` enables a curated set of plugins and registers a few more as discoverable (so they can be activated ad-hoc via [`-p` plugin arguments](/commands#plugin-arguments) without editing config):
+
+```js
+import { setCommonPlugins } from '@codeceptjs/configure'
+
+setCommonPlugins()
+```
+
+| Plugin            | Default        | Notes                                                                          |
+| :---------------- | :------------- | :----------------------------------------------------------------------------- |
+| `retryFailedStep` | enabled        | Retry steps that fail with transient errors                                    |
+| `screenshot`      | enabled        | Screenshot on `fail` (default) / `test` / `step` / `file` / `url`              |
+| `pause`           | registered     | Pause on failure / step / file / URL — `-p pause:on=fail`, `-p pause:on=step`, `-p pause:on=file:path=tests/login_test.js`, `-p pause:on=url:pattern=/checkout/*` |
+| `browser`         | registered     | CLI overrides for browser helpers — `-p browser:show`, `-p browser:browser=firefox`, see [commands](/commands#browser-control) |
+| `aiTrace`         | registered     | Capture AI traces — `-p aiTrace`, narrow with `on=fail|test|step|file|url`     |
+| `heal`            | registered     | Self-heal failing steps — `-p heal`, narrow with `on=file|url`                 |
+
+> `eachElement`, `tryTo`, and `retryTo` are no longer plugins in 4.x — import them from `codeceptjs/effects`.
+
+## Profile
+
+Using `process.env.profile` you can change the config dynamically.
+It provides value of `--profile` option passed to runner.
+Use its value to change config value on the fly.
+
+For instance, with the config above we can change browser value using `profile` option
+
+```sh
+codeceptjs run --profile firefox
+```
+
+```js
+export const config = {
+  helpers: {
+    WebDriver: {
+      url: 'http://localhost:3000',
+      // load value from `profile`
+      browser: process.env.profile || 'firefox',
+    },
+  },
+}
+```