You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 01a9ba5
Browse filesBrowse the repository at this point in the historyBrowse files
@@ -6,149 +6,175 @@ title: Alternative Browser Engines
6
6
# Alternative Browser Engines
7
7
8
8
::: warning Experimental
9
-
The `Lightpanda`, `Obscura` and `Kitesurf` helpers are experimental. Keep a Playwright or WebDriver job for compatibility-critical tests.
9
+
The `Obscura`, `Lightpanda` and `Kitesurf` helpers are experimental. Keep a Playwright or WebDriver job for compatibility-critical tests.
10
10
:::
11
11
12
-
Your tests stay the same. `I.amOnPage`, `I.click`, `I.fillField`, `I.see`, `I.seeElement` and the rest of the `I.*` web API work on every engine below; only the helper in the config changes.
12
+
Playwright drives full Chromium, Firefox and WebKit: the most accurate way to test what users see, at the cost of a heavy browser per worker. Alternative engines trade part of that accuracy for speed, a small footprint, or cloud scale. They are a good fit for functional tests (text appears, form submits, redirect happens, cookie is set) and a poor one for anything visual.
13
13
14
-
| Engine | What it is | Screenshots | Runs on |
15
-
|---|---|---|---|
16
-
|[Lightpanda](https://lightpanda.io)| headless browser built for automation, nothing painted | no | Linux, macOS |
17
-
|[Obscura](https://github.com/h4ckf0r0day/obscura)| lightweight browser with its own rendering engine | yes | Linux, macOS, Windows |
18
-
|[Kitesurf](https://blog.cloudflare.com/kitesurf/)| Cloudflare's browser in the cloud | yes | Cloudflare |
14
+
Your tests do not change. `I.amOnPage`, `I.click`, `I.fillField`, `I.see`, `I.seeElement` and the rest of the `I.*` web API work the same; you only swap the helper in the config. All engines below speak Chrome DevTools Protocol, so there is no `npx playwright install` step.
19
15
20
-
All three speak Chrome DevTools Protocol. There is no `npx playwright install` step: Lightpanda and Obscura are single binaries, Kitesurf is a cloud service.
16
+
Compared to Playwright, none of them supports iframes (`switchTo`), multiple tabs, popups, `dragAndDrop`, `moveCursorTo`, clipboard actions, or Playwright-only APIs such as `usePlaywrightTo`and `mockRoute`. Tag scenarios that need those and skip them on the alternative engine:
21
17
22
-
## When to use which
18
+
```sh
19
+
npx codeceptjs run --grep @playwright-only --invert
20
+
```
23
21
24
-
-**Lightpanda**: fastest start and smallest memory footprint. Functional tests that never need a screenshot.
25
-
-**Obscura**: lightweight like Lightpanda, but renders, so screenshots and failure screenshots work.
26
-
-**Kitesurf**: as many parallel browsers as you have workers, with nothing running on your machine.
27
-
-**Stay on Playwright** for visual checks, iframes, multiple tabs, drag-and-drop, network mocking, and Firefox or WebKit.
22
+
To see which `I.*` actions the configured engine supports:
28
23
29
-
## Install
24
+
```sh
25
+
npx codeceptjs list
26
+
```
30
27
31
-
Follow the official instructions, then put the binary on `PATH`:
-**Kitesurf**: [Cloudflare Browser Run](https://developers.cloudflare.com/browser-run/), then export `CF_ACCOUNT_ID` and `CF_API_TOKEN`
30
+
[Obscura](https://github.com/h4ckf0r0day/obscura) is a lightweight open-source browser with a real V8 engine and its own rendering engine, distributed as a single binary for Linux, macOS and Windows. Unlike Lightpanda it renders: layout, visibility checks, screenshots and the `screencast` plugin work.
36
31
37
-
## Configure
32
+
Limitations:
38
33
39
-
Pick the engine with an environment variable, so one config serves every engine and Playwright stays the default:
34
+
- Its CSS engine is new: some computed styles differ from Chromium, so `grabCssPropertyFrom` and `seeCssPropertiesOnElements` can disagree with Playwright.
35
+
-`click` is always dispatched as a DOM event, not a mouse event at coordinates.
36
+
-`-no-render` builds have no layout: no visibility checks and no screenshots.
Install Obscura following the [official instructions](https://github.com/h4ckf0r0day/obscura#installation) and put `obscura` on `PATH`. Then enable the helper:
There is nothing to start by hand. Lightpanda and Obscura are launched on a free port before the first test and stopped after the last one, the way Playwright manages Chromium.
53
+
If the binary is not on `PATH`, set `binaryPath` in the config or the `OBSCURA_PATH` environment variable.
60
54
61
-
If the binary is not on `PATH`, point the helper at it, like Playwright's `executablePath`:
Or set it per machine with an environment variable:
61
+
The helper starts `obscura serve` on a free port before the first test and stops it after the last one, like Playwright manages Chromium. Each worker gets its own instance:
68
62
69
63
```sh
70
-
LIGHTPANDA_PATH=/opt/lightpanda/lightpanda npx codeceptjs run
64
+
npx codeceptjs run-workers 8
71
65
```
72
66
73
-
The helper checks `binaryPath`, then `LIGHTPANDA_PATH` (`OBSCURA_PATH` for Obscura), then `PATH`. Relative paths resolve from the directory you run `npx codeceptjs` in.
74
-
75
-
## Run
67
+
To connect to an Obscura you started yourself, set `endpoint`; the helper then never starts or stops it:
Each worker starts its own browser on its own port:
82
-
83
-
```sh
84
-
ENGINE=lightpanda npx codeceptjs run-workers 8
73
+
```js
74
+
Obscura: {
75
+
url:'http://localhost:3000',
76
+
endpoint:'http://127.0.0.1:9222',
77
+
}
85
78
```
86
79
87
-
See which `I.*` actions the engine supports:
80
+
All options: [Obscura helper reference](/helpers/Obscura).
88
81
89
-
```sh
90
-
ENGINE=lightpanda npx codeceptjs list
91
-
```
82
+
## Lightpanda
83
+
84
+
[Lightpanda](https://lightpanda.io) is an open-source headless browser built from scratch for automation. It runs your app's JavaScript in V8 but never paints anything, which makes it start in milliseconds and use a fraction of Chromium's memory. It computes enough layout for `seeElement`, `waitForVisible` and other visibility checks.
92
85
93
-
## Exclude what an engine cannot do
86
+
Limitations:
94
87
95
-
Most functional tests pass unchanged. These Playwright features do not carry over:
88
+
- No screenshots: `saveScreenshot`, failure screenshots and the `screencast` plugin do not work.
89
+
- No scrolling: `scrollTo` and `scrollPageToBottom` have no effect.
90
+
- No coordinate input: `clickXY` does not work.
91
+
- Computed styles cover `display`, `visibility` and `opacity`; other CSS properties are unreliable.
92
+
- Some rich text editors (TinyMCE, Trix, Monaco) never finish loading.
93
+
- Linux and macOS only; on Windows use WSL2.
94
+
- Licensed under AGPL-3.0. It runs as a separate process, so it does not affect the license of your tests.
96
95
97
-
| Feature | Lightpanda | Obscura |
98
-
|---|---|---|
99
-
|`saveScreenshot`, failure screenshots, `screencast` plugin | no | yes |
100
-
|`seeElement`, `waitForVisible` and other visibility checks | yes | yes |
101
-
|`switchTo` (iframes), new tabs, popups | no | no |
102
-
|`dragAndDrop`, `moveCursorTo`| no | no |
103
-
|`clickXY`| no | yes |
104
-
|`scrollTo`, `scrollPageToBottom`| no effect | yes |
105
-
|`grabCssPropertyFrom`, `seeCssPropertiesOnElements`|`display`, `visibility`, `opacity` only | most properties |
106
-
| clipboard actions | no | no |
107
-
|`usePlaywrightTo`, `mockRoute`, downloads | no | no |
96
+
### Setup
108
97
109
-
Tag the scenarios that need a full browser:
98
+
Install Lightpanda following the [official instructions](https://lightpanda.io/docs/open-source/installation) and put `lightpanda` on `PATH`. Then enable the helper:
110
99
111
100
```js
112
-
Scenario('checkout matches the design @visual', ({ I }) => {
113
-
I.amOnPage('/checkout')
114
-
I.saveScreenshot('checkout.png')
115
-
})
101
+
// codecept.conf.js
102
+
exportconstconfig= {
103
+
helpers: {
104
+
Lightpanda: {
105
+
url:'http://localhost:3000',
106
+
},
107
+
},
108
+
}
116
109
```
117
110
118
-
And skip them on the lightweight engine:
111
+
If the binary is not on `PATH`, set `binaryPath` in the config or the `LIGHTPANDA_PATH` environment variable.
112
+
113
+
### Usage
119
114
120
115
```sh
121
-
ENGINE=lightpanda npx codeceptjs run --grep @visual --invert
116
+
npx codeceptjs run
122
117
```
123
118
124
-
## Run in CI
119
+
The helper starts `lightpanda serve` on a free port with telemetry turned off, and stops it after the last test. Each worker gets its own instance:
125
120
126
-
Install the binary in a step before the tests, and point the helper at it with `LIGHTPANDA_PATH` (or `OBSCURA_PATH`) if it is not on `PATH`. Run the lightweight engine as a fast first job and keep Playwright for the full run.
121
+
```sh
122
+
npx codeceptjs run-workers 8
123
+
```
127
124
128
-
## Connect to a running browser
125
+
To connect to a Lightpanda you started yourself, set `endpoint`; the helper then never starts or stops it:
129
126
130
-
To use a browser you started yourself (a container, a remote host), set `endpoint`. The helper then only connects and never starts or stops anything:
Start Lightpanda yourself with telemetry turned off:
138
+
All options: [Lightpanda helper reference](/helpers/Lightpanda).
139
+
140
+
## Kitesurf
141
+
142
+
[Kitesurf](https://blog.cloudflare.com/kitesurf/) is Cloudflare's browser running on Cloudflare Workers, with a real layout and rendering pipeline. Sessions start in about a second and nothing runs on your machine, so the number of parallel browsers is limited only by how far your suite splits.
143
+
144
+
Limitations:
145
+
146
+
- Cloud only, currently a free beta.
147
+
- The browser cannot reach `localhost`: test a deployed environment or expose your app with a tunnel such as `cloudflared tunnel --url http://localhost:3000`.
148
+
- The `screencast` plugin is untested.
149
+
150
+
### Setup
151
+
152
+
Enable [Cloudflare Browser Run](https://developers.cloudflare.com/browser-run/) and create an API token with the **Browser Rendering → Edit** permission. Export the credentials:
0 commit comments