Merge branch '4.x' into use-native-fetch

Author: kobenguyent

.github/workflows/appium_Android.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - 4.x
-      - appium-esm-migration
   pull_request:
     branches:
       - 4.x
@@ -22,6 +21,8 @@ env:
 
 jobs:
   appium:
+    # Run ONLY on the main repo AND (if it's a push OR a PR from the same repo)
+    if: github.repository == 'codeceptjs/CodeceptJS' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository)
     runs-on: ubuntu-22.04
     timeout-minutes: 30
 

.github/workflows/docker.yml

@@ -29,6 +29,9 @@ jobs:
           echo "VERSION=$VERSION" >> $GITHUB_ENV
           echo "version=$VERSION" >> $GITHUB_OUTPUT
 
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -51,6 +54,7 @@ jobs:
         with:
           context: .
           push: true
+          platforms: linux/amd64,linux/arm64
           tags: |
             ${{ env.DOCKER_REPO }}:latest
             ${{ env.DOCKER_REPO }}:${{ env.VERSION }}

.github/workflows/test.yml

@@ -20,7 +20,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x]
+        node-version: [26.x]
 
     steps:
       - uses: actions/checkout@v6
@@ -53,6 +53,27 @@ jobs:
       - name: Stop mock server
         run: npm run mock-server:stop
 
+  unit-tests-windows:
+    name: Unit tests
+    runs-on: windows-latest
+    timeout-minutes: 15
+
+    strategy:
+      matrix:
+        node-version: [ 20.x ]
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm i
+        env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: true
+          PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: true
+      - run: npm run test:unit:windows
+
   runner-tests:
     name: Runner tests
     runs-on: ubuntu-22.04

.prettierignore

@@ -0,0 +1,2 @@
+# Vendored third-party bundles used by rich-text editor test fixtures
+test/data/app/js/

Dockerfile

@@ -1,5 +1,5 @@
 # Download Playwright and its dependencies
-FROM mcr.microsoft.com/playwright:v1.55.0-noble
+FROM mcr.microsoft.com/playwright:v1.61.0-noble
 
 # Set non-interactive mode for apt operations
 ENV DEBIAN_FRONTEND=noninteractive

bin/codecept.js

@@ -5,6 +5,7 @@ import Codecept from '../lib/codecept.js'
 import output from '../lib/output.js'
 const { print, error } = output
 import { printError } from '../lib/command/utils.js'
