# Windup

> Natural-language E2E tests with deterministic replay — the LLM plans once, replays run without it. ~1s, $0 per replay.

Windup turns a plain-language task into a schema-validated JSON action plan, executes it deterministically with cheap DOM/URL verification after every step, and caches the trajectory. The second run replays the cached plan with no model calls. When the app changes and a verification fails, the plan is invalidated and re-planned automatically — you edit scenarios, not selectors.

Fast facts for driving the tool:
- Install: `npm i -D windupjs` (Chromium auto-provisioned). Requires Node >= 20 and one API key in `.env.local`: `GOOGLE_GENERATIVE_AI_API_KEY` (Google, default) or `OPENAI_API_KEY` (OpenAI). Keys are used only for planning; cached replays never call an LLM.
- Initialize a project: `npx windup init`. Index the app's routes/elements from source: `npx windup scan`.
- Author a test: `npx windup new "<plain-language instruction>"` → writes a scenario JSON in `e2e/scenarios/`. Add `--validate` to run and refine it until it passes.
- Run: `npx windup run <scenario_id>` (first run plans, later runs replay at $0). Whole suite for CI: `npx windup run --all --reporter junit` (non-zero exit on failure).
- A scenario is JSON: `{ "scenario_id", "start_url"?, "task", "hints"?, "depends_on"? }`. End the `task` with what to verify — it becomes the final postcondition. Never put secrets in tasks; reference named accounts (`windup secret set <account>`), plans use `value_ref: "ENV:VAR"` resolved at runtime.

## Documentation

- [Getting started](https://windup.run/docs/getting-started.md): Install Windup, initialize a project, and go from a rough instruction to a deterministic replaying test in five commands.
- [How it works](https://windup.run/docs/how-it-works.md): The LLM plans a scenario once into schema-validated JSON; a deterministic executor replays it with zero LLM calls and cheap DOM verification.
- [Scenarios](https://windup.run/docs/scenarios.md): A scenario is a JSON file describing a test in plain language. Learn the format, scenario dependencies, and LLM-assisted authoring with windup new.
- [Test credentials](https://windup.run/docs/credentials.md): Credentials never live in scenarios, plans, the cache or git — only references. Values stay in .env.local or CI secrets, resolved at runtime.
- [Environments](https://windup.run/docs/environments.md): Run the same scenarios across dev, staging and CI. The plan cache is environment-portable — keyed by URL path, not host.
- [LLM providers](https://windup.run/docs/llm-providers.md): The planner is provider-agnostic. Configure Google Gemini and OpenAI at once and pick one per run — switching never invalidates the plan cache.
- [CI / CD](https://windup.run/docs/ci-cd.md): Run the whole suite in one warm browser, fail the build on any failing scenario, and emit JUnit, JSON or self-contained HTML reports.
- [Configuration](https://windup.run/docs/configuration.md): The windup.config.ts reference — base URL, LLM providers, scan settings, and the project manifest that injects team knowledge into the planner.
- [Programmatic API](https://windup.run/docs/api.md): Run scenarios from code with the programmatic API, or plug Windup into vitest with the jest-compatible adapter.
- [Commands](https://windup.run/docs/commands.md): The full Windup CLI reference — every command, the run flags, and the opt-in AI debrief (--summary) and fix-suggestion (--suggest) helpers.
- [Architecture & spec](https://windup.run/docs/architecture.md): The living specification — thesis, principles, module boundaries, data formats, and cost & security posture behind Windup's deterministic replay.
- [Engineering notes](https://windup.run/docs/techniques.md): The techniques that make natural-language tests deterministic and cheap — plan-once replay, self-healing cache, structural signatures, and more.

## Optional

- [Full documentation as one file](https://windup.run/llms-full.txt): every page above concatenated as markdown for single-fetch ingestion
- [GitHub repository](https://github.com/windupjs/windup): source, issues, MIT license
- [npm package](https://www.npmjs.com/package/windupjs)
- [Technical specification (SPEC.md)](https://github.com/windupjs/windup/blob/main/docs/specs/SPEC.md)