feat(helpers): add experimental Lightpanda helper (#5730)

* 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>

* fix(typings): keep helper config types in types.d.ts only

An eighth duplicated *Config typedef makes TypeScript report the conflicts
as one file-level error that @ts-ignore cannot suppress.

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

* docs: add Lightpanda getting-started guide for Playwright users

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

* docs: show how to point the Lightpanda helper at its binary

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

* docs: rewrite alternative browsers guide, drop pinned Lightpanda version

Install steps per engine and platform, one config to switch engines,
and latest-release download links instead of a hardcoded version.

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

* docs: link to official install instructions instead of copying them

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

* docs: one section per engine in alternative browsers guide

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

* docs: list only engine limitations confirmed by the test suite

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

* fix(CDPBrowser): bound poll request timeout, prevent orphaned server process on failed start

- _waitForServer: each /json/version poll is bounded by a 1s (or remaining deadline) axios timeout,
  so a port held by something that never responds can not hang the run forever
- _connect: self-managed resolution is attempted exactly once; on failure the error is stored
  and rethrown on subsequent connects instead of spawning a second process

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

* ci(lightpanda): pin browser to 1.0.0 release

releases/latest resolves to a nightly build; the suite is tested against stable
releases and attachFile (DOM.setFileInputFiles) fails on the current nightly

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

---------

Co-authored-by: DavertMik <davert@testomat.io>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Denys Kuchma <den.kuchma@ukr.net>

Author: 4 people

.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'] },
 }
 
@@ -430,8 +431,7 @@ async function docsHelperMarkdown(name, { parent, exclude = [], excludeConfig =
 
   if (parent) {
     const parentDoc = await documentation.build([`docs/build/${parent}.js`], buildOptions)
-    const parentClass = parentDoc.find(c => c.kind === 'class')
-    for (const method of parentClass.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.