feat(helpers): add Lightpanda helper, share server lifecycle in CDPBrowser

Lightpanda is a thin CDPBrowser subclass that self-launches
`lightpanda serve` with telemetry disabled. The spawn/free-port/wait/kill
lifecycle moves from Obscura into CDPBrowser so both helpers share it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: DavertMik

.github/workflows/lightpanda.yml

@@ -0,0 +1,73 @@
+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_VERSION: 1.0.0
+  LIGHTPANDA_SHA256: aa5a4b8ed53d1e38b3c73f5b2647d0a84a82e6744557f45f9a9c85858aa031c3
+  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: Cache Lightpanda binary
+        uses: actions/cache@v4
+        with:
+          path: ~/lightpanda-bin/lightpanda
+          key: lightpanda-${{ env.LIGHTPANDA_VERSION }}-x86_64-linux
+      - name: Download Lightpanda
+        run: |
+          mkdir -p ~/lightpanda-bin
+          if [ ! -f ~/lightpanda-bin/lightpanda ]; then
+            curl -sfL --retry 3 -o ~/lightpanda-bin/lightpanda https://github.com/lightpanda-io/browser/releases/download/${LIGHTPANDA_VERSION}/lightpanda-x86_64-linux
+          fi
+          echo "${LIGHTPANDA_SHA256}  $HOME/lightpanda-bin/lightpanda" | sha256sum -c -
+          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.
 

docs/alternative-browsers.md

@@ -6,7 +6,7 @@ title: Alternative Browser Engines
 # Alternative Browser Engines
 
 ::: warning Experimental
-The `Obscura` and `Kitesurf` helpers are experimental in CodeceptJS 4.2. Pin browser versions in CI and retain Playwright or WebDriver coverage for compatibility-critical tests.
+The `Obscura`, `Lightpanda` and `Kitesurf` helpers are experimental in CodeceptJS 4.2. Pin browser versions in CI and retain Playwright or WebDriver coverage for compatibility-critical tests.
 :::
 
 Playwright and Puppeteer drive full Chromium — the most accurate way to test what users see.
@@ -17,11 +17,15 @@ through dedicated helpers:
   V8 engine. From v0.2.0, the default release build also renders — real layout, computed styles,
   and screenshots — with `-no-render` builds still available for pure-speed, nothing-painted
   scraping mode. Release archives are available for Linux, macOS, and Windows.
+- **[Lightpanda](https://lightpanda.io)** — an open-source browser written from scratch in Zig for
+  automation, with a real V8 engine and broad Web API coverage. It never paints: no screenshots,
+  but it does compute enough style and layout for visibility checks. Binaries are available for
+  Linux and macOS.
 - **[Kitesurf](https://blog.cloudflare.com/kitesurf/)** — Cloudflare's browser that runs in V8
   isolates on Cloudflare Workers, with a real layout and rendering pipeline. Cloud-only,
   free in beta, planned to be open-sourced.
 
-Both speak Chrome DevTools Protocol. CodeceptJS drives them with raw CDP — one round-trip per
+All of them speak Chrome DevTools Protocol. CodeceptJS drives them with raw CDP — one round-trip per
 action, no stale element handles — which is why suites on these browsers run fast and never hang
 on navigation races.
 
@@ -56,6 +60,10 @@ redirect happens, cookie is set — do not need a GPU raster pipeline. Obscura e
 app's real JavaScript in real V8; it only skips painting. For API-adjacent flows
 (login → dashboard data appears), that is exactly the right amount of browser.
 
+Lightpanda takes the same trade further: it has no rendering pipeline at all, which is what makes
+it start in milliseconds and use a fraction of Chromium's memory. Pick it when the suite never
+needs a screenshot; pick Obscura when it does.
+
 **Constrained environments.** ARM CI runners, thin containers, air-gapped machines:
 a static binary with no system dependencies goes where Chromium will not.
 
@@ -64,7 +72,9 @@ as an Obscura capability rather than a browser-compatibility guarantee from Code
 
 ## When to stay with Playwright
 
-- Anything visual: visual regression, PDF (neither helper exposes PDF output). Obscura's v0.2.0+
+- Anything visual: visual regression, PDF (none of these helpers exposes PDF output). Lightpanda
+  has no screenshots at all, no scrolling, and only computes the CSS properties visibility checks
+  need. Obscura's v0.2.0+
   rendering/CSS engine is new and independently implemented — expect edge cases and gaps versus a
   real browser, especially around inherited properties and less common computed-style values.
 - Visibility semantics on `-no-render` Obscura builds (and v0.1.x): every element reports as
@@ -88,6 +98,12 @@ CodeceptJS 4.2 is tested in CI with Obscura 0.2.2. Obscura 0.2.x is recommended;
       },
     }
 
