> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openqa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Scaffold a browser test harness into your project in 2 minutes

# Quickstart

Run this from your existing project root:

```bash theme={null}
npx openqa init
```

The interactive wizard asks 4 questions — then everything is set up automatically.

***

## Step 1: Choose your agent

| Agent           | SDK                              | Best for                                          |
| --------------- | -------------------------------- | ------------------------------------------------- |
| **Claude Code** | `@anthropic-ai/claude-agent-sdk` | Anthropic models only                             |
| **OpenCode**    | `@opencode-ai/sdk`               | Any provider: Anthropic, OpenAI, Google, and more |

Both agents connect to the same Playwright MCP server over HTTP and expose the same interface. You can swap between them by changing one import.

***

## Step 2: Choose your model

**Claude Code** models:

| Model               | Speed  | Best for             |
| ------------------- | ------ | -------------------- |
| `claude-haiku-4-5`  | Fast   | Default, most tests  |
| `claude-sonnet-4-6` | Medium | Complex flows        |
| `claude-opus-4-7`   | Slow   | Most demanding tasks |

**OpenCode** models use `provider/model` format:

| Model                        | Provider             |
| ---------------------------- | -------------------- |
| `gitlab/duo-chat-haiku-4-5`  | GitLab Duo (default) |
| `github-copilot/gpt-5.4`     | GitHub Copilot       |
| `anthropic/claude-haiku-4-5` | Anthropic            |
| `openai/gpt-4o`              | OpenAI               |
| `google/gemini-2.0-flash`    | Google               |

Or enter any custom model name your OpenCode installation supports.

***

## Step 3: Choose your framework

**Playwright-BDD** — Uses Gherkin `.feature` files with the Playwright test runner. Recommended.

**Cucumber.js** — Standard Cucumber with Playwright browser automation.

***

## Step 4: Point to your feature files

Enter the relative path from your project root to your `.feature` files. For example:

* `features/` — default
* `tests/features/`
* `src/test/features/`

The harness will be configured to point at them automatically, wherever they live.

***

## What gets created

```
your-project/
└── .openqa/               ← agent harness lives here
    ├── .env.example       ← copy to .env and fill in your values
    ├── .env.schema        ← committed schema: variable types, defaults, secret redaction
    ├── playwright.config.ts  (or cucumber.js)
    ├── features/          ← example feature files (edit or replace these)
    │   ├── todomvc.feature        ← 2 scenarios
    │   └── getting-started.feature ← 1 scenario
    └── steps/
        ├── fixtures.ts    ← Playwright-BDD only
        └── steps.ts       ← single AI step definition
```

