# Hover

> Hover is the regression-test suite built for vibe coding, powered by an MCP server. Vibe-coding ships fast and breaks quietly; Hover keeps a vibe-coded app from breaking as the AI keeps changing it. Add @hover-dev/mcp to the coding agent you already run; describe a flow and it crystallizes into a plain test you own (a standard @playwright/test spec) that runs in your CI with zero AI. Hover Cloud (live, free early access) judges every CI run (drift vs bug) and routes the fix back to your editor — without running any browsers. Tagline: "Keep your vibe-coded app from breaking."

Hover is MCP-first. The authoring engine is an MCP server (`@hover-dev/mcp`) that plugs into your OWN coding agent (Claude Code, Cursor, …). You call the `test_app` MCP prompt; the agent logs in, browses, and checks out — acting through Hover's grounded browser tools — and each flow is saved as a standard `@playwright/test` spec under `__vibe_tests__/`. The saved spec runs in CI like any Playwright test: no agent, no model, no API key, no per-token billing. An optional VS Code extension adds a review cockpit (a Business Map graph of your flows + a pass/fail Dashboard); it drives no agent. Hover Cloud is a hosted data/insights layer over the runs your own CI already produces.

Available in English (https://gethover.dev/) and Chinese (https://gethover.dev/zh/).

## What makes Hover different

- **record == replay.** The agent acts through grounded browser tools (role+name → testId → text), so the selector that drove a click is the exact one written into the saved spec, and crystallization is deterministic — no LLM writes the code. Playwright codegen, Stagehand and Midscene cannot guarantee this.
- **AI authors once, then steps out.** The model is spent once, at authoring. The committed artifact is plain deterministic Playwright; CI never calls a model, so green runs cost no tokens.
- **You own the artifact.** Output is standard `@playwright/test` in your git repo — no proprietary format, no runtime dependency on Hover, no lock-in. Delete Hover and every test still passes.
- **BYO-CLI, no API key held by Hover.** Hover bundles no AI runtime and holds no key; it rides whichever coding agent and subscription you already have — Claude Code (recommended), Cursor, or any MCP-capable agent.
- **Local and private.** `@hover-dev/core` binds to 127.0.0.1, has no telemetry and no upload path; the agent drives an isolated debug Chrome on a temporary profile, never your main browser.

## Install (MCP — the primary path)

Add the MCP server to the coding agent you already run:

    npm i -g @hover-dev/mcp && claude mcp add hover -- hover-mcp

Then call the `test_app` prompt (in Claude Code: `/mcp__hover__test_app`). npm: https://www.npmjs.com/package/@hover-dev/mcp — Apache-2.0. The optional review cockpit is the "Hover" VS Code extension (`hyperyond.hover-dev`). Hover drives your existing dev server over CDP, so it works with any framework (Vite, Next.js, Nuxt, Astro, webpack); native iOS / Android is out of scope.

## Key features

- MCP server you add to your own agent: it explores your app and crystallizes each flow into a plain `@playwright/test` spec with semantic `getByRole` / `getByLabel` selectors.
- record == replay — grounded actuation means the saved selector is the one that drove the click; crystallization is deterministic, no LLM writing code.
- You own the artifact — plain Playwright in your repo, running in your CI with zero AI, zero tokens, no lock-in.
- Optional VS Code cockpit — a Business Map graph of your flows + coverage and a Dashboard (pass / fail / flaky + CI results). It reviews; it does not drive the agent.
- Multi-environment accounts — test accounts per environment, parameterised into `process.env` references (never written into the spec) and exportable to CI secrets.
- Claude Code hooks (`hover-hook`) — optional, zero-AI hooks that orient the agent at session start (active environment + drifted specs) and can gate a turn from finishing while a spec is red. Deterministic; no browser, no model.

## When a saved spec breaks

Most UI churn does not break a spec, because selectors are semantic (`getByRole` / `getByLabel`), not CSS or XPath. When the semantics genuinely change, edit the plain Playwright file by hand or treat the failure as a real regression. CI never calls a model to self-heal, which keeps it deterministic and free. On failure, Hover Cloud extracts a heal hint (the failing locator and what it should be) and routes it to your editor to fix locally, human-reviewed.

## Hover Cloud (live — free early access)

A hosted data/insights layer over the specs you already own and the CI you already run. Sign in with GitHub (https://cloud.gethover.dev), connect a repo, and Hover Cloud writes the CI workflow and reporting secrets, then ingests every CI run: spec-by-spec pass / fail / flaky, pass rate, run history, and the heal hint behind a failing locator. It runs NO browsers — execution stays in your own CI (GitHub Actions); Cloud only reads results, and never edits a spec without your review. It is free while in early access. Authoring stays local and free; CI still runs plain Playwright; the spec stays entirely yours.

## 中文摘要 (Chinese summary)

Hover 是专为 vibe coding 打造的回归测试套件，由一个 MCP server 驱动。vibe coding 上线飞快、坏起来却悄无声息；在 AI 不断改动的过程中，Hover 让 vibe coding 出来的应用不崩。把 `@hover-dev/mcp` 加到你已经在用的编码 Agent（Claude Code、Cursor…），调用 `test_app` prompt；Agent 会登录、浏览、下单——全程通过 Hover 的接地（grounded）浏览器工具操作——每条流程都被存成 `__vibe_tests__/` 下标准的 `@playwright/test`。这个用例在 CI 里像普通 Playwright 测试一样跑：不需要 Agent、不需要模型、不需要 API key、没有按 token 计费。可选的 VS Code 扩展提供一个审阅驾驶舱（业务流程 Business Map 图 + 通过/失败 Dashboard），它不驱动 Agent。中文站：https://gethover.dev/zh/

Hover 的核心差异：

- **record == replay。** Agent 通过接地工具操作（role+name → testId → text），所以驱动点击的那个 selector 正是写进 spec 的那个，结晶是确定性的——没有 LLM 在写代码。codegen、Stagehand、Midscene 都无法保证这一点。
- **AI 只在编写时跑一次，然后退场。** 模型只在编写时花一次；进 git 的产物是确定性的纯 Playwright，CI 永不调用模型，绿色运行不烧 token。
- **产物归你所有。** 你 git 仓库里标准的 `@playwright/test`——无私有格式、对 Hover 无运行时依赖、无锁定。删掉 Hover，测试照样通过。
- **BYO-CLI，Hover 不持有任何 key。** 不打包 AI 运行时，搭载你已有的编码 Agent 与订阅——Claude Code（推荐）、Cursor，或任何支持 MCP 的 agent。
- **本地且私有。** `@hover-dev/core` 只绑 `127.0.0.1`，无遥测、无上传通道；Agent 操作临时 profile 上隔离的调试版 Chrome，绝不碰你的主浏览器。

**Hover Cloud（已上线 · 公测免费）**：一层架在你已有 spec 与 CI 之上的托管数据/洞察服务。用 GitHub 登录（https://cloud.gethover.dev），连上一个 repo，Cloud 就写好 CI workflow 与 secrets，然后摄入每次 CI 运行：逐条 spec 的通过/失败/flaky、通过率、运行历史，以及失败 locator 背后的 heal 提示。它**不跑任何浏览器**——执行始终在你自己的 CI（GitHub Actions），Cloud 只读结果，且绝不未经你审阅就改 spec。公测期间免费；编写始终本地且免费；CI 依然跑纯 Playwright；spec 完全归你。

## Reading

- Vibe coding vs. vibe testing: https://gethover.dev/blog/vibe-coding-vs-vibe-testing/
- AI-authored Playwright tests (why no AI in CI): https://gethover.dev/blog/ai-authored-playwright-tests/
- Bring your own CLI, no API key: https://gethover.dev/blog/bring-your-own-cli-no-api-key/
- Playwright codegen vs. AI exploration: https://gethover.dev/blog/playwright-codegen-vs-ai-exploration/
- Self-healing without a model in CI: https://gethover.dev/blog/self-healing-playwright-tests-without-a-model-in-ci/
- Two-layer test evaluation (define the business, AI fits the code): https://gethover.dev/blog/two-layer-test-evaluation-define-the-business/
- Five Claude Code hooks that keep your regression green: https://gethover.dev/blog/claude-code-hooks-for-regression-tests/
- How to test a vibe-coded app before you ship it: https://gethover.dev/blog/test-a-vibe-coded-app-before-launch/
- Your coding agent doesn't know what it broke: https://gethover.dev/blog/your-coding-agent-doesnt-know-what-it-broke/

## Links

- Website: https://gethover.dev
- Chinese site: https://gethover.dev/zh/
- Documentation: https://gethover.dev/docs/
- Hover Cloud (free early access): https://cloud.gethover.dev
- MCP on npm: https://www.npmjs.com/package/@hover-dev/mcp
- VS Code Marketplace (review cockpit): https://marketplace.visualstudio.com/items?itemName=hyperyond.hover-dev
- Source (Apache-2.0): https://github.com/Hyperyond/Hover
- X / Twitter: https://x.com/gethover_dev
- Discord community: https://discord.gg/a85TE3NX2z
- YouTube channel: https://www.youtube.com/@hyperyond