codeceptjs 4.0.0-rc.20 → 4.0.0-rc.22

package/docs/retry.md

@@ -7,6 +7,17 @@ title: Retry Mechanisms
 
 CodeceptJS provides flexible retry mechanisms to handle flaky tests. Use retries when dealing with unstable environments, network delays, or timing issues — not to mask bugs in your code.
 
+## Retry Levels
+
+* [helper retries](#helper-retries) — happen low level on browser interaction (resolves rendering of elements)
+* [failed step retries](#failed-step-retries) — performed by CodeceptJS on step fail
+* [manual step retries](#manual-step-retries) — on known flaky steps
+* [multiple steps retry](#multiple-steps-retry) — retry a group of steps together as a single operation
+* [self-healing steps](#self-healing-steps) — AI-powered recovery that continues tests without changing test code
+* [scenario retry](#scenario-retry) — retry entire test scenarios on failure
+* [feature retry](#feature-retry) — retry all scenarios within a feature
+* [hook retries](#hook-retries) — retry `Before`/`After` hooks on failure
+
 ## 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.
@@ -24,38 +35,7 @@ helpers: {
 
 **Learn more:** [Playwright Helper](/helpers/Playwright), [Timeouts](/timeouts)
 
-## CodeceptJS Retry Levels
-
-When helper retries aren't enough, CodeceptJS adds retry layers on top.
-
-### 1. Manual Step Retry
-
-Retry a specific step known to be flaky:
-
-```js
-import step from 'codeceptjs/steps'
-
-Scenario('checkout', ({ I }) => {
-  I.amOnPage('/cart')
-  I.click('Proceed to Checkout', step.retry(5))  // retry up to 5 times
-  I.see('Payment')
-})
-```
-
-Configure timing with exponential backoff:
-
-```js
-I.click('Submit', step.retry({
-  retries: 3,
-  minTimeout: 1000,  // wait 1 second before first retry
-  maxTimeout: 5000,  // max 5 seconds between retries
-  factor: 1.5        // exponential backoff multiplier
-}))
-```
-
-Pass `0` for infinite retries.
-
-### 2. Automatic Step Retry
+## Failed Step Retries
 
 Automatically retry all failed steps without modifying test code:
 
@@ -99,7 +79,34 @@ Full plugin options:
 | `deferToScenarioRetries` | `true` | Disable step retries when scenario retries exist |
 | `when` | `() => true` | Function receiving error; return `true` to retry |
 
-### 3. Multiple Steps Retry (retryTo)
+## Manual Step Retries
+
+Retry a specific step known to be flaky:
+
+```js
+import step from 'codeceptjs/steps'
+
+Scenario('checkout', ({ I }) => {
+  I.amOnPage('/cart')
+  I.click('Proceed to Checkout', step.retry(5))  // retry up to 5 times
+  I.see('Payment')
+})
+```
+
+Configure timing with exponential backoff:
+
+```js
+I.click('Submit', step.retry({
+  retries: 3,
+  minTimeout: 1000,  // wait 1 second before first retry
+  maxTimeout: 5000,  // max 5 seconds between retries
+  factor: 1.5        // exponential backoff multiplier
+}))
+```
+
+Pass `0` for infinite retries.
+
+## Multiple Steps Retry
 
 Retry a group of steps together as a single operation:
 
@@ -116,7 +123,7 @@ If any step inside fails, the entire block retries. Use this for sequences that
 
 **Learn more:** [Effects](/effects#retryto)
 
-### 4. Self-Healing Steps
+## Self-Healing Steps
 
 When a step fails, a healing recipe runs recovery actions and continues the test — without touching test code. With AI healing enabled:
 
@@ -143,7 +150,7 @@ You can also write custom recipes for non-UI failures — network errors, data g
 
 **Learn more:** [Self-Healing Tests](/heal), [AI Configuration](/ai)
 
-### 5. Scenario Retry
+## Scenario Retry
 
 Retry an entire test when it fails:
 
@@ -165,7 +172,7 @@ export const config = {
 }
 ```
 
-### 6. Feature Retry
+## Feature Retry
 
 Retry all scenarios within a feature:
 
@@ -186,7 +193,7 @@ export const config = {
 }
 ```
 
-### 7. Hook Retries
+## Hook Retries
 
 Retry `Before`/`After` hooks when they fail:
 

package/docs/typescript.md

@@ -5,370 +5,155 @@ title: TypeScript
 
 # TypeScript
 
-CodeceptJS supports [type declaration](https://github.com/codeceptjs/CodeceptJS/tree/master/typings) for [TypeScript](https://www.typescriptlang.org/). It means that you can write your tests in TS. Also, all of your custom steps can be written in TS
+CodeceptJS ships [type declarations](https://github.com/codeceptjs/CodeceptJS/tree/master/typings), so you can write tests, page objects, and custom helpers in TypeScript and get autocomplete and type checking in your editor.
 
-# Why TypeScript?
+## Getting started
 
-With the TypeScript writing CodeceptJS tests becomes much easier. If you configure TS properly in your project as well as your IDE, you will get the following features:
-- [Autocomplete (with IntelliSense)](https://code.visualstudio.com/docs/editor/intellisense) - a tool that streamlines your work by suggesting when you typing what function or property which exists in a class, what arguments can be passed to that method, what it returns, etc.
-Example:
-
-![Auto Complete](/img/Auto_comlete.gif)
-
-- To show additional information for a step in a test. Example:
-
-![Quick Info](/img/Quick_info.gif)
-
-- Checks types - thanks to TypeScript support in CodeceptJS now allow to tests your tests. TypeScript can prevent some errors:
-  - invalid type of variables passed to function;
-  - calls no-exist method from PageObject or `I` object;
-  - incorrectly used CodeceptJS features;
-
-
-## Getting Started <Badge text="Since 3.3.5" type="warning"/>
-
-CodeceptJS can initialize tests as a TypeScript project.
-When starting a new project with a standard installation via 
-
-```
-npx codeceptjs init
-``` 
-Then select TypeScript as the first question:
+`npx codeceptjs init` scaffolds a TypeScript project when you answer **Yes** to:
 
 ```
 ? Do you plan to write tests in TypeScript? Yes
 ```
 
-Then a config file and new tests will be created in TypeScript format.
-
-If a config file is set in TypeScript format (`codecept.conf.ts`) package `ts-node` will be used to run tests. 
-
-## TypeScript Tests in ESM (CodeceptJS 4.x) <Badge text="Since 4.0.0" type="tip"/>
-
-CodeceptJS 4.x uses ES Modules (ESM) which requires a different approach for TypeScript test files. While TypeScript **config files** (`codecept.conf.ts`) are automatically transpiled, TypeScript **test files** need a loader.
-
-### Using tsx (Recommended)
+It writes `codecept.conf.ts` and `*_test.ts` files. The **config file** and helpers are transpiled automatically. **Test files** need a loader — CodeceptJS 4.x is ESM, and Mocha loads test files through CommonJS hooks, so use [`tsx`](https://tsx.is) (fast, esbuild-based, no `tsconfig.json` required):
 
-[tsx](https://tsx.is) is a modern, fast TypeScript loader built on esbuild. It's the recommended way to run TypeScript tests in CodeceptJS 4.x.
-
-**Installation:**
-```bash
-npm install --save-dev tsx
+```sh
+npm i tsx --save-dev
 ```
 
-**Configuration:**
-```typescript
+```ts
 // codecept.conf.ts
 export const config = {
   tests: './**/*_test.ts',
-  require: ['tsx/cjs'],  // ← Enable TypeScript loader for test files
+  require: ['tsx/cjs'],   // loads the *_test.ts files
   helpers: {
-    Playwright: {
-      url: 'http://localhost',
-      browser: 'chromium'
-    }
-  }
-}
-```
-
-That's it! Now you can write tests in TypeScript with full language support:
-
-```typescript
-// login_test.ts
-Feature('Login')
-
-Scenario('successful login', ({ I }) => {
-  I.amOnPage('/login')
-  I.fillField('email', 'user@example.com')
-  I.fillField('password', 'password123')
-  I.click('Login')
-  I.see('Welcome')
-})
-```
-
-**Why tsx?**
-- ⚡ **Fast:** Built on esbuild, much faster than ts-node
-- 🎯 **Zero config:** Works without tsconfig.json  
-- 🚀 **Works with Mocha:** Uses CommonJS hooks that Mocha understands
-- ✅ **Complete:** Handles all TypeScript features (enums, decorators, etc.)
-
-### Using ts-node/esm (Not Recommended)
-
-> ⚠️ **Note:** `ts-node/esm` has significant limitations with module resolution and doesn't work well with modern ESM TypeScript projects. **We strongly recommend using `tsx` instead.** The information below is provided for reference only.
-
-`ts-node/esm` has several issues:
-- Doesn't support `"type": "module"` in package.json
-- Doesn't resolve extensionless imports or `.js` imports to `.ts` files
-- Requires explicit `.ts` extensions in imports, which isn't standard TypeScript practice
-- Less reliable than `tsx` for ESM scenarios
-
-**If you still want to use ts-node/esm:**
-
-```bash
-npm install --save-dev ts-node
-```
-
-```typescript
-// codecept.conf.ts
-export const config = {
-  tests: './**/*_test.ts',
-  require: ['ts-node/esm'],
-  helpers: { /* ... */ }
-}
-```
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "module": "ESNext",
-    "target": "ES2022",
-    "moduleResolution": "node",
-    "esModuleInterop": true
+    Playwright: { url: 'http://localhost', browser: 'chromium' },
   },
-  "ts-node": {
-    "esm": true
-  }
 }
 ```
 
-**Critical Limitations:**
-- ❌ Cannot use `"type": "module"` in package.json
-- ❌ Import statements must match the actual file (no automatic resolution)
-- ❌ Module resolution doesn't work like standard TypeScript/Node.js ESM
+Run the tests with `npx codeceptjs run`.
 
-**Recommendation:** Use `tsx/cjs` instead for a better experience.
+> Adding TypeScript to an existing project: set `"type": "module"` in `package.json`, rename the config to `codecept.conf.ts` with `export const config = {}`, install `tsx`, and add `require: ['tsx/cjs']`.
 
-### Full TypeScript Features in Tests
+## Writing tests
 
-With tsx or ts-node/esm, you can use complete TypeScript syntax including imports, enums, interfaces, and types:
+Test files use the full TypeScript syntax — imports, enums, interfaces, types:
 
-```typescript
-// types.ts
-export enum Environment {
-  TEST = 'test',
-  STAGING = 'staging',
-  PRODUCTION = 'production'
-}
-
-export interface User {
-  email: string
-  password: string
-}
+```ts
+// fixtures.ts
+export interface User { email: string; password: string }
+export const admin: User = { email: 'admin@example.com', password: 's3cret' }
 
 // login_test.ts
-import { Environment, User } from './types'
-
-const testUser: User = {
-  email: 'test@example.com',
-  password: 'password123'
-}
+import { admin } from './fixtures'
 
 Feature('Login')
 
-Scenario(`Login on ${Environment.TEST}`, ({ I }) => {
+Scenario('admin signs in', ({ I }) => {
   I.amOnPage('/login')
-  I.fillField('email', testUser.email)
-  I.fillField('password', testUser.password)
+  I.fillField('email', admin.email)
+  I.fillField('password', admin.password)
   I.click('Login')
   I.see('Welcome')
 })
 ```
 
-### Troubleshooting TypeScript Tests
+> **Cannot find module** or **Unexpected token** while running tests means the loader isn't wired up — check that `tsx` is installed and `require: ['tsx/cjs']` is in the config.
 
-**Error: "Cannot find module" or "Unexpected token"**
+## Promise-based typings
 
-This means the TypeScript loader isn't configured. Make sure:
-1. You have `tsx` or `ts-node` installed: `npm install --save-dev tsx`
-2. Your config includes the loader in `require` array: `require: ['tsx/cjs']`
-3. The loader is specified before test files are loaded
+CodeceptJS tests read synchronously even though every `I.*` call returns a promise:
 
-**Error: Module not found when importing from `.ts` files**
-
-When using `ts-node/esm` with ESM, you need to use `.js` extensions in imports:
-
-```typescript
-// This will cause an error in ESM mode:
-import loginPage from "./pages/Login"
-
-// Use .js extension instead:
-import loginPage from "./pages/Login.js"
+```ts
+I.amOnPage('/')
+I.click('Login')
+I.see('Hello')
 ```
 
-TypeScript will resolve the `.js` import to your `.ts` file during compilation. This is the standard behavior for ESM + TypeScript.
-
-Alternatively, use `tsx/cjs` which doesn't require explicit extensions.
-
-**TypeScript config files vs test files**
-
-Note the difference:
-- **Config files** (`codecept.conf.ts`, helpers): Automatically transpiled by CodeceptJS
-- **Test files** (`*_test.ts`): Need a loader specified in `config.require`
-
-### Migration from CodeceptJS 3.x
-
-If you're upgrading from CodeceptJS 3.x (CommonJS) to 4.x (ESM):
-
-**Old setup (3.x):**
-```javascript
-// codecept.conf.js
-module.exports = {
-  tests: './*_test.ts',
-  require: ['ts-node/register'],  // CommonJS loader
-  helpers: {}
-}
-```
+The default typings declare these methods as returning `void`, so a linter won't demand `await` on every line. To follow TypeScript conventions and `await` each command instead — some teams find explicit flow control improves stability — enable promise-based typings in `codecept.conf.ts`:
 
-**New setup (4.x):**
-```typescript
-// codecept.conf.ts
+```ts
 export const config = {
-  tests: './*_test.ts',
-  require: ['tsx/cjs'],  // TypeScript loader
-  helpers: {}
+  fullPromiseBased: true,
+  // ...
 }
 ```
 
-**Migration steps:**
-1. Install tsx: `npm install --save-dev tsx`
-2. Update package.json: `"type": "module"`
-3. Rename config to `codecept.conf.ts` and use `export const config = {}`
-4. Change `require: ['ts-node/register']` to `require: ['tsx/cjs']`
-5. Run tests: `npx codeceptjs run`
-
-## Promise-Based Typings
-
-By default, CodeceptJS tests are written in synchronous mode. This is a regular CodeceptJS test:
+Rebuild the type definitions:
 
-```js
-I.amOnPage('/')
-I.click('Login')
-I.see('Hello!')
+```sh
+npx codeceptjs def
 ```
 
-Even thought we don't see any `await`, those commands are executed synchronously, one by one.
-All methods of `I` object actually return promise and TypeScript linter requires to use `await` operator for those promises.
-To trick TypeScript and allow writing tests in CodeceptJS manner we create typings where `void` is returned instead of promises. This way linter won't complain on async code without await, as no promise is returned. 
+Now the typings return promises:
 
-Our philosophy here is: use `await` only when it is actually needed, don't add visual mess to your code prefixing each line with `await`. However, you might want to get a better control of your tests and follow TypeScript conventions.
-This is why you might want to **enable promise-based typings**.
-
-A previous test should be rewritten with `await`s:
-
-```js
+```ts
 await I.amOnPage('/')
 await I.click('Login')
-await I.see('Hello!')
+await I.see('Hello')
 ```
 
-Using `await` explicitly provides a beter control of execution flow. Some CodeceptJS users report that they increased stability of tests by adopting `await` for all CodeceptJS commands in their codebase.
+## Types for page objects and custom helpers
 
-If you select to use promise-based typings, type definitions will be generated so all actions to return a promise. 
-Otherwise they will still return promises but it won't be relfected in type definitions.
+`npx codeceptjs def` regenerates `steps.d.ts` from your config — run it after adding a page object or a custom helper so autocomplete picks them up.
 
-To introduce promise-based typings into a current project edit `codecept.conf.ts`:
+For a custom helper:
 
 ```ts
-fullPromiseBased: true;
-```
-
-and rebuild type definitions with
-
-```
-npx codeceptjs def
-```
-
-## Types for custom helper or page object
-
-If you want to get types for your [custom helper](https://codecept.io/helpers/#configuration), you can add their automatically with CodeceptJS command `npx codeceptjs def`.
-
-For example, if you add the new step `printMessage` for your custom helper like this:
-```js
-// customHelper.ts
+// CustomHelper.ts
 export class CustomHelper extends Helper {
   printMessage(msg: string) {
     console.log(msg)
   }
 }
-
 ```
 
-Then you need to add this helper to your `codecept.conf.js` like in this [docs](https://codecept.io/helpers/#configuration).
-And then run the command `npx codeceptjs def`.
+Register it in `codecept.conf.ts` ([helper configuration](/helpers#configuration)), run `npx codeceptjs def`, and `steps.d.ts` becomes:
 
-As result our `steps.d.ts` file will be updated like this:
 ```ts
 /// <reference types='codeceptjs' />
-type CustomHelper = import('./CustomHelper');
+type CustomHelper = import('./CustomHelper')
 
 declare namespace CodeceptJS {
   interface SupportObject { I: I }
-  interface Methods extends Puppeteer, CustomHelper {}
+  interface Methods extends Playwright, CustomHelper {}
   interface I extends WithTranslation<Methods> {}
-  namespace Translation {
-    interface Actions {}
-  }
 }
 ```
 
-And now you can use autocomplete on your test.
+Page objects appear the same way — `def` adds a `type` for each and lists them in `SupportObject`:
 
-Generation types for PageObject looks like for a custom helper, but `steps.d.ts` will look like:
 ```ts
-/// <reference types='codeceptjs' />
-type loginPage = typeof import('./loginPage');
-type homePage = typeof import('./homePage');
-type CustomHelper = import('./CustomHelper');
+type loginPage = typeof import('./loginPage')
+type homePage = typeof import('./homePage')
 
 declare namespace CodeceptJS {
   interface SupportObject { I: I, loginPage: loginPage, homePage: homePage }
-  interface Methods extends Puppeteer, CustomHelper {}
-  interface I extends WithTranslation<Methods> {}
-  namespace Translation {
-    interface Actions {}
-  }
+  // ...
 }
 ```
 
-## Types for custom strict locators
-
-You can define [custom strict locators](https://codecept.io/locators/#custom-strict-locators) that can be used in all methods taking a locator (parameter type `LocatorOrString`).
-
-Example: A custom strict locator with a `data` property, which can be used like this:
-
-```ts
-I.click({ data: 'user-login' });
-```
+## Types for custom locators
 
-In order to use the custom locator in TypeScript code, its type shape needs to be registered in the interface `CustomLocators` in your `steps.d.ts` file:
+If you use [custom locators](/locators#custom-locators) — for example `I.click({ data: 'user-login' })` — declare their shape in the `CustomLocators` interface in `steps.d.ts` so they're accepted wherever a locator is expected:
 
 ```ts
 /// <reference types='codeceptjs' />
-...
 
 declare namespace CodeceptJS {
-  ...
-
   interface CustomLocators {
-    data: { data: string };
+    data: { data: string }
   }
 }
 ```
 
-The property keys used in the `CustomLocators` interface do not matter (only the *types* of the interface properties are used). For simplicity it is recommended to use the name that is also used in your custom locator itself.
-
-You can also define more complicated custom locators with multiple (also optional) properties:
+Only the property *types* matter, not the keys. Locators with several (optional) properties work too:
 
 ```ts
-/// <reference types='codeceptjs' />
-...
-
 declare namespace CodeceptJS {
-  ...
-
   interface CustomLocators {
-    data: { data: string, value?: number, flag?: boolean };
+    data: { data: string; value?: number; flag?: boolean }
   }
 }
 ```

package/lib/codecept.js

@@ -316,7 +316,7 @@ class Codecept {
 
       try {
         event.emit(event.all.before, this)
-        mocha.run(async (failures) => await done(failures))
+        mocha.runner = mocha.run(async (failures) => await done(failures))
       } catch (e) {
         output.error(e.stack)
         reject(e)

package/lib/command/run-workers.js

@@ -87,19 +87,5 @@ export default async function (workerCount, selectedRuns, options) {
     process.exitCode = 1
   } finally {
     await workers.teardownAll()
-    
-    // Force exit if event loop doesn't clear naturally
-    // This is needed because worker threads may leave handles open
-    // even after proper cleanup, preventing natural process termination
-    if (!options.noExit) {
-      // Use beforeExit to ensure we run after all other exit handlers
-      // have set the correct exit code
-      process.once('beforeExit', (code) => {
-        // Give cleanup a moment to complete, then force exit with the correct code
-        setTimeout(() => {
-          process.exit(code || process.exitCode || 0)
-        }, 100)
-      })
-    }
   }
 }

package/lib/command/run.js

@@ -1,8 +1,7 @@
-import { getConfig, printError, getTestRoot, createOutputDir } from './utils.js'
+import { getConfig, printError, getTestRoot, createOutputDir, autoExit } from './utils.js'
 import Config from '../config.js'
 import store from '../store.js'
 import Codecept from '../codecept.js'
-import container from '../container.js'
 
 export default async function (test, options) {
   // registering options globally to use in config
@@ -43,19 +42,6 @@ export default async function (test, options) {
     process.exitCode = 1
   } finally {
     await codecept.teardown()
-
-    // Schedule a delayed exit to prevent process hanging due to browser helper event loops
-    // Only needed for Playwright/Puppeteer which keep the event loop alive
-    // Wait 1 second to allow final cleanup and output to complete
-    if (!process.env.CODECEPT_DISABLE_AUTO_EXIT) {
-      const helpers = container.helpers()
-      const hasBrowserHelper = helpers && (helpers.Playwright || helpers.Puppeteer || helpers.WebDriver)
-      
-      if (hasBrowserHelper) {
-        setTimeout(() => {
-          process.exit(process.exitCode || 0)
-        }, 1000).unref()
-      }
-    }
+    await autoExit()
   }
 }

package/lib/command/utils.js

@@ -107,6 +107,20 @@ export const createOutputDir = (config, testRoot) => {
   }
 }
 
+export async function autoExit() {
+  const timeout = parseInt(process.env.CODECEPT_AUTO_EXIT_TIMEOUT, 10)
+  if (timeout === 0) return
+  const exitTimeout = timeout || 2000
+
+  const { default: container } = await import('../container.js')
+  const helpers = container.helpers()
+  if (!helpers || !Object.values(helpers).some(h => typeof h._cleanup === 'function')) return
+
+  const { default: recorder } = await import('../recorder.js')
+  await Promise.race([recorder.promise(), new Promise(resolve => setTimeout(resolve, exitTimeout))])
+  process.exit(process.exitCode || 0)
+}
+
 export const findConfigFile = testsPath => {
   const extensions = ['js', 'ts']
   for (const ext of extensions) {

package/lib/command/workers/runTests.js

@@ -54,11 +54,7 @@ process.on('unhandledRejection', (reason, promise) => {
     process.stderr.write(`${reason.stack}\n`)
   }
 
-  // Don't exit on test-related rejections
-  if (msg.includes('expected') || msg.includes('AssertionError')) {
-    return
-  }
-  process.exit(1)
+  // Do not exit — killing the worker silently drops every remaining test from the report.
 })
 
 // hide worker output

package/lib/heal.js

@@ -54,7 +54,9 @@ class Heal {
 
   async getCodeSuggestions(context) {
     const suggestions = []
+    const stepName = context.step?.name
     const recipes = matchRecipes(this.recipes, this.contextName)
+      .filter(r => !r.steps || !stepName || r.steps.includes(stepName))
 
     debug('Recipes', recipes)