Feature files live in `.openqa/features/` by default. To move them, update the path in `playwright.config.ts` (or `cucumber.js`) — see [Writing Feature Files](#writing-feature-files).

***

## Authentication

<Note>
  **No API key needed for local development.** Just log in once with the CLI and you're done.
</Note>

<Tabs>
  <Tab title="Claude Code (local)">
    ```bash theme={null}
    claude login
    ```

    One-time login. No `.env` needed for local runs.
  </Tab>

  <Tab title="OpenCode (local)">
    ```bash theme={null}
    opencode auth login
    ```

    One-time login — works with GitLab Duo, GitHub Copilot, Anthropic, OpenAI, Google, and more. No `.env` needed for local runs.
  </Tab>

  <Tab title="API Key (Claude Code)">
    ```bash theme={null}
    cp .openqa/.env.example .openqa/.env
    # then add:
    ANTHROPIC_API_KEY=your_key_here
    ```

    Use this for CI or if you prefer an explicit key.
  </Tab>

  <Tab title="API Key (OpenCode)">
    ```bash theme={null}
    cp .openqa/.env.example .openqa/.env
    # then add whichever provider key you need:
    ANTHROPIC_API_KEY=your_key_here
    # OPENAI_API_KEY=your_key_here
    # GOOGLE_API_KEY=your_key_here
    ```

    Use this for CI or if you prefer an explicit key.
  </Tab>
</Tabs>

***

## Environment Variables

The scaffolded project uses [varlock](https://varlock.dev) for environment variable management. Variables are defined in `.env.schema` (committed to git) and values go in `.env` (gitignored). Secrets are automatically redacted from logs.

| Variable            | Default | Description                                                              |
| ------------------- | ------- | ------------------------------------------------------------------------ |
| `BASE_URL`          | —       | App URL — sets Playwright `baseURL` and injected into every agent prompt |
| `APP_USERNAME`      | —       | Username — injected into agent prompt for login steps                    |
| `APP_PASSWORD`      | —       | Password — injected into prompt; always redacted from logs               |
| `OPENQA_VERBOSE`    | `true`  | Set `false` to suppress step-by-step agent logs                          |
| `HEADLESS`          | `true`  | Set `false` to watch the browser                                         |
| `ANTHROPIC_API_KEY` | —       | Anthropic API key — CI only (use `claude login` locally)                 |
| `OPENAI_API_KEY`    | —       | OpenAI API key — CI only via OpenCode                                    |
| `GOOGLE_API_KEY`    | —       | Google API key — CI only via OpenCode                                    |

All variables are optional. Copy `.env.example` to `.env` and uncomment what you need.

**Adding your own variables** — declare them in `.env.schema`, add values to `.env`:

```
# .env.schema
# @sensitive=false
ENVIRONMENT = staging

STAGING_USER =
# @sensitive
STAGING_PASSWORD =
```

***

## Customizing Your Setup

`openqa init` is a starting point — everything in `.openqa/` is yours to edit.

**Playwright config** — `.openqa/playwright.config.ts` is a standard [Playwright config file](https://playwright.dev/docs/test-configuration). Update timeouts, add projects, enable retries, change reporters — anything the Playwright docs describe will work here.

**Step definitions** — `.openqa/steps/steps.ts` is a regular [Playwright-BDD](https://playwright-bdd.dev) step file (or [Cucumber.js](https://github.com/cucumber/cucumber-js) for the Cucumber framework). Add non-AI steps, Before/After hooks, or custom fixtures alongside the AI step.

***

## Writing Feature Files

Two example feature files are scaffolded into `.openqa/features/` — edit or replace them with your own tests.

Use `*` (asterisk) for natural, AI-friendly steps:

```gherkin theme={null}
Feature: TodoMVC

  Scenario: Add a todo item
    * I navigate to "https://demo.playwright.dev/todomvc/"
    * I add a new todo item "Buy groceries"
    * I should see "Buy groceries" in the todo list

  Scenario: Filter completed todos
    * I navigate to "https://demo.playwright.dev/todomvc/"
    * I add three todo items: "Task 1", "Task 2", and "Task 3"
    * I mark the first todo as completed
    * I click the Active filter
    * I should see 2 active todos
```

Standard `Given`/`When`/`Then` also works — both are identical under the hood.

**Tips for good steps:**

* Be specific about URLs: `I navigate to "https://..."` not `I go to the site`
* Quote the exact text you expect: `I should see "Buy groceries"`
* Describe intent, not mechanics: `I add a new todo item "..."` not `I click the input and type "..."`

**Moving feature files elsewhere** — update the path in `.openqa/playwright.config.ts` (or `cucumber.js`):

```typescript theme={null}
// playwright.config.ts — point to a directory outside .openqa/
const testDir = defineBddConfig({
  featuresRoot: '../features',
  features: '../features/**/*.feature',
  steps: 'steps/*.ts',
});
```

***

## Run your tests

```bash theme={null}
cd .openqa
npm run test:headed   # visible browser
npm run test          # headless
npm run test:report   # open the HTML report
```

***

## Changing Model or Provider

Your model is set in one line inside `.openqa/steps/steps.ts` (Playwright-BDD) or `.openqa/steps/steps.js` (Cucumber.js). Open that file and change the provider call — that's it.

**Change the Claude Code model:**

```typescript theme={null}
import { runAgent, claudeCode } from 'openqa';

// Fast (default)
await runAgent(claudeCode('claude-haiku-4-5'), action, page);

// More capable
await runAgent(claudeCode('claude-sonnet-4-6'), action, page);
await runAgent(claudeCode('claude-opus-4-7'), action, page);
```

**Switch to OpenCode — GitLab Duo or GitHub Copilot:**

```typescript theme={null}
import { runAgent, openCode } from 'openqa';  // swap the import

// GitLab Duo (if you use gitlab.com — login with opencode auth login)
await runAgent(openCode('gitlab/duo-chat-haiku-4-5'), action, page);

// GitHub Copilot (if you use GitHub — login with opencode auth login)
await runAgent(openCode('github-copilot/gpt-5.4'), action, page);
```

**Switch to OpenCode — Anthropic, OpenAI, or Google:**

```typescript theme={null}
import { runAgent, openCode } from 'openqa';

await runAgent(openCode('anthropic/claude-sonnet-4-6'), action, page);
await runAgent(openCode('openai/gpt-4o'), action, page);
await runAgent(openCode('google/gemini-2.0-flash'), action, page);
```

<Note>
  Switching between `claudeCode` and `openCode` requires changing the import **and** the provider call. Everything else — feature files, step syntax, test runner commands — stays the same.
</Note>

***

## Examples

Browse working examples in the repository:

* [`examples/playwright-bdd/`](https://github.com/openqa-labs/openqa/tree/main/examples/playwright-bdd) — Playwright-BDD with natural language steps
* [`examples/cucumberjs/`](https://github.com/openqa-labs/openqa/tree/main/examples/cucumberjs) — Cucumber.js integration
* [`examples/playwright-yaml/`](https://github.com/openqa-labs/openqa/tree/main/examples/playwright-yaml) — YAML-based tests