# Windup

> 自然语言 E2E 测试，确定性回放 —— LLM 只规划一次，回放无需它参与。每次回放 ~1s、$0。

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

- [快速开始](https://windup.run/zh/docs/getting-started.md): 安装 Windup，初始化项目，用五条命令从一句粗略的指令走到一个可确定性回放的测试。
- [工作原理](https://windup.run/zh/docs/how-it-works.md): LLM 把一个场景规划一次，产出经过 schema 校验的 JSON；确定性执行器以零 LLM 调用和廉价的 DOM 验证进行回放。
- [测试场景](https://windup.run/zh/docs/scenarios.md): 一个场景就是一个用纯自然语言描述测试的 JSON 文件。了解其格式、场景依赖，以及用 windup new 进行 LLM 辅助编写。
- [测试凭据](https://windup.run/zh/docs/credentials.md): 凭据从不存在于场景、计划、缓存或 git 中 —— 只有引用。值留在 .env.local 或 CI 密钥中，在运行时解析。
- [环境](https://windup.run/zh/docs/environments.md): 在 dev、staging 和 CI 中运行相同的场景。计划缓存可跨环境移植 —— 以 URL 路径为键，而非主机。
- [LLM 提供商](https://windup.run/zh/docs/llm-providers.md): 规划器与提供商无关。同时配置 Google Gemini 和 OpenAI，按次运行选择其一 —— 切换从不使计划缓存失效。
- [CI / CD](https://windup.run/zh/docs/ci-cd.md): 在一个热浏览器中运行整个套件，任何场景失败都让构建失败，并产出 JUnit、JSON 或自包含的 HTML 报告。
- [配置](https://windup.run/zh/docs/configuration.md): windup.config.ts 参考 —— base URL、LLM 提供商、扫描设置，以及把团队知识注入规划器的项目清单。
- [编程式 API](https://windup.run/zh/docs/api.md): 用编程式 API 从代码中运行场景，或通过兼容 jest 的适配器把 Windup 接入 vitest。
- [命令](https://windup.run/zh/docs/commands.md): 完整的 Windup CLI 参考 —— 每条命令、run 的各个标志，以及可选启用的 AI 复盘（--summary）和修复建议（--suggest）辅助功能。
- [架构与规范](https://windup.run/zh/docs/architecture.md): 活文档 —— Windup 确定性回放背后的论点、原则、模块边界、数据格式，以及成本与安全态势。
- [工程说明](https://windup.run/zh/docs/techniques.md): 让自然语言测试既确定又廉价的那些技术 —— 规划一次的回放、自愈缓存、结构签名等等。

## Optional

- [Full documentation as one file](https://windup.run/zh/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)