Skip to content
Plune Plune Docs

Getting started

Cairn is an autonomous QA agent: it observes your app, grounds every locator, designs methodical test cases, generates self-repairing Playwright specs, and judges the result. This guide walks the full cycle once.

v0.6.0Apache-2.0Node 20+

observe ground design generate & validate judge & learn

  1. Install and configure

    Section titled “Install and configure”
    Terminal window
    npm install -g @plune-ai/cairn

    Create a .env (copy .env.example) with at least your LLM key:

    ANTHROPIC_API_KEY=sk-ant-...
    # or:  OPENROUTER_API_KEY=sk-or-...   and   LLM_PROFILE=openrouter

  2. Capture a session (for pages behind login)

    Section titled “Capture a session (for pages behind login)”
    Terminal window
    cairn session capture --url https://app.example.com/login --name myapp

    A browser opens; log in manually, then press Enter. Cookies + localStorage are saved to .auth/myapp.storageState.json and reused for every run — no credentials in code. Skip this step for public pages. (cairn login is a shorthand; inside the repo npm run session:save -- … works too.)

  3. Design test cases — no code yet

    Section titled “Design test cases — no code yet”

    The easiest first run is the interactive TUI — cairn with no arguments. Prefer the command line?

    Terminal window
    cairn design --url https://app.example.com/page --session myapp

    The agent observes the page, verifies every locator against it, and writes cases using EP, BVA, decision tables, and state transitions (ISO/IEC/IEEE 29119-4) into runs/<id>/testcases/.

    Steer what it covers with an optional checklist: cairn design … --checklist plan.md.

    ATC

    Automatable — read-only checks on verified locators. The bot generates Playwright code for these.

    MTC

    Manual — form submits, security/XSS, visual judgment, irreversible actions. Left to humans on purpose.

  4. Review the cases

    Section titled “Review the cases”

    Each ATC-*.md / MTC-*.md file has a title, preconditions, steps, expected result, and recorded selectors. In the TUI: Browse past runs → open your run → Cases tab.

  5. Promote a manual case (optional)

    Section titled “Promote a manual case (optional)”

    Reviewed an MTC and decided it’s actually safe to automate? Convert it to an ATC in place:

    Terminal window
    cairn promote --run runs/<id> --cases MTC-LOGIN-001

  6. Automate & validate

    Section titled “Automate & validate”
    Terminal window
    cairn automate --run runs/<id> --validate --session myapp

    Generates POM-style @playwright/test specs from the ATC cases, runs them, classifies pass / fail / flaky, and self-repairs failures. Keep-best: a repair never makes the suite worse.

    Run result
    12 specs 11 green · 91.7% 1 flaky → repaired ◆ Pilot: PASS (92%)

…or run everything at once:

Terminal window
cairn explore --url https://app.example.com/page --session myapp

Next steps

Section titled “Next steps”