Hover

<div align="center">

# Hover

<img src="docs/assets/banner.png" alt="Hover — the local-first, open-source way to author end-to-end tests with AI" width="100%" />

<p>
  <b>English</b> · <a href="./README.zh-CN.md">简体中文</a>
</p>

<p>
  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square" /></a>
  <a href="https://www.npmjs.com/package/@hover-dev/cli"><img alt="@hover-dev/cli on npm" src="https://img.shields.io/npm/v/@hover-dev/cli?style=flat-square&label=npx%20%40hover-dev%2Fcli%20setup&color=cb3837&logo=npm&logoColor=white" /></a>
  <a href="https://www.npmjs.com/package/@hover-dev/core"><img alt="@hover-dev/core on npm" src="https://img.shields.io/npm/v/@hover-dev/core?style=flat-square&label=%40hover-dev%2Fcore&color=cb3837&logo=npm&logoColor=white" /></a>
  <a href="https://github.com/Hyperyond/Hover/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/Hyperyond/Hover?style=flat-square&color=ffd700" /></a>
  <a href="https://gethover.dev/docs"><img alt="Documentation" src="https://img.shields.io/badge/docs-gethover.dev-7CFFA8?style=flat-square&logo=readthedocs&logoColor=white" /></a>
</p>

<p>Open a chat in your dev page, describe a flow in plain English, watch AI drive your real app — then click <b>Save as spec</b> for a standard <code>@playwright/test</code> file that runs in CI with no agent, no model, no key.</p>

</div>

<p align="center">
  <a href="https://www.youtube.com/watch?v=lQV5dmVWaIA">
    <img src="https://img.youtube.com/vi/lQV5dmVWaIA/maxresdefault.jpg" alt="Hover demo — watch on YouTube" width="80%" />
  </a>
  <br/>
  <sub><b><a href="https://www.youtube.com/watch?v=lQV5dmVWaIA">▶ Watch the 2-minute demo</a></b></sub>
</p>

Hover drives your app once to explore, then crystallises the verified run into a deterministic spec. From there an optional **AI optimisation pass** polishes it — adding the success/error assertions the run actually observed, completing popup / download flows, flagging buggy behaviour with `// KNOWN BUG` — into a candidate you review by diff, with the deterministic original always kept.

**Bring your own CLI — subscription *or* API key.** Hover spawns the coding-agent CLI already on your `PATH` (`claude` / `codex` / …). Ride the subscription you already pay for, or drop your own model API key into the widget (it's passed to the CLI's environment, stored only in your browser, never uploaded). Either way the LLM cost is a one-off at authoring time — never a recurring tax on green builds, since the saved `.spec.ts` runs forever with `npx playwright test`, no agent in the loop.

## Why Hover

Several good tools exist here; Hover is what falls out when you optimise for **artifact portability**.

| Tool | What it does | The trade-off |
|---|---|---|
| **Playwright Codegen** | Records your clicks → `.spec.ts`. No AI | Can't think — replays literally |
| **Stagehand / Midscene** | AI-augmented tests; caches skip the LLM on steady-state runs. Needs an OpenAI / Anthropic key | Tests run **inside the vendor SDK** + cache file — not portable to a plain Playwright runner |
| **Hover** | AI drives the browser **once** to explore, saves a deterministic spec — with an optional AI pass that polishes it into a diff-reviewed candidate — *and* a Jira-importable case. **Spawns the CLI on your `PATH`** — subscription or your own API key | Crystallised spec is brittle to UI change — when it breaks, re-run the agent (no self-heal at CI time) |

Hover isn't trying to be the better *test-time* AI runtime. It makes the saved artifact plain `@playwright/test` code that runs with zero AI deps: the agent's job ends at "save", and CI is pure Playwright — **zero tokens, no key wired into CI**.

### Crystallise two ways

A single **💾 Save as ▾** on the done card crystallises one verified session two ways — every file checks into git, readable by teammates who never install Hover.

| | `📜 .spec.ts` | `📋 .case.csv` |
|---|---|---|
| **Lands in** | `__vibe_tests__/` | `__vibe_tests__/` |
| **Read by** | Node + Playwright (CI) | Xray · Zephyr · Jira |
| **Audience** | CI, devs | QA · PM |
| **Determinism** | Hard contract | Manual review |

<p align="center">
  <img src="docs/screenshots/05-save-dropdown.png" alt="Save dropdown — Playwright spec, Jira test case (CSV)" width="48%" />
  <img src="docs/screenshots/06-jira-case-modal.png" alt="Save as Jira case modal" width="48%" />
</p>

## What you get

- **Five bundler integrations** — Vite, Astro, Nuxt, Next.js (Turbopack), webpack 5; React Native Web rides on `vite-plugin-hover`. A Shadow-DOM widget injects into your dev page, is a no-op in production, and is marked `data-hover="true"` so your own Playwright runs skip it.
- **Your subscription or your API key** — spawns whichever coding-agent CLI is on your `PATH`, on the subscription you logged in with or a model API key you paste into the widget (kept in your browser, injected into the CLI's env, never uploaded

... (truncated)