Merge remote-tracking branch 'origin/4.x' into feat/last-failed

# Conflicts:
#	docs/commands.md
#	lib/codecept.js
#	lib/command/workers/runTests.js

Author: DenysKuchma

.github/workflows/lightpanda.yml

@@ -0,0 +1,64 @@
+name: Lightpanda Helper Tests
+
+on:
+  push:
+    branches:
+      - 4.x
+  pull_request:
+    branches:
+      - '**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  CI: true
+  FORCE_COLOR: 1
+  LIGHTPANDA_DISABLE_TELEMETRY: true
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 15
+
+    strategy:
+      matrix:
+        node-version: [22.x]
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.0
+      - name: npm install
+        run: npm i --force
+      - name: Download Lightpanda
+        run: |
+          mkdir -p ~/lightpanda-bin
+          # pinned: releases/latest resolves to a nightly build; the suite is tested against stable releases
+          curl -sfL --retry 3 -o ~/lightpanda-bin/lightpanda https://github.com/lightpanda-io/browser/releases/download/1.0.0/lightpanda-x86_64-linux
+          chmod +x ~/lightpanda-bin/lightpanda
+          ~/lightpanda-bin/lightpanda version
+      - name: start test server
+        run: |
+          php -S 127.0.0.1:8000 -t test/data/app &
+          sleep 1
+          curl -sf http://127.0.0.1:8000/info > /dev/null
+      - name: run lightpanda helper tests
+        run: |
+          export LIGHTPANDA_PATH="$HOME/lightpanda-bin/lightpanda"
+          npm run test:unit:webbapi:lightpanda
+      - name: run lightpanda acceptance tests
+        run: |
+          export LIGHTPANDA_PATH="$HOME/lightpanda-bin/lightpanda"
+          ./bin/codecept.js run -c test/acceptance/codecept.Lightpanda.js --grep @Lightpanda --debug

Bunoshfile.js

@@ -399,6 +399,7 @@ const inheritedHelperDocs = {
     exclude: [/Title/, /Popup/, /Cookie/, /Url/, /^press/, /^refreshPage/, /^resizeWindow/, /Script$/, /cursor/, /Css/, /Tab$/, /^wait/],
   },
   Obscura: { parent: 'CDPBrowser' },
+  Lightpanda: { parent: 'CDPBrowser' },
   Kitesurf: { parent: 'CDPBrowser', excludeConfig: ['endpoint', 'headers'] },
 }
 
