mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-21 03:05:26 +08:00
* docs: retire sidebar page icons The docs sidebar no longer shows icons. Drop icon: from every page's frontmatter, delete the grey silhouettes in docs/images/icons/, and make check-docs-logos fail on any frontmatter icon instead of requiring one on vendor pages. Card logos stay required. The authoring-docs skill trades its Page icons section for a short Vendor logos one. * docs: require a migrate overview card for each migration guide * docs: match only top-level icon keys in check-docs-logos
141 lines
4.8 KiB
Plaintext
141 lines
4.8 KiB
Plaintext
---
|
|
title: Kernel browsers
|
|
sidebarTitle: Kernel
|
|
description: Run web targets in Kernel's hosted Chromium with the kernel() browser provider from @e2e-dev/kernel.
|
|
"og:image": "https://e2e.com/docs/images/og/integrations/kernel.png?v=c116b9983d"
|
|
"twitter:image": "https://e2e.com/docs/images/og/integrations/kernel.png?v=c116b9983d"
|
|
---
|
|
|
|
`kernel()` from `@e2e-dev/kernel` is a
|
|
[browser provider](/browser#hosted-browsers) for [Kernel](https://kernel.sh).
|
|
Each worker slot, or each attempt, gets its own hosted Chromium. Tests stay
|
|
the same. Only the target's `browser` changes.
|
|
|
|
## Setup
|
|
|
|
Install the provider and the Kernel SDK:
|
|
|
|
<CodeGroup>
|
|
```bash npm
|
|
npm install --save-dev @e2e-dev/kernel @onkernel/sdk
|
|
```
|
|
|
|
```bash pnpm
|
|
pnpm add -D @e2e-dev/kernel @onkernel/sdk
|
|
```
|
|
|
|
```bash bun
|
|
bun add -d @e2e-dev/kernel @onkernel/sdk
|
|
```
|
|
</CodeGroup>
|
|
|
|
Set the target's `browser` to `kernel()`:
|
|
|
|
```ts title="e2e.config.ts"
|
|
import type { E2EConfig } from 'e2e';
|
|
import { web } from '@e2e-dev/web';
|
|
import { kernel } from '@e2e-dev/kernel';
|
|
|
|
export default {
|
|
targets: [
|
|
{
|
|
name: 'kernel',
|
|
engine: web({ browser: kernel() }),
|
|
app: { url: 'https://staging.example.com' },
|
|
},
|
|
],
|
|
} satisfies E2EConfig;
|
|
```
|
|
|
|
Set `KERNEL_API_KEY` in the environment that `e2e run` starts in, such as a
|
|
CI secret. `workers` sets how many browsers run at the same time.
|
|
|
|
Without the key, or on a Kernel error, the lease fails with that message. In
|
|
`worker` scope the run ends before any test. In `attempt` scope only the
|
|
attempt fails.
|
|
|
|
## Fill the screen
|
|
|
|
Set the screen size with Kernel's `viewport`, and the web engine's
|
|
`viewport: null` so the page takes the size of the window:
|
|
|
|
```ts
|
|
web({
|
|
browser: kernel({ viewport: { width: 1920, height: 1080 } }),
|
|
viewport: null,
|
|
})
|
|
```
|
|
|
|
The window opens maximized, and the page [fills it](/web#fill-the-window):
|
|
1920 by 993 on a 1920 by 1080 screen. With a fixed web `viewport`, the live
|
|
view shows the page cut off, or in part of the window.
|
|
|
|
## Options
|
|
|
|
`kernel(options)` takes Kernel's create-browser body as it is: `stealth`,
|
|
`headless`, `timeout_seconds`, `profile`, `proxy_id`, `viewport`, `tags`,
|
|
and the rest of `BrowserCreateParams` in your `@onkernel/sdk`. It adds two:
|
|
|
|
| Option | Default | Meaning |
|
|
| -------- | ---------- | ------- |
|
|
| `scope` | `'worker'` | One browser per worker slot, or per attempt. See [Scopes](#scopes). |
|
|
| `replay` | `true` | A Kernel replay or the engine's screencast. See [Recordings](#recordings). |
|
|
|
|
## Scopes
|
|
|
|
`scope: 'worker'` keeps one browser per worker slot for the run. Each
|
|
attempt gets a new browser context on it, as in a local run, so a test never
|
|
sees another test's cookies, storage, or permissions. Kernel's first tab
|
|
stays open behind it. A Kernel `profile` has no effect, because it applies
|
|
only to the browser's default context.
|
|
|
|
`scope: 'attempt'` leases a new browser for each attempt, retries included.
|
|
The attempt runs in its default context, on its first tab, so a `profile`
|
|
applies and the live view shows one tab. Each test pays for a browser start,
|
|
and the [limits of a per-attempt lease](/browser#hosted-browsers) apply,
|
|
sessions included.
|
|
|
|
## Recordings
|
|
|
|
An attempt that records [video](/reference/config#video) gets a Kernel
|
|
replay of the browser's screen, saved as `video/replay.mp4` in its artifact
|
|
directory. The replay shows the whole window, tabs and address bar included,
|
|
at the size Kernel's `viewport` sets.
|
|
|
|
Replays run at Kernel's default 10 fps. To change that, pass Kernel's
|
|
start-replay body (`framerate`, `max_duration_in_seconds`, `record_audio`):
|
|
`kernel({ replay: { framerate: 20 } })`. A `framerate` above 20 needs
|
|
`gpu: true` on the browser.
|
|
|
|
Kernel replays only headed browsers, its default. With `headless: true` or
|
|
`replay: false`, the web engine records its screencast of the page instead.
|
|
|
|
## Downloads
|
|
|
|
`browser.waitForDownload` works as it does locally, in both scopes. The
|
|
provider copies each file off the browser's disk into the attempt's
|
|
artifacts.
|
|
|
|
## Watch and clean up browsers
|
|
|
|
The reporter logs `browser <id>, watch at <live view URL>` for each new
|
|
browser. Each browser carries the tags `e2e_run`, `e2e_target`, `e2e_slot`,
|
|
and `e2e_attempt` in `'attempt'` scope, on top of your `tags`. Kernel's
|
|
dashboard then names the run that started it.
|
|
|
|
When the run ends, the provider deletes every active browser tagged with the
|
|
run and target, including the browser of a worker that died. If the run
|
|
itself dies first, Kernel deletes each browser after `timeout_seconds` idle,
|
|
600 unless you pass your own.
|
|
|
|
## Next
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Hosted browsers" icon="globe" href="/browser#hosted-browsers">
|
|
How a browser provider leases browsers, and the limits of `'attempt'` scope.
|
|
</Card>
|
|
<Card title="Continuous integration" icon="rotate" href="/ci">
|
|
Run the suite on GitHub Actions or another CI service.
|
|
</Card>
|
|
</CardGroup>
|