+    helpers: {
+      Lightpanda: {
+        url: 'http://localhost:3000',
+      },
+    }
+
     helpers: {
       Kitesurf: {
         url: 'https://staging.myapp.com',
@@ -131,18 +147,29 @@ process — there is nothing to start by hand in the common case:
   that "start Obscura by hand and just run the tests" keeps working without any config, while
   self-launch is still the default for everyone else.
 
+### Lightpanda's connection modes
+
+Lightpanda works the same way, with `lightpanda` in place of `obscura`: the binary is resolved
+from `binaryPath`, then `LIGHTPANDA_PATH`, then `lightpanda` on `PATH`, and `lightpanda serve` is
+started on a free port and stopped when the run ends. Setting `endpoint` attaches to an instance
+you manage yourself, for example the `lightpanda/browser` Docker image. CodeceptJS is tested in CI
+with Lightpanda 1.0.0; see [Installation](/installation#lightpanda-experimental).
+
+The helper always starts Lightpanda with `LIGHTPANDA_DISABLE_TELEMETRY=true`. When you start the
+server yourself, set that variable yourself.
+
 ## Capability matrix
 
-| | Playwright | Obscura | Kitesurf |
-|---|---|---|---|
-| Real JS execution (V8) | yes | yes | yes |
-| Layout / getBoundingClientRect | yes | yes (v0.2.0+ default builds); synthetic on `-no-render`/v0.1.x | yes |
-| Screenshots | yes | yes (v0.2.0+ default builds); no on `-no-render`/v0.1.x | yes |
-| Visibility assertions | yes | yes (v0.2.0+ default builds); no, DOM-presence only, on `-no-render`/v0.1.x | yes |
-| Screencast / video (`screencast` plugin) | yes — WebM via `page.screencast`, with caption burn-in | yes — APNG via CDP `Page.startScreencast`, assembled in-process (v0.2.0+ default builds; verified PNG frames on the live server); no caption burn-in | untested |
-| Startup model | local browser process | standalone local binary | remote cloud session |
-| Parallel scale | machine-bound | machine-bound (light) | near-unlimited (cloud) |
-| Where it runs | local/grid | local | Cloudflare only |
-| License / cost | open source | Apache-2.0 | proprietary, free beta |
-
-See helper reference pages: [Obscura](/helpers/Obscura), [Kitesurf](/helpers/Kitesurf).
+| | Playwright | Obscura | Lightpanda | Kitesurf |
+|---|---|---|---|---|
+| Real JS execution (V8) | yes | yes | yes | yes |
+| Layout / getBoundingClientRect | yes | yes (v0.2.0+ default builds); synthetic on `-no-render`/v0.1.x | computed boxes, nothing painted | yes |
+| Screenshots | yes | yes (v0.2.0+ default builds); no on `-no-render`/v0.1.x | no | yes |
+| Visibility assertions | yes | yes (v0.2.0+ default builds); no, DOM-presence only, on `-no-render`/v0.1.x | yes | yes |
+| Screencast / video (`screencast` plugin) | yes — WebM via `page.screencast`, with caption burn-in | yes — APNG via CDP `Page.startScreencast`, assembled in-process (v0.2.0+ default builds; verified PNG frames on the live server); no caption burn-in | no | untested |
+| Startup model | local browser process | standalone local binary | standalone local binary | remote cloud session |
+| Parallel scale | machine-bound | machine-bound (light) | machine-bound (light) | near-unlimited (cloud) |
+| Where it runs | local/grid | local | local (Linux, macOS) | Cloudflare only |
+| License / cost | open source | Apache-2.0 | AGPL-3.0 | proprietary, free beta |
+
+See helper reference pages: [Obscura](/helpers/Obscura), [Lightpanda](/helpers/Lightpanda), [Kitesurf](/helpers/Kitesurf).

docs/helpers/Kitesurf.md

@@ -5,6 +5,7 @@ sidebar: auto
 title: Kitesurf
 ---
 
+
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
 ## Kitesurf
@@ -1742,7 +1743,9 @@ Returns **[Promise][4]<void>**&#x20;
 
 ### _connect
 
-Resolves the CDP endpoint and opens the underlying `CDPConnection`, storing it on `this.cdp`.
+In SELF-MANAGED mode, resolves and spawns the browser server (or courtesy-attaches to an
+already-running one on :9222) exactly once via `_resolveSelfManaged`. Then resolves the CDP
+endpoint and opens the underlying `CDPConnection`, storing it on `this.cdp`.
 
 ### _ensureClient
 
@@ -1790,6 +1793,14 @@ Evaluates a JavaScript expression in the page attached to the current session vi
 
 Returns **[Promise][4]<any>** the evaluated value, or `undefined` if the expression has no result.
 
+### _findFreePort
+
+Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading back the
+OS-assigned port. Used when `options.port` isn't explicitly set, so multiple `run-workers`
+workers never collide on the same port.
+
+Returns **[Promise][4]<[number][7]>** a free port.
+
 ### _grabCurrentPath
 
 Resolves the current page URL to a `pathname`, ignoring the origin, query string, and hash.
@@ -1824,6 +1835,26 @@ retrying once, mirroring the `'__NO_CLIENT__'` handling right next to it.
 
 *   `needsXPath` **[boolean][11]**  
 
+### _manageServer
+
+Opts a subclass into managing its own browser server process. Called from a subclass
+constructor with the raw user config and a server descriptor:
+
+*   `name` — binary name looked up on `PATH`, also used in messages
+*   `envVar` — environment variable that may point at the binary
+*   `args(port)` — arguments the binary is spawned with to serve CDP on `port`
+*   `env` — extra environment variables for the spawned process
+*   `releases` — URL shown when no binary can be resolved
+
+An explicit `endpoint` in the user config always wins: the helper stays in ATTACH mode and
+never spawns or kills anything. Otherwise the helper becomes SELF-MANAGED and the default
+`endpoint` is cleared until `_resolveSelfManaged` sets the real one.
+
+#### Parameters
+
+*   `config` **[object][5]** the config object the helper was constructed with.
+*   `server` **[object][5]** the server descriptor described above.
+
 ### _needsVisibleTextFallback
 
 Determines whether `see`/`dontSee`/`waitForText` should read whole-page text through the
@@ -1931,6 +1962,25 @@ The `xpath`/`innerText` probes determine *whether* their respective fallback is
 do not install anything — injection stays deferred to `_ensureClient`'s reactive install and
 `_textSource`'s own read, matching `amOnPage` no longer eagerly installing the client.
 
+### _probeUp
+
+Probes a `/json/version`-style URL with a short timeout, used for the courtesy-attach check.
+
+#### Parameters
+
+*   `url` **[string][3]**&#x20;
+
+Returns **[Promise][4]<[boolean][11]>** true if the URL answered.
+
+### _resolveBinary
+
+Resolves the binary to spawn, in priority order: `options.binaryPath`, then the server
+descriptor's environment variable, then its name on `PATH`. The `PATH` lookup walks the
+directories itself instead of shelling out to `which`, which does not exist on Windows: on
+Windows every `PATHEXT` suffix is tried, so a `.exe` on `PATH` is found too.
+
+Returns **([string][3] | null)** an absolute or relative path to the binary, or null if none resolved.
+
 ### _resolveEndpoint
 
 Acquires a Kitesurf browser session from the Cloudflare Browser Run API and resolves it to
@@ -1939,6 +1989,18 @@ which resolves a fixed local endpoint instead of provisioning a cloud session pe
 
 Returns **[Promise][4]<[string][3]>** a `wss://` debugger URL ready to be passed to `CDPConnection`.
 
+### _resolveSelfManaged
+
+Resolves how to reach a SELF-MANAGED browser, trying, in order: spawn a binary
+(`binaryPath` config, then the descriptor's `envVar`, then its `name` on `PATH`) on
+`options.port` or a free port, courtesy-attach to `http://127.0.0.1:9222` if something already
+answers there (never killed by this helper), or throw a loud, actionable error. Sets
+`this.options.endpoint` as a side effect.
+
+A spawn failure (e.g. a bad binary) is delivered asynchronously by Node as an `error` event;
+it is recorded on `this.serverError` and surfaced as a rejection from `_waitForServer` instead
+of crashing the process as an uncaught exception.
+
 ### _run
 
 Delegates a find-and-act call to `window.__codecept.run(candidates, action, payload)`. This is
@@ -2155,6 +2217,14 @@ navigation, competing for the same CDP connection with real work.
 
 Returns **[Promise][4]<void>**&#x20;
 
+### _waitForServer
+
+Polls `http://127.0.0.1:<port>/json/version` until the spawned server responds,
+`this.serverError` is set by the process' `error` event, or `options.serverStartTimeout`
+elapses. The process typically comes up within tens of milliseconds — a 20ms retry interval
+keeps the wasted tail after the server is actually ready small, since this cost is paid once
+per run and counts directly toward real-world startup latency.
+
 ### _withinBegin
 
 Starts a `within` block, scoping every subsequent `_run` call (and therefore every element