codeceptjs 4.2.0 → 4.2.1-beta.2

package/docs/helpers/Lightpanda.md

@@ -0,0 +1,139 @@
+---
+permalink: /helpers/Lightpanda
+editLink: false
+sidebar: auto
+title: Lightpanda
+---
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Lightpanda
+
+**Extends CDPBrowser**
+
+Lightpanda drives [Lightpanda][1], a headless browser written from scratch
+for automation, exposed over the Chrome DevTools Protocol. It executes real JavaScript in V8 and
+implements the DOM and Web APIs, but has no graphical rendering engine: nothing is ever painted,
+so there are no screenshots.
+
+This helper is a thin `CDPBrowser` subclass: it changes nothing about how locating or acting on
+elements works, it only pins the config presets Lightpanda requires and manages the
+`lightpanda serve` process lifecycle, the same way Playwright manages its own browser process.
+
+> Lightpanda support is experimental. Pin the browser version in CI and keep a
+> Playwright/WebDriver job for browser-compatibility coverage.
+
+## Modes
+
+*   **ATTACH** — `endpoint` is set explicitly in the config. The helper only connects to it; it
+    never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
+*   **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
+    the config, then the `LIGHTPANDA_PATH` environment variable, then `lightpanda` on `PATH`. The
+    helper spawns `lightpanda serve --host 127.0.0.1 --port <port>` (`port` from the config, or a
+    free port picked automatically), waits for it to answer, connects, and kills it in
+    `_finishTest`.
+*   **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
+    answers `http://127.0.0.1:9222/json/version` (e.g. `lightpanda serve` started by hand, or the
+    `lightpanda/browser` Docker image). The helper attaches to it and never kills it. If neither a
+    binary nor a running server on :9222 can be found, the helper throws a loud, actionable error.
+
+## Install
+
+Follow the [official installation instructions][2],
+then put `lightpanda` on your `PATH`, or point `binaryPath`/`LIGHTPANDA_PATH` at it. The helper
+then launches and tears it down automatically.
+
+Lightpanda sends usage telemetry by default. This helper always spawns it with
+`LIGHTPANDA_DISABLE_TELEMETRY=true`; set that variable yourself when you start the server by hand.
+
+Lightpanda is licensed under AGPL-3.0. It runs as a separate process that CodeceptJS talks to
+over a WebSocket, so it does not change the license of CodeceptJS or of your tests.
+
+## Config presets
+
+These are set automatically and only need overriding for unusual setups:
+
+| option                    | value       | why                                                                                                                                                                                                                                        |
+| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `input`                   | `synthetic` | nothing is painted, so coordinates are not hit-tested; `click` always takes the `forceClick` path                                                                                                                                          |
+| `xpathPolyfill`           | `auto`      | probed per binary/page                                                                                                                                                                                                                     |
+| `capabilities.layout`     | `real`      | Lightpanda computes visibility-related styles and element boxes without painting, which is enough for `seeElement` and the `waitForVisible` family; it is pinned because the runtime layout probe cannot run on Lightpanda's `about:blank` |
+| `capabilities.screenshot` | `false`     | there is no rendering engine                                                                                                                                                                                                               |
+
+## Limitations
+
+*   No screenshots and no screencast: `saveScreenshot` and `saveElementScreenshot` do nothing (a debug message is printed).
+*   No frames or popups.
+*   No scrolling: scroll positions always stay at 0.
+*   Computed styles cover what visibility checks need (`display`, `visibility`, `opacity`,
+    `pointer-events`); `grabCssPropertyFrom` and `seeCssPropertiesOnElements` are unreliable for
+    other properties.
+*   No coordinate-based input (`clickXY`).
+*   No clipboard access.
+*   Some rich text editors (TinyMCE, Trix, Monaco) never finish initialising.
+
+
+
+## Configuration
+
+This helper should be configured in codecept.conf.js
+
+Type: [object][3]
+
+### Properties
+
+*   `endpoint` **[string][4]?** explicit CDP endpoint. Setting this switches the helper to ATTACH
+    mode: it only connects, and never spawns or kills a process, no matter what else is configured.
+    Leave it unset for SELF-MANAGED mode (see below).
+*   `binaryPath` **[string][4]?** path to the `lightpanda` executable, used in SELF-MANAGED mode
+    (`endpoint` unset). Checked before `LIGHTPANDA_PATH` and `PATH`.
+*   `port` **[number][5]?** port `lightpanda serve` listens on, in SELF-MANAGED mode. When unset, a
+    free port is picked automatically, which is what makes `run-workers` collision-free — every
+    worker gets its own instance on its own port with zero config.
+*   `serverStartTimeout` **[number][5]?** milliseconds to wait for a spawned `lightpanda serve`
+    to answer `/json/version` before `_connect` gives up.
+
+
+
+## Example
+
+```js
+// inside codecept.conf.js — SELF-LAUNCH mode (recommended): the helper finds/starts/stops
+// lightpanda serve on its own, on a free port. Ideal for run-workers: every worker gets its
+// own instance with no config.
+{
+  helpers: {
+    Lightpanda: {
+      url: 'http://localhost',
+    }
+  }
+}
+```
+
+```js
+// ATTACH mode — connect to a Lightpanda instance you manage yourself (remote host, container, etc.)
+{
+  helpers: {
+    Lightpanda: {
+      url: 'http://localhost',
+      endpoint: 'http://127.0.0.1:9222',
+    }
+  }
+}
+```
+
+## Methods
+
+### Parameters
+
+*   `config` **LightpandaConfig**&#x20;
+
+[1]: https://lightpanda.io
+
+[2]: https://lightpanda.io/docs/open-source/installation
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number