---
title: Local Testing with Shiplight CLI
description: Run YAML E2E tests locally with the Shiplight CLI — project structure, prerequisites, and how tests run alongside your Playwright suite.
---

# Local Testing with Shiplight CLI

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

The Shiplight CLI (`shiplightai`) runs YAML E2E tests locally — end-to-end browser tests authored in YAML instead of Playwright code. Coding agents create and maintain these tests, while humans can review the readable YAML, run the tests locally, and hand-tune complex UI flows in the debugger. YAML E2E tests run alongside your existing `.test.ts` files with no separate tooling.

The CLI includes an AI agent for natural language actions, self-healing locators, and VERIFY assertions — the same agent used in [Shiplight Cloud](/cloud/quickstart) execution.

::: tip Let your agent set this up
You rarely need to scaffold or wire this by hand. Run **`/shiplight init`** to scaffold the project and **`/shiplight create-yaml-tests`** to author tests — your coding agent handles dependencies, API keys, `playwright.config.ts`, and the first tests. This page documents what those produce so you can review, run, and hand-tune the results. See [the full `/shiplight` skill](/getting-started/what-is-shiplight#your-agent-does-the-work-shiplight).
:::

## On this section

- [Authentication](/local/local-testing/authentication) — shared-account and per-test login patterns
- [Configuration](/local/local-testing/configuration) — `shiplightConfig()` and report options
- [Debugging](/local/local-testing/debugging) — the visual debugger for hand-tuning tests
- [CLI Reference](/local/cli-reference) — every `shiplight` command and flag

## Prerequisites

- **Node.js** >= 22
- **AI API key** — `GOOGLE_API_KEY` ([Get key](https://aistudio.google.com/app/apikey)) or `ANTHROPIC_API_KEY` ([Get key](https://console.anthropic.com/settings/keys))

Store API keys and credentials in a `.env` file in your project root — the CLI auto-discovers it on startup. Make sure `.env` is in your `.gitignore`.

## Quick Start

Invoke `/shiplight create-yaml-tests` in your coding agent (Claude Code, Cursor, or Codex) to get started. The agent scaffolds the project, installs dependencies, configures API keys, and writes the first YAML E2E tests for your app.

Run tests with:

```bash
npx shiplight test
```

## Project Structure

A typical project follows standard Playwright conventions. Shiplight adds `.env` for API keys and credentials.

```
my-tests/
├── playwright.config.ts
├── package.json
├── .env                            # API keys + credentials (gitignored)
├── .gitignore
│
├── tests/
│   ├── public-app/                 # No login needed
│   │   ├── search.test.yaml
│   │   └── filter.test.yaml
│   │
│   └── my-saas-app/               # Requires login
│       ├── auth.setup.ts           # Playwright login setup
│       ├── dashboard.test.yaml
│       └── settings.test.yaml
```

**Run all tests:**

```bash
npx shiplight test
```

**Run one project:**

```bash
npx shiplight test my-saas-app/
```

After the run completes, open `shiplight-report/index.html` to view the results. See [Configuration → Report](/local/local-testing/configuration#report) for customization.

## YAML E2E Test Format

See [YAML E2E Test Format](/local/yaml-tests/) for a quick overview of statement types, actions, conditionals, loops, variables, and templates.

For the complete language specification and ready-to-run examples, see the [examples repo](https://github.com/ShiplightAI/examples/tree/main/yaml-examples).

## CI/CD

Since `npx shiplight test` is a standard Playwright command, it works with any CI/CD provider — GitHub Actions, GitLab CI, CircleCI, Jenkins, etc. Just install dependencies and run:

```bash
npm ci && npx playwright install chromium && npx shiplight test
```

For Shiplight-hosted runners and the failure-triage pipeline, see [CI & Auto-triage](/local/ci).