# Windup

> Testes E2E em linguagem natural com replay determinístico — o LLM planeja uma vez, os replays rodam sem ele. ~1s, $0 por 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

- [Primeiros passos](https://windup.run/pt/docs/getting-started.md): Instale o Windup, inicialize um projeto e vá de uma instrução vaga a um teste determinístico com replay em cinco comandos.
- [Como funciona](https://windup.run/pt/docs/how-it-works.md): O LLM planeja um cenário uma vez em JSON validado por schema; um executor determinístico faz replay com zero chamadas ao LLM e verificação barata de DOM.
- [Cenários](https://windup.run/pt/docs/scenarios.md): Um cenário é um arquivo JSON que descreve um teste em linguagem simples. Aprenda o formato, as dependências entre cenários e a autoria assistida por LLM com windup new.
- [Credenciais de teste](https://windup.run/pt/docs/credentials.md): Credenciais nunca ficam em cenários, planos, no cache ou no git — apenas referências. Os valores ficam em .env.local ou nos secrets de CI, resolvidos em tempo de execução.
- [Ambientes](https://windup.run/pt/docs/environments.md): Rode os mesmos cenários em dev, staging e CI. O cache de planos é portável entre ambientes — indexado pelo caminho da URL, não pelo host.
- [Provedores de LLM](https://windup.run/pt/docs/llm-providers.md): O planejador é agnóstico de provedor. Configure Google Gemini e OpenAI ao mesmo tempo e escolha um por execução — trocar nunca invalida o cache de planos.
- [CI / CD](https://windup.run/pt/docs/ci-cd.md): Rode a suíte inteira em um navegador aquecido, faça o build falhar em qualquer cenário que falhar e gere relatórios JUnit, JSON ou HTML autocontido.
- [Configuração](https://windup.run/pt/docs/configuration.md): A referência do windup.config.ts — base URL, provedores de LLM, configurações de scan e o manifesto do projeto que injeta conhecimento da equipe no planejador.
- [API programática](https://windup.run/pt/docs/api.md): Rode cenários a partir de código com a API programática, ou integre o Windup ao vitest com o adaptador compatível com jest.
- [Comandos](https://windup.run/pt/docs/commands.md): A referência completa da CLI do Windup — cada comando, as flags do run e os auxiliares opcionais de resumo por IA (--summary) e sugestão de correção (--suggest).
- [Arquitetura e especificação](https://windup.run/pt/docs/architecture.md): A especificação viva — tese, princípios, fronteiras entre módulos, formatos de dados e a postura de custo e segurança por trás do replay determinístico do Windup.
- [Notas de engenharia](https://windup.run/pt/docs/techniques.md): As técnicas que tornam testes em linguagem natural determinísticos e baratos — replay planejado uma vez, cache autorreparável, assinaturas estruturais e mais.

## Optional

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