codeceptjs 4.0.0-rc.23 → 4.0.0-rc.24

package/docs/reports.md

@@ -21,13 +21,19 @@ plugins: {
   testomatio: {
     enabled: true,
     require: '@testomatio/reporter/codecept',
+    html: true,
+    markdown: true,
+    csv: true,
+    reportDir: 'output/report',
   },
 }
 ```
 
+The local reports above are enabled directly from CodeceptJS config. If `reportDir` is omitted, reports are written to `output/report` using the CodeceptJS `output` directory.
+
 ### Enable an output
 
-Each output turns on when you set its environment variable. Run your tests as usual — one run feeds every output you enabled.
+Each output can also be enabled with environment variables. Run your tests as usual and one run feeds every output you enabled.
 
 | To get… | Set | Details |
 | --- | --- | --- |
@@ -63,7 +69,9 @@ The GitHub pipe also needs the job to grant `permissions: pull-requests: write`.
 
 A single self-contained HTML file with the run summary and, per test, its steps, screenshots, logs, and error. It needs no API key and no service, so it works anywhere — open it locally or attach it to a CI build.
 
-![HTML report](https://raw.githubusercontent.com/testomatio/reporter/master/docs/pipes/images/html-pipe.png)
+![HTML report](./images/testomatio-html-report.png)
+
+- Preferred in CodeceptJS 4: enable `html: true` in `plugins.testomatio` and run `npx codeceptjs run`
 
 - `TESTOMATIO_HTML_REPORT_SAVE=1` — enable the report
 - `TESTOMATIO_HTML_REPORT_FOLDER=output/reports` — keep it inside CodeceptJS's `output/` dir (default folder is `html-report`)
@@ -118,6 +126,10 @@ Posts a comment to the Pull Request with the same summary. Comments are created
 
 ### Markdown Report
 
+- Preferred in CodeceptJS 4: enable `markdown: true` in `plugins.testomatio` and run `npx codeceptjs run`
+
+![Markdown report](./images/testomatio-markdown-report.png)
+
 A single self-contained Markdown file — renders in PR comments, CI job summaries, and Slack, and is convenient for AI agents reading test results. Needs no API key.
 
 - `TESTOMATIO_MARKDOWN_REPORT_SAVE=1` — enable the report
@@ -161,12 +173,14 @@ plugins: {
 
 Hooks: `onHookFinished`, `onTestBefore`, `onTestPassed`, `onTestFailed`, `onTestSkipped`, `onTestFinished`, `onResult`.
 
-For Mocha reporters, use `--reporter`:
+For built-in Mocha reporters, use `--reporter`:
 
 ```sh
