# Windup

> Pruebas E2E en lenguaje natural con replay determinista — el LLM planifica una vez, los replays se ejecutan sin él. ~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

- [Primeros pasos](https://windup.run/es/docs/getting-started.md): Instala Windup, inicializa un proyecto y pasa de una instrucción imprecisa a una prueba con replay determinista en cinco comandos.
- [Cómo funciona](https://windup.run/es/docs/how-it-works.md): El LLM planifica un escenario una vez en JSON validado por esquema; un ejecutor determinista lo reproduce con cero llamadas al LLM y verificación barata de DOM.
- [Escenarios](https://windup.run/es/docs/scenarios.md): Un escenario es un archivo JSON que describe una prueba en lenguaje natural. Aprende el formato, las dependencias entre escenarios y la autoría asistida por LLM con windup new.
- [Credenciales de prueba](https://windup.run/es/docs/credentials.md): Las credenciales nunca viven en escenarios, planes, la caché ni git — solo referencias. Los valores permanecen en .env.local o en secretos de CI, resueltos en tiempo de ejecución.
- [Entornos](https://windup.run/es/docs/environments.md): Ejecuta los mismos escenarios en dev, staging y CI. La caché de planes es portable entre entornos — indexada por la ruta de la URL, no por el host.
- [Proveedores de LLM](https://windup.run/es/docs/llm-providers.md): El planificador es agnóstico al proveedor. Configura Google Gemini y OpenAI a la vez y elige uno por ejecución — cambiar nunca invalida la caché de planes.
- [CI / CD](https://windup.run/es/docs/ci-cd.md): Ejecuta toda la suite en un navegador caliente, haz fallar el build ante cualquier escenario fallido y emite informes JUnit, JSON o HTML autocontenido.
- [Configuración](https://windup.run/es/docs/configuration.md): La referencia de windup.config.ts — base URL, proveedores de LLM, ajustes de scan y el manifiesto del proyecto que inyecta el conocimiento del equipo en el planificador.
- [API programática](https://windup.run/es/docs/api.md): Ejecuta escenarios desde código con la API programática, o integra Windup en vitest con el adaptador compatible con jest.
- [Comandos](https://windup.run/es/docs/commands.md): La referencia completa de la CLI de Windup — cada comando, los flags de run y los ayudantes opcionales de informe de IA (--summary) y sugerencia de corrección (--suggest).
- [Arquitectura y especificación](https://windup.run/es/docs/architecture.md): La especificación viva — tesis, principios, límites de módulos, formatos de datos y la postura de coste y seguridad detrás del replay determinista de Windup.
- [Notas de ingeniería](https://windup.run/es/docs/techniques.md): Las técnicas que hacen que las pruebas en lenguaje natural sean deterministas y baratas — replay de plan único, caché autorreparable, firmas estructurales y más.

## Optional

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