Hover/docs
EN中文
← HomeGitHub

Your first session

A guided walkthrough of one Hover run through your agent. Estimated time: 5 minutes.

Prerequisites

  • Followed Quick start — @hover-dev/mcp is added to your agent and your dev server is running.
  • A coding agent that speaks MCP (Claude Code, Cursor, …), logged in.
  • On the first run, Hover prompts you to launch an isolated debug Chrome on port 9222.

Step 1 — Set up an environment (optional)

You can let the agent log in for you without putting credentials in a spec. Define a test account and reference it by name; the agent signs in via @account. Credentials are parameterized into process.env references — never written into the spec, the JSDoc, or the sidecar — and the same names export to your CI secrets. (Account passwords are kept in VS Code SecretStorage if you use the cockpit, never in the committed roster.)

If you're working purely from the MCP in your own agent, just tell it the test credentials when it asks — it will ask rather than guess.

Step 2 — Run the test_app prompt

In your agent, invoke Hover's prompt:

/mcp__hover__test_app           # explore the whole app and crystallize a suite
/mcp__hover__test_app login     # …or scope it to one flow

The prompt walks the agent through a phased, scale-aware loop:

  1. Map the business lines. The agent reads your routes + nav with its own file tools and writes a checklist to .hover/hover-map.md — the plan for a large app.
  2. Pick a scope. If you named one, it covers that; otherwise it shows the uncovered lines and asks which to do now.
  3. Cover each flow, one at a time. For each: navigate → snapshot → exercise the real flow (click_control / fill_control / …) → assert the outcome → crystallize_spec.
  4. Update coverage in hover-map.md.

Step 3 — Watch the agent drive

The agent calls Hover's grounded tools over CDP against your debug Chrome — browser_snapshot to read the page, then click_control / fill_control / select_control / check_control to act, and assert_visible on the outcome. Because it targets controls by role+name, the selector that drives each action is the exact one that gets saved.

If the agent genuinely can't resolve something — is this a bug or by-design? what does this domain term mean? — it asks you rather than guessing, and when you confirm a durable rule it remembers it via record_fact (see your app's test knowledge).

Step 4 — Crystallize

The moment a flow is verified, the agent calls crystallize_spec, and Hover writes __vibe_tests__/<slug>.spec.ts — deterministically, using getByRole / getByLabel / getByTestId. No LLM writes the code. See Crystallize a spec for the shape of the file.

Step 5 — Run the spec without Hover

The saved file is plain @playwright/test. Run it like any other Playwright test:

npx playwright test __vibe_tests__

This is the point of crystallization: the AI authored the test once, but the saved spec runs forever in CI with zero agent involvement.

What's next

  • The MCP tools — the full grounded tool surface and the test_app prompt.
  • Test knowledge — what Hover remembers about your app under .hover/.
  • Want a visual surface? The optional VS Code cockpit adds a Business Map graph + Dashboard. It reviews — it doesn't drive the agent.
  • Optimize a spec — the optional diff-reviewed AI polish pass.