-npx codeceptjs run --reporter mochawesome --reporter-options reportDir=output
+npx codeceptjs run --reporter dot
 ```
 
+> The bundled `Mochawesome` helper was removed in 4.x. For an HTML report use the [Testomat.io Reporter](https://github.com/testomatio/reporter) HTML pipe (see above); for JUnit XML use the [`junitReporter`](#junit-xml) plugin. Wiring multiple Mocha reporters through `mocha-multi`/`cmr` is not recommended — prefer these instead.
+
 Plugins exist for [TestRail](https://www.npmjs.com/package/codeceptjs-testrail) and [Tesults](https://www.npmjs.com/package/codeceptjs-tesults).
 
 ## CLI output

package/docs/retry.md

@@ -20,24 +20,36 @@ CodeceptJS provides flexible retry mechanisms to handle flaky tests. Use retries
 
 ## Helper Retries
 
-Browser automation helpers (Playwright, Puppeteer, WebDriver) have **built-in retry mechanisms** for element interactions. When you call `I.click('Button')`, Playwright automatically waits for the element to exist, be visible, stable, and enabled — retrying for up to 5 seconds.
+Plawright has a built-in retry mechanism for element interactions. When you call `I.click('Button')`, after the element is located Playwright keeps retrying until it is actionable — up to `timeout` (default 5s).
 
-Configure the timeout in your helper settings:
+> WebDriver has a different auto-retry option: [smartWait](/webdriver#smartwait)
+
+Even though the handle exists (from `.all()`), Playwright still waits for it to become visible, stable (not mid-animation), enabled, not covered by an overlay/modal, and not rerendering.
 
 ```js
 helpers: {
   Playwright: {
-    timeout: 5000,      // retry actions for up to 5 seconds
-    waitForAction: 100  // wait 100ms before each action
+    timeout: 5000,      // retry the action until the element is actionable
+    waitForAction: 100  // fixed pause AFTER click/doubleClick/pressKey
   }
 }
 ```
 
-**Learn more:** [Playwright Helper](/helpers/Playwright), [Timeouts](/timeouts)
+What each setting does:
+
+```
+find element (no wait — fails instantly if locator matches nothing)
+  → wait up to `timeout` for it to become actionable   ← timeout
+  → perform action
+  → sleep `waitForAction` ms                            ← waitForAction (settle pause, not a wait)
+```
+
+`timeout` covers the action. If the locator matches nothing yet, the step fails immediately. Use [Failed Step Retries](#failed-step-retries) to cover that gap.
+
 
 ## Failed Step Retries
 
-Automatically retry all failed steps without modifying test code:
+CodeceptJS retries all failed steps by default by using the `retryFailedStep` plugin.
 
 ```js
 plugins: {
@@ -66,18 +78,36 @@ Scenario('manual retries only', { disableRetryFailedStep: true }, ({ I }) => {
 })
 ```
 
-Full plugin options:
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `retries` | — | Retries per step |
-| `minTimeout` | — | Milliseconds before first retry |
-| `maxTimeout` | `Infinity` | Max milliseconds between retries |
-| `factor` | — | Exponential backoff multiplier |
-| `randomize` | `false` | Randomize timeout intervals |
-| `ignoredSteps` | `[]` | Patterns/regex of steps to never retry |
-| `deferToScenarioRetries` | `true` | Disable step retries when scenario retries exist |
-| `when` | `() => true` | Function receiving error; return `true` to retry |
+Defaults: `minTimeout: 150`, `factor: 1.5`, `maxTimeout: 10000`.
+
+
+> See [plugin reference](/plugins/retry-failed-step) for more options
+
+Retries are calculated via this formula:
+
+```
+gap(N) = min(minTimeout × factor^(N-1), maxTimeout)
+```
+
+Practically if step fails it will trigger a retry with increasing delay until `maxTimeout` is reached:
+
+```
+retries: 2                              => 0.15s-0.4s (150,225ms)
+retries: 3                              => 0.15s-0.7s (150,225,338ms)
+retries: 3, minTimeout: 1000            => 1s-4.75s   (1s,1.5s,2.25s)
+retries: 3, minTimeout: 1000, factor: 2 => 1s-7s      (1s,2s,4s)
+retries: 5, minTimeout: 1000, factor: 2 => 1s-25s     (1s,2s,4s,8s,10s)
+```
+
+Playwright `timeout` adds to each attempt only when the element is found:
+
+- `Playwright.timeout: 5000`
+- `retries: 2, minTimeout: 1000`
+
+```
+element not found => 0 + (1s+1s)    = 2s
+element found but not interactable  => 3×5s + (1s+1s) = 17s
+```
 
 ## Manual Step Retries
 

package/docs/store.md

@@ -0,0 +1,94 @@
+---
+permalink: /store
+title: Store
+---
+
+# Store
+
+`store` is a global object that holds the state of the current run — which test and step are executing, which modes are enabled, and where the project lives on disk. Listeners, plugins, and helpers read it to find out *where in the lifecycle* they are without threading that information through every call.
+
+```js
+import { store } from 'codeceptjs'
+
+event.dispatcher.on(event.step.before, () => {
+  if (store.dryRun) return            // skip side effects on a dry run
+  console.log(`running ${store.currentTest?.title}`)
+})
+```
+
+It is a single shared object for the whole process. Read from it freely; write to it only if you are deliberately driving execution state (see [Writing to the store](#writing-to-the-store)).
+
+## Fields
+
+### Required
+
+Set once when the runner starts and immutable afterwards. Resolved from the test root, falling back to the legacy `global.codecept_dir` / `global.output_dir`.
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `store.codeceptDir` | `string` | root directory of the tests |
+| `store.outputDir` | `string` | resolved output directory for artifacts |
+| `store.workerMode` | `boolean` | `true` when running inside a [parallel](/parallel) worker |
+
+### Session config
+
+Set at session start and stable for that session. They reflect how the run was invoked.
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `store.debugMode` | `boolean` | run started with `--debug` |
+| `store.timeouts` | `boolean` | [timeouts](/timeouts) are enabled |
+| `store.autoRetries` | `boolean` | step auto-retries are active (the `tryTo` [effect](/effects) turns this off while it runs) |
+| `store.dryRun` | `boolean` | run is a `--dry-run`; steps must not cause side effects |
+| `store.featureOnly` | `boolean` | a `Feature.only()` was used |
+| `store.scenarioOnly` | `boolean` | a `Scenario.only()` was used |
+| `store.maskSensitiveData` | `boolean \| object` | mask [secret](/secrets) values in output |
+| `store.noGlobals` | `boolean` | `noGlobals` mode — the user imports everything instead of relying on globals |
+
+### State
+
+Changes constantly as the run progresses. The most useful fields for plugins and listeners:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `store.onPause` | `boolean` | execution is paused inside [`pause()`](/basics#pause) |
+| `store.currentTest` | `Test \| null` | the running test, or `null` between tests |
+| `store.currentStep` | `Step \| null` | the running step, or `null` |
+| `store.currentSuite` | `Suite \| null` | the running suite, or `null` between suites |
+| `store.tsFileMapping` | `Map \| null` | TypeScript source-map lookup, when running `.ts` tests |
+
+`currentTest`, `currentStep`, and `currentSuite` carry the same objects passed to lifecycle events — see the [test and step object](/architecture#test-object) fields.
+
+## Reading the store
+
+A typical use is gating expensive or unsafe work by run mode:
+
+```js
+import { store, recorder } from 'codeceptjs'
+
+event.dispatcher.on(event.test.before, () => {
+  if (store.dryRun || store.workerMode) return
+
+  recorder.add('seed fixture data', async () => {
+    await api.post('/users', { name: 'john' })
+  })
+})
+```
+
+`store.currentTest` is the simplest way to attach context to the current test from anywhere — for example tagging an artifact:
+
+```js
+import { store } from 'codeceptjs'
+
+store.currentTest?.artifacts.push({ name: 'log', path: '/tmp/run.log' })
+```
+
+## Writing to the store
+
+CodeceptJS keeps the state fields current for you — the built-in [`store` listener](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/listener/store.js) sets `currentSuite` and `currentTest` around each suite and test. You rarely need to write to it.
+
+Write only when you are deliberately driving execution — for example, a tool that opens `pause()` sets `store.onPause`. The required fields (`codeceptDir`, `outputDir`) are locked after `store.initialize()` and cannot be reassigned.
+
+---
+
+**See also:** [Architecture](/architecture) · [Extending CodeceptJS](/hooks) · [Events](/architecture#events)

package/docs/timeouts.md

@@ -118,7 +118,7 @@ plugins: {
 When multiple timeouts are configured, CodeceptJS applies them in priority order:
 
 1. **stepTimeoutHard** — plugin with `overrideStepLimits: true`
-2. **codeLimitTime** — `step.timeout()` or `I.limitTime()`
+2. **codeLimitTime** — `step.timeout()`
 3. **stepTimeoutSoft** — plugin with `overrideStepLimits: false`
 4. **testOrSuite** — global test/suite timeout