@@ -425,11 +426,12 @@ async function docsHelperMarkdown(name, { parent, exclude = [], excludeConfig =
   const documentation = await import('documentation')
   const buildOptions = { shallow: true, sortOrder: ['alpha'] }
   const doc = await documentation.build([`docs/build/${name}.js`], buildOptions)
+  doc.sort((a, b) => (b.kind === 'class') - (a.kind === 'class'))
   let members = doc[0].members.instance
 
   if (parent) {
     const parentDoc = await documentation.build([`docs/build/${parent}.js`], buildOptions)
-    for (const method of parentDoc[0].members.instance) {
+    for (const method of parentDoc.find(c => c.kind === 'class').members.instance) {
       if (exclude.some(f => method.name.match(f))) continue
       if (members.some(m => m.name === method.name)) continue
       members.push(method)

README.md

@@ -11,6 +11,7 @@
 | 🌐 Web    | Puppeteer  | [![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)                  |
 | 🌐 Web    | WebDriver  | [![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)                  |
 | 🌐 Web    | Obscura    | [![Obscura Helper Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/obscura.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/obscura.yml)               |
+| 🌐 Web    | Lightpanda | [![Lightpanda Helper Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/lightpanda.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/lightpanda.yml)      |
 | 📱 Mobile | Appium     | [![Appium Tests - Android](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml) |
 
 # CodeceptJS [![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)
@@ -44,6 +45,7 @@ CodeceptJS uses **Helper** modules to provide actions to `I` object. Currently,
 - [**Puppeteer**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Puppeteer.md) - uses Google Chrome's Puppeteer for fast headless testing.
 - [**WebDriver**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) - uses [webdriverio](http://webdriver.io/) to run tests via WebDriver or Devtools protocol.
 - [**Obscura**](https://codecept.io/helpers/Obscura) - drives the lightweight Obscura browser through Chrome DevTools Protocol. See [Alternative Browser Engines](https://codecept.io/alternative-browsers).
+- [**Lightpanda**](https://codecept.io/helpers/Lightpanda) - drives the Lightpanda headless browser through Chrome DevTools Protocol. See [Alternative Browser Engines](https://codecept.io/alternative-browsers).
 - [**Appium**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Appium.md) - for **mobile testing** with Appium
 - [**Detox**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Detox.md) - This is a wrapper on top of Detox library, aimed to unify testing experience for CodeceptJS framework. Detox provides a grey box testing for mobile applications, playing especially well for React Native apps.
 

bin/codecept.js

@@ -78,8 +78,16 @@ program
   .command('init [path]')
   .description('Creates dummy config in current dir or [path]')
   .option('-y, --yes', 'skip prompts and use defaults (Playwright + chromium, BASE_URL env for url)')
+  .option('--agent <name>', 'set up an AI coding agent: claude, codex, cursor, opencode')
   .action(commandHandler('../lib/command/init.js'))
 
+program
+  .command('init:agent [agent]')
+  .alias('init-agent')
+  .description('Set up CodeceptJS MCP server and skills for a coding agent: claude, codex, cursor, opencode')
+  .option('-y, --yes', 'skip prompts, requires [agent]')
+  .action(commandHandler('../lib/command/initAgent.js'))
+
 program
   .command('check')
   .option(commandFlags.config.flag, commandFlags.config.description)
@@ -211,6 +219,7 @@ program
   .option('--last-failed', 'run only tests that failed in the previous run')
   .option('-o, --override [value]', 'override current config options')
   .option('--suites', 'parallel execution of suites not single tests')
+  .option('--serial <pattern>', 'run tests matching <pattern> one by one after parallel workers finish')
   .option('--by <strategy>', 'test distribution strategy: "test" (pre-assign individual tests), "suite" (pre-assign test suites), or "pool" (dynamic distribution for optimal load balancing, recommended)')
   .option(commandFlags.debug.flag, commandFlags.debug.description)
   .option(commandFlags.verbose.flag, commandFlags.verbose.description)

docs/agents.md

@@ -25,7 +25,15 @@ CodeceptJS is token-efficient: it stores HTML, ARIA, logs, and HTTP request data
 
 ## 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.
+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:
+
+```bash
+npx codeceptjs init:agent claude
+```
+
+Use `codex`, `cursor`, or `opencode` instead of `claude` for other agents, or omit the name to pick from a list. `npx codeceptjs init` offers the same step at the end.
+
+### Manual setup
 
 Install the skills:
 
@@ -165,6 +173,21 @@ After a failed run, the agent reads every trace under `output/`, clusters failur
 
 If the fix held, the PR goes green. If it didn't, every edit is rolled back with `git checkout` and the report says which patterns the agent couldn't safely handle. No half-applied fixes left behind, no `retries: 3` masking the problem.
 
+## Assertions in plain language
+
+Some outcomes are hard to pin to a locator: "checkout form has all required fields", "success message is shown". Instead of building a fragile chain of `see*` checks, the agent can write the expected outcome as a statement with the [Decision helper](/assertions#decision-assertions):
+
+```js
+I.decide([
+  'order summary lists the purchased items',
+  'success message is shown',
+])
+```
+
+The agent runs the statement on the live page like any other command and keeps it only if it passes. The test then checks it on every run.
+
+Decision models like [Jev](https://openrouter.ai/typesafe/jev-1.13) are built for this. They answer in a fraction of a second, cost a fraction of a cent per request, and return a probability instead of free text. That makes them fast and cheap enough to run on every CI build, and predictable enough to keep in a test.
+
 ## Skills bundle
 
 Skills teach the agent best practices for using CodeceptJS. Plug them in when you develop tests with agents, and update them regularly to ensure you use CodeceptJS in the most effective way.

docs/ai.md

@@ -23,6 +23,7 @@ CodeceptJS AI can do the following:
 
 - 🏋️‍♀️ **assist writing tests** in `pause()` or interactive shell mode
 - 🚑 **self-heal failing tests** (can be used on CI)
+- ⚖️ **assert statements in plain language** with [decision models](#decision-assertions)
 
 ![](/img/fill_form.gif)
 
@@ -338,6 +339,22 @@ Run tests with both AI and analyze enabled:
 npx codeceptjs run --ai
 ```
 
+## Decision Assertions
+
+Some checks are hard to express with locators: "checkout form has all required fields", "success message is shown". The [Decision helper](/helpers/Decision) asserts them in plain language:
+
+```js
+I.decide([
+  'checkout form has all required fields',
+  'submit button enabled',
+])
+I.decideVisually('sidebar is shown')
+```
+
+It uses a [decision model](https://openrouter.ai/models?output_modalities=decisions) like [Jev](https://openrouter.ai/typesafe/jev-1.13) instead of a chat model. A decision model reads the page and returns the probability that a statement is true. It is fast, costs a fraction of a cent per request, and gives a probability instead of free text, so a step passes or fails on a confidence threshold you set.
+
+Configure it in `ai.decisionModel`. Decisions call the decisions API directly, so they don't need `ai.model` or the `--ai` flag. See [Decision Assertions](/assertions#decision-assertions) for setup and usage.
+
 ## Advanced Configuration
 
 AI prompts and HTML compression can be configured inside `ai` section of `codecept.conf` file: