codeceptjs 4.0.0-rc.21 → 4.0.0-rc.23

package/docs/advanced.md

@@ -134,7 +134,7 @@ Feature('My feature', {key: val});
 Scenario('My scenario', {key: val},({ I }) => {});
 ```
 
-You can use this options for build your own [plugins](https://codecept.io/hooks/#plugins) with [event listners](https://codecept.io/hooks/#api). Example: 
+You can use these options to build your own [plugins](https://codecept.io/hooks#plugins) with [event listeners](https://codecept.io/architecture#events). Example: 
 
 ```js
   // for test

package/docs/architecture.md

@@ -0,0 +1,219 @@
+---
+permalink: /architecture
+title: Architecture
+---
+
+# CodeceptJS Architecture
+
+How CodeceptJS runs a test, and the internal modules you build [plugins, listeners, and helpers](/hooks) against.
+
+## How a Test Runs
+
+CodeceptJS is built on top of [Mocha](https://mochajs.org). A run goes through these stages:
+
+1. **Load.** CodeceptJS reads the config, builds the [container](#container) (helpers, support objects, plugins), and runs the `bootstrap` hook. `event.all.before` fires.
+2. **Suite.** For each suite, `event.suite.before` fires. Helper `_beforeSuite` hooks run.
+3. **Test.** For each test: `event.test.started` fires; `Before` hooks from helpers (`_before`) and from the suite run, then `event.test.before` fires; the scenario function runs; `event.test.passed` or `event.test.failed` fires; `After` hooks run; `event.test.after` and then `event.test.finished` fire.
+4. **Step.** Each `I.*` call inside a scenario becomes a step. It is *scheduled* onto the [recorder](#the-recorder) — `event.step.before` fires — then executed: `event.step.started`, `event.step.passed` or `event.step.failed`, `event.step.after`, `event.step.finished`.
+5. **Finish.** `event.suite.after` fires after each suite, `event.all.after` after the last one, and `event.all.result` when results are printed. The `teardown` hook runs.
+
+The key idea is step 4: **a scenario doesn't execute its steps as it runs** — it queues them. `I.click()` returns immediately; the [recorder](#the-recorder) runs the queued action later. This is why scenarios rarely need `await`, and why anything that injects async work has to go through the recorder.
+
+## The Internal API
+
+CodeceptJS exposes its internals as named exports of the `codeceptjs` package. Import only what you need:
+
+```js
+import { recorder, event, output, container, config } from 'codeceptjs'
+```
+
+| Export | What it is |
+| --- | --- |
+| [`codecept`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/codecept.js) | the test runner class |
+| [`config`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/config.js) | the loaded configuration |
+| [`container`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/container.js) | dependency-injection container: helpers, support objects, plugins, the Mocha instance |
+| [`recorder`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/recorder.js) | the global promise chain that orders every step |
+| [`event`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/event.js) | the event dispatcher and the names of all lifecycle events |
+| [`output`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/output.js) | the printer used for all console output |
+| [`helper`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/helper.js) | the base class every helper extends |
+| [`actor`](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/actor.js) | the base class behind the `I` object |
+
+> Older code relied on a global `codeceptjs` object (`const { recorder } = codeceptjs`). That global only exists under `noGlobals: false`, the deprecated 3.x default — prefer named imports.
+
+The [API reference](https://github.com/codeceptjs/CodeceptJS/tree/master/docs/api) on GitHub documents these modules; the source is the final word.
+
+## The Recorder
+
+The recorder is a single global promise chain. Every step a scenario "calls" is appended to it, and the chain runs the steps one after another. To run your own async code at the right point in a test, append it to the recorder too:
+
+```js
+import { event, recorder } from 'codeceptjs'
+
+event.dispatcher.on(event.test.before, () => {
+  recorder.add('seed fixture data', async () => {
+    await api.post('/users', { name: 'john', email: 'john@example.com' })
+  })
+})
+```
+
+- `recorder.add(name, fn)` — append `fn` (async, or returning a promise) to the chain. The name shows up in `--verbose` output.
+- `recorder.startUnlessRunning()` — start a chain if none is running. Call it before `add()` from a listener that may fire outside a running chain, such as `event.all.before`.
+- `recorder.retry({ retries, when })` — retry failing steps that match `when`. See [conditional retries](/helpers#conditional-retries).
+
+Run tests with `--verbose` to watch the recorder schedule and execute each entry.
+
+## Container
+
+The container resolves helpers and support objects by name:
+
+```js
+import { container } from 'codeceptjs'
+
+const helpers = container.helpers()          // every helper, keyed by name
+const { Playwright } = container.helpers()   // one helper
+const support = container.support()          // every support object
+const { UserPage } = container.support()     // one page object
+const plugins = container.plugins()          // enabled plugins
+const mocha = container.mocha()              // the current Mocha instance
+```
+
+Add objects at runtime — useful from a `bootstrap` script:
+
+```js
+import { container } from 'codeceptjs'
+import UserPage from './pages/user.js'
+
+container.append({
+  helpers: { MyHelper: new MyHelper({ host: 'http://example.com' }) },
+  support: { UserPage },
+})
+```
+
+## Events
+
+`event.dispatcher` is a Node `EventEmitter`. Attach listeners to it from a [plugin](/hooks#plugins) or `bootstrap` script.
+
+Events are **sync** or **async**:
+
+- **sync** — fires the moment the action happens. Do synchronous work only.
+- **async** — fires when the action is *scheduled*. To do async work in the right order, queue it with `recorder.add()`.
+
+| Event | Kind | When |
+| --- | --- | --- |
+| `event.all.before` | — | before any test runs |
+| `event.suite.before(suite)` | async | before a suite |
+| `event.test.started(test)` | sync | at the very start of a test |
+| `event.test.before(test)` | async | after `Before` hooks from helpers and the test are run |
+| `event.test.passed(test)` | sync | test passed |
+| `event.test.failed(test, err)` | sync | test failed |
+| `event.test.skipped(test)` | sync | test skipped |
+| `event.test.after(test)` | async | after each test |
+| `event.test.finished(test)` | sync | test finished |
+| `event.suite.after(suite)` | async | after a suite |
+| `event.step.before(step)` | async | step scheduled for execution |
+| `event.step.started(step)` | sync | step starts executing |
+| `event.step.passed(step)` | sync | step passed |
+| `event.step.failed(step, err)` | sync | step failed |
+| `event.step.after(step)` | async | after a step |
+| `event.step.finished(step)` | sync | step finished |
+| `event.step.comment(step)` | sync | a comment such as `I.say(...)` |
+| `event.bddStep.before(step)` / `event.bddStep.after(step)` | async | around a Gherkin step |
+| `event.hook.started(hook)` / `event.hook.passed` / `event.hook.failed` / `event.hook.finished` | sync | around `Before` / `After` / `BeforeSuite` / `AfterSuite` hooks |
+| `event.all.after` | — | after all tests |
+| `event.all.result(result)` | — | when results are printed |
+| `event.all.failures(failures)` | — | when a run reports failures |
+| `event.workers.before` / `event.workers.after` / `event.workers.result(result)` | — | around a [parallel run](/parallel) (parent process only) |
+
+The [built-in listeners](https://github.com/codeceptjs/CodeceptJS/tree/master/lib/listener) are working examples — every reporter and several plugins are listeners.
+
+### Test object
+
+Test events pass a test object with these fields:
+
+- `title` — the test title
+- `body` — the test function as a string
+- `opts` — test options such as `retries` (see [test options](/advanced#test-options))
+- `pending` — `true` while scheduled, `false` once finished
+- `tags` — array of [tags](/test-structure#tags) for this test
+- `artifacts` — files attached to this test (screenshots, videos, …), shared across reporters
+- `file` — path to the test file
+- `steps` — executed steps (only on `test.passed`, `test.failed`, `test.finished`)
+- `skipInfo` — present when the test was skipped: `{ message, description }`
+
+### Step object
+
+Step events pass a step object with these fields:
+
+- `name` — the step name, such as `see` or `click`
+- `actor` — the current actor, usually `I`
+- `helper` — the helper instance that executes this step
+- `helperMethod` — the helper method, usually the same as `name`
+- `status` — `passed` or `failed`
+- `prefix` — for a step inside a `within` block, the within text (e.g. `Within .js-signup-form`)
+- `args` — the arguments passed to the step
+
+## Config
+
+```js
+import { config } from 'codeceptjs'
+
+config.get()                       // the full config object
+config.get('myKey')                // one value
+config.get('myKey', 'fallback')    // one value, with a default
+```
+
+## Output
+
+Output has four verbosity levels, each toggled by a CLI flag:
+
+| Level | Flag | Use |
+| --- | --- | --- |
+| default | — | `output.print` — basic information |
+| steps | `--steps` | step execution |
+| debug | `--debug` | steps plus `output.debug` |
+| verbose | `--verbose` | debug plus `output.log` (internal logs and recorder activity) |
+
+```js
+import { output } from 'codeceptjs'
+
+output.print('basic information')
+output.debug('debug information')
+output.log('verbose logging information')
+```
+
+Use these instead of `console.log` so messages respect the chosen verbosity.
+
+## Helpers and the Actor
+
+The `I` object is an **actor** assembled from the enabled helpers. Each `I.method()` call delegates to the matching helper method and is wrapped as a step. Methods whose names start with `_` are private to the helper and not exposed on `I`. To add your own actions, write a [custom helper](/helpers).
+
+## Running CodeceptJS from Code
+
+CodeceptJS can be driven from your own script. Create the runner with a config and options, initialize it, then bootstrap, load tests, and run:
+
+```js
+import { codecept as Codecept } from 'codeceptjs'
+
+const config = { helpers: { Playwright: { browser: 'chromium', url: 'http://localhost' } } }
+const opts = { steps: true }
+
+const codecept = new Codecept(config, opts)
+codecept.init(import.meta.dirname)   // the test root directory
+
+try {
+  await codecept.bootstrap()
+  codecept.loadTests('**/*_test.js')
+  await codecept.run()               // pass a test file path to run only that file
+} catch (err) {
+  console.error(err)
+  process.exitCode = 1
+} finally {
+  await codecept.teardown()
+}
+```
+
+> To run tests inside workers from a script, see [parallel execution](/parallel).
+
+---
+
+**See also:** [Extending CodeceptJS](/hooks) · [Custom Helpers](/helpers) · [Plugins](/plugins) · [Bootstrap & Teardown](/bootstrap)

package/docs/configuration.md

@@ -5,167 +5,129 @@ 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.                                                                                                                                                                                                                                                                                                                                            |
+`codeceptjs init` creates a `codecept.conf.js` (or `codecept.conf.ts`) in your test root. It exports a `config` object:
 
-## Require
+```js
+export const config = {
+  tests: './**/*_test.js',
+  output: './output',
+  helpers: {
+    Playwright: { url: 'http://localhost', browser: 'chromium' },
+  },
+  include: {
+    I: './steps_file.js',
+  },
+}
+```
 
-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"]`
+## Options
 
-### TypeScript Support
+**Tests and files**
 
-#### For ESM Projects (CodeceptJS 4.x)
+- `tests` — glob pattern (or array of patterns) locating your test files, e.g. `'tests/**/*_test.js'` (or `*_test.ts` for TypeScript).
+- `output` — directory for failure screenshots, artifacts, and temporary files. Default `./output`.
+- `include` — page objects and support objects exposed via dependency injection: `{ I: './steps_file.js', loginPage: './pages/Login.js' }`. They can then be injected by name — `Scenario('test', ({ I, loginPage }) => …)`.
+- `require` — extra modules to load before tests run: assertion libraries, TypeScript loaders, setup files. See [Require](#require).
+- `grep` — run only tests whose name matches this pattern, e.g. `grep: '@firefox'`. Handy when you keep separate configs per environment.
 
-Use modern loaders that support ES Modules:
+**Helpers and plugins**
 
-**Using tsx (recommended - fast, zero config):**
+- `helpers` — enable and configure [helpers](/helpers): `{ Playwright: { url: 'https://mysite.com', browser: 'firefox' } }`.
+- `plugins` — enable [plugins](/plugins): `{ autoDelay: { enabled: true } }`.
 
-```typescript
-// codecept.conf.ts
-export const config = {
-  tests: './**/*_test.ts',
-  require: ['tsx/cjs'],  // ← Modern TypeScript loader
-  helpers: {},
-  include: {},
-}
-```
+**Hooks**
 
-**Using ts-node/esm:**
+- `bootstrap` / `teardown` — run code before / after the whole run; an async function or a path to a JS module. See [Bootstrap](/bootstrap).
+- `bootstrapAll` / `teardownAll` — run once around a parallel run (before any worker starts / after all finish). See [bootstrapAll / teardownAll](/bootstrap#bootstrapall-teardownall).
 
-```typescript
-// codecept.conf.ts
-export const config = {
-  tests: './**/*_test.ts',
-  require: ['ts-node/esm'],  // ← Established TypeScript loader
-  helpers: {},
-  include: {},
-}
-```
+**Test runner**
 
-> **Note:** For ts-node/esm, you need a tsconfig.json with ESM configuration. See [TypeScript documentation](/typescript) for details.
+- `timeout` — default per-test timeout in seconds; a test is killed if it stops responding.
+- `mocha` — [Mocha options](https://mochajs.org/#configuring-mocha-nodejs), including extra reporters. See [Reporters](/reports).
 
-#### For CommonJS Projects (CodeceptJS 3.x)
+**BDD**
 
-Use the CommonJS loader:
+- `gherkin` — enable [BDD features](/bdd#configuration): `{ features: './features/*.feature', steps: ['./step_definitions/steps.js'] }`.
+  - `gherkin.features` — feature file glob, or an array of globs.
+  - `gherkin.steps` — JS files with step definitions.
 
-```javascript
-// codecept.conf.js
-exports.config = {
-  tests: './*_test.ts',
-  require: ['ts-node/register'],  // ← CommonJS TypeScript loader
-  helpers: {},
-  include: {},
-}
-```
+**TypeScript**
+
+- `fullPromiseBased` — generate typings where `I.*` methods return promises, so you can `await` each command. See [TypeScript](/typescript#promise-based-typings).
+
+**Other**
 
-### Multiple Requires
+- `translation` — enable [localized commands](/translation).
+- `maskSensitiveData` — mask secrets in console output.
+- `noGlobals` — don't register the global functions (`Feature`, `Scenario`, `Before`, …). Not recommended.
 
-You can combine multiple modules:
+## Require
+
+`require` loads modules before tests run — assertion libraries (`'should'`), setup files (`'./lib/setup'`), and TypeScript loaders. Modules load in the order listed.
+
+For TypeScript test files in CodeceptJS 4.x, use the [`tsx`](https://tsx.is) loader:
 
-```typescript
+```ts
 // codecept.conf.ts
 export const config = {
-  tests: ['./**/*_test.ts', './smoke_test.ts'],
-  require: [
-    'tsx/cjs',           // TypeScript loader
-    'should',            // Assertion library
-    './lib/testSetup'    // Custom setup
-  ],
+  tests: './**/*_test.ts',
+  require: ['tsx/cjs'],
   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:
+Combine several modules:
 
-```sh
-codeceptjs run -o '{ "helpers": {"WebDriver": {"browser": "firefox"}}}'
+```ts
+require: ['tsx/cjs', 'should', './lib/testSetup']
 ```
 
-You can also switch to JS configuration format for more dynamic options.
-Create `codecept.conf.js` file and make it export `config` property.
+The config file itself (`codecept.conf.ts`) and helpers are transpiled automatically — only test files need the loader. See [TypeScript](/typescript) for the full setup.
+
+## Dynamic configuration
 
-See the config example:
+A JS/TS config file is plain code, so you can read environment variables and build the config at runtime:
 
 ```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(),
+    loginPage: './src/pages/login_page.js',
   },
-
-  // 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:
+Override config values at runtime with `--override` / `-o`, passing JSON:
 
 ```sh
-codeceptjs run --config=./path/to/my/config.js
+npx codeceptjs run -o '{ "helpers": { "WebDriver": { "browser": "firefox" } } }'
 ```
 
-## Common Configuration Patterns
+Point at a non-default config file with `--config` / `-c`:
 
-> 📺 [Watch this material](https://www.youtube.com/watch?v=onBnfo_rJa4&t=4s) on YouTube
+```sh
+npx codeceptjs run --config ./path/to/config.js
+```
 
-[`@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.
+## Common configuration patterns
 
-Toggle headless/headed mode, change window size, etc.:
+[`@codeceptjs/configure`](https://github.com/codeceptjs/configure) ships with CodeceptJS as a dependency. It holds shared recipes for config that's independent of the active helper.
+
+Toggle headless mode, set window size, and so on:
 
 ```js
 import { setHeadlessWhen, setWindowSize } from '@codeceptjs/configure'
 
-setHeadlessWhen(process.env.CI)
+setHeadlessWhen(process.env.HEADLESS || process.env.CI)
 setWindowSize(1600, 1200)
 
 export const config = {
@@ -173,20 +135,20 @@ 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:
+For one-shot bundles use `setBrowserConfig` — pass any subset of `{ browser, show, windowSize, url }` and the right per-helper translation happens automatically (Puppeteer gets `product`, WebDriver gets `--headless` injected, …). Keys whose value is `undefined` are skipped, so an unset env var won'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
+  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
+  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):
+`setCommonPlugins()` enables a curated set of plugins and registers a few more as discoverable, so they can be switched on ad-hoc with [`-p` plugin arguments](/commands#plugin-arguments) without editing the config:
 
 ```js
 import { setCommonPlugins } from '@codeceptjs/configure'
@@ -194,27 +156,21 @@ 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`                 |
+- `retryFailedStep` — *enabled*. Retries steps that fail with transient errors.
+- `screenshot` — *enabled*. Screenshot on `fail` (default), or `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 [browser control](/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
+`process.env.profile` carries the value of the `--profile` CLI option, so you can branch the config on it:
 
 ```sh
-codeceptjs run --profile firefox
+npx codeceptjs run --profile firefox
 ```
 
 ```js
@@ -222,8 +178,7 @@ export const config = {
   helpers: {
     WebDriver: {
       url: 'http://localhost:3000',
-      // load value from `profile`
-      browser: process.env.profile || 'firefox',
+      browser: process.env.profile || 'chrome',
     },
   },
 }