---
title: Shiplight Fixture
description: The Playwright fixture that executes YAML E2E tests — authentication, Chrome extension support, persistent profiles, test context, and the AI agent.
---

# Shiplight Fixture

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

The `shiplightai` package provides a Playwright fixture that extends the standard `test` object with additional capabilities. These are configured via the `use:` block in your YAML E2E test or in `playwright.config.ts`.

The [YAML language](/local/yaml-tests/) defines _what_ your test does. The **fixture** is the runtime that _executes_ the test, providing authentication, Chrome extension support, and AI agent integration.

## Authentication (`auth`)

Automatically log in before the test runs. Point to a TypeScript module that exports a `login()` function returning a storage state file path:

```yaml
goal: Verify dashboard after login
base_url: https://app.example.com

use:
  auth: ./auth.login.ts
  args:
    username: "{{TEST_USER}}"
    password: "{{TEST_PASS}}"
statements:
  - URL: /dashboard
  - VERIFY: Dashboard is displayed
```

The `login()` function handles login and returns a storage state for the test to run.

## Chrome Extension Testing (`extensionDir`)

Load an unpacked Chrome extension into the browser:

```yaml
goal: Verify extension injects banner
base_url: https://example.com

use:
  extensionDir: ./my-extension
statements:
  - URL: /
  - VERIFY: Extension banner is visible at the top of the page
```

The fixture launches a persistent Chromium context with `--load-extension` in headed mode (headless Chrome cannot load extensions).

## Persistent Chrome Profile (`userDataDir`)

Reuse a Chrome profile directory across test runs. Works with or without extensions — useful for Google OAuth, cached sessions, or any state that lives in the Chrome profile:

```yaml
goal: Verify app with persistent login
base_url: https://app.example.com

use:
  userDataDir: ./chrome-profile
statements:
  - URL: /
  - VERIFY: User is already logged in
```

Can also be combined with `extensionDir`:

```yaml
goal: Verify extension with cached state
base_url: https://example.com

use:
  extensionDir: ./my-extension
  userDataDir: ./chrome-profile
statements:
  - URL: /
  - VERIFY: Extension shows saved settings
```

## Extension Storage State (`extensionStorageState`)

Inject cookies into a persistent extension context (since Playwright's `storageState` option doesn't work with persistent contexts):

```yaml
goal: Test extension on authenticated page
base_url: https://app.example.com

use:
  extensionDir: ./my-extension
  extensionStorageState: ./auth/storage-state.json
statements:
  - URL: /
  - VERIFY: User is logged in and extension is active
```

## Test Context (`testContext`)

The `testContext` fixture provides a shared variable store accessible from YAML steps, custom functions, and inline code. It supports property-style access:

```ts
// In a custom function
export async function setup_user(page, testContext) {
  testContext.userId = "user-123"; // write
  const email = testContext.userEmail; // read
}
```

Variables set on `testContext` are available in YAML as <code v-pre>{{variableName}}</code>, and vice versa. The agent's `$variableName` resolves from the same store.

## Agent (`agent`)

The `agent` fixture provides the AI for actions like `VERIFY`, `intent:` resolution, and `ai_extract`. It shares the same variable store as `testContext`. Configured automatically from environment variables:

| Variable                                | Description                                    |
| --------------------------------------- | ---------------------------------------------- |
| `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` | At least one required — model is auto-detected |
| `WEB_AGENT_MODEL`                       | Override model selection                       |

AI features (DRAFT statements, VERIFY, ai_extract) require an API key. ACTION statements with `js:` or `action:` run without one.

For full details on the agent's capabilities, see the Agent SDK documentation.