+import { resolveImportModulePath } from '../lib/utils.js'
 
 const commandFlags = {
   ai: {
@@ -45,7 +46,8 @@ const errorHandler =
   }
 
 const dynamicImport = async modulePath => {
-  const module = await import(modulePath)
+  const resolvedPath = resolveImportModulePath(modulePath)
+  const module = await import(resolvedPath)
   return module.default || module
 }
 

docs/agents.md

@@ -23,6 +23,38 @@ Agents get full control over test and browser execution:
 
 CodeceptJS is token-efficient: it stores HTML, ARIA, logs, and HTTP request data as files instead of streaming them through MCP. Agents read these files with their native shell tools—no extra API calls, no redundant context.
 
+## Essential Setup
+
+Two things make agent testing work: the **skills** that teach the agent CodeceptJS, and the **MCP server** that lets it drive the browser. Set both up once, from your project directory.
+
+Install the skills:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+Connect the MCP server (`npx codeceptjs-mcp`).
+
+**Claude Code:**
+
+```bash
+claude mcp add codeceptjs -- npx codeceptjs-mcp
+```
+
+**Codex:**
+
+```bash
+codex mcp add codeceptjs -- npx codeceptjs-mcp
+```
+
+**Cursor** — add to `.cursor/mcp.json`:
+
+```json
+{ "mcpServers": { "codeceptjs": { "command": "npx", "args": ["codeceptjs-mcp"] } } }
+```
+
+See [/mcp](/mcp) for full client setup. Now the agent is ready to run the loop.
+
 ## The loop
 
 Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
@@ -96,31 +128,6 @@ Only `url` is inline. The rest are paths the agent opens with the right tool:
 
 Saved HTML is formatted, with non-semantic elements stripped out: `<style>`, `<script>`, Tailwind-style trash classes, and inline `style=""` attributes. `grep` can then effectively find the correct tree branch in raw page source. ARIA snapshots are smaller and more structured than HTML, which is why the agent prefers them when picking locators.
 
-## Setup
-
-When CodeceptJS is installed, the MCP server can be launched with this command:
-
-```bash
-npx codeceptjs-mcp
-```
-
-> See [/mcp](/mcp) for detailed client setup.
-
-We recommend pairing CodeceptJS MCP with the skills bundle.
-
-Install for any agent:
-
-```bash
-npx skills add codeceptjs/skills
-```
-
-Or, in Claude Code:
-
-```text
-/plugin marketplace add codeceptjs/skills
-/plugin install codeceptjs@codeceptjs-skills
-```
-
 ## Usage Examples
 
 When MCP and skills are connected, the agent receives predefined workflows and can act effectively for testing purposes. Common scenarios it handles:

docs/configuration.md

@@ -44,6 +44,8 @@ export const config = {
 
 - `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).
+- `workerInitializationDelay` — delay in milliseconds between spinning up parallel workers to prevent CPU spikes and stagger browser startup. Defaults to `200`. Set to `0` to disable.
+- `workerInitializationMaxDelay` — maximum total delay (in milliseconds) for worker initialization staggering. Defaults to `10000` (10 s). Set to `0` to disable capping.
 
 **BDD**
 
@@ -71,16 +73,18 @@ For TypeScript test files in CodeceptJS 4.x, use the [`tsx`](https://tsx.is) loa
 // codecept.conf.ts
 export const config = {
   tests: './**/*_test.ts',
-  require: ['tsx/cjs'],
+  require: ['tsx/esm'],
   helpers: {},
   include: {},
 }
 ```
 
+This requires `"type": "module"` in `package.json` so `.ts` test files are compiled as ES Modules.
+
 Combine several modules:
 
 ```ts
-require: ['tsx/cjs', 'should', './lib/testSetup']
+require: ['tsx/esm', 'should', './lib/testSetup']
 ```
 
 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.

docs/installation.md

@@ -111,7 +111,7 @@ npm i tsx --save-dev
 // codecept.conf.ts
 export const config = {
   tests: './**/*_test.ts',
-  require: ['tsx/cjs'],   // loads the *_test.ts files
+  require: ['tsx/esm'],   // loads the *_test.ts files as ES Modules (needs "type": "module")
   helpers: {
     Playwright: { url: 'http://localhost', browser: 'chromium' },
   },

docs/migration-4.md

@@ -7,9 +7,31 @@ title: Migrating from 3.x to 4.x
 
 CodeceptJS 4.x is a major release. It moves the codebase from CommonJS to native ESM, drops several long-deprecated helpers and plugins, replaces legacy plugins with first-class APIs, and bumps most third-party dependencies.
 
-> Migrate automatically! Install CodeceptJS skills `npx skills add codeceptjs/skills` and run `/codeceptjs-3-to-4-migration` in your coding agent
+## Migrate Automatically with an Agent
 
-This guide tells you exactly what to change in your project to upgrade.
+The fastest way to upgrade is to let an AI agent do it. This release is mechanical enough that an agent handles most of it end-to-end.
+
+Install CodeceptJS 4:
+
+```bash
+npm install codeceptjs@4
+```
+
+Then install the skills bundle. It works the same in Claude Code or any other agent:
+
+```bash
+npx skills add codeceptjs/skills
+```
+
+The bundle ships a `migrate-codeceptjs-4` skill. Point an agent at the project and run it:
+
+```bash
+claude "/migrate-codeceptjs-4"
+```
+
+It reads your config and tests, applies the mechanical changes, runs the suite, and fixes what breaks.
+
+The rest of this guide documents every change the skill makes — read it if you prefer to migrate by hand, or to review what the agent did.
 
 ## 1. Update Node and Package