# Docs

- Documentation: Guides and concepts

  - **Get started**
  - [Introduction](/docs): danwo is an end-to-end testing framework for web and mobile apps. Test the UI, and add the backend when you need it.
  - [Quickstart](/docs/quickstart): Set danwo up in your project, write a UI test, run it, and watch it in the dashboard.
  - [What you can test](/docs/what-you-can-test): From a log-in to a payment charged exactly once, which of danwo's layers each kind of test needs.
  - [Why danwo](/docs/why-danwo): danwo does everything you expect of an end-to-end test, then checks what the button did behind the screen.
  - [Test a provider](/docs/test-a-provider): Pay through Stripe in a test, check the charge happened exactly once, then try to break it.

  - **Coding agents**
  - [Overview](/docs/coding-agents): Your coding agent can write danwo tests, run them, read why they failed and fix the cause, through danwo's skill and MCP server.
  - [Set up your agent](/docs/agent-setup): Which files danwo writes for each coding agent, and how to add the skill and MCP server by hand.
  - [MCP tools](/docs/mcp-tools): Every tool, resource and prompt danwo's MCP server gives a coding agent, and what each is for.
  - [Fix a failure](/docs/fix-with-an-agent): Hand a failing test to your coding agent with its failure page, and get back a fix it has checked with danwo.

  - **Where danwo runs**
  - [Overview](/docs/where-danwo-runs): What danwo can emulate and break depends on where your app runs. One rule decides it.
  - [Full-stack app](/docs/full-stack-local): One app that serves both pages and API, started by danwo. Everything works.
  - [Frontend and backend](/docs/frontend-and-backend): A frontend and an API in separate apps, both started by danwo behind one proxy.
  - [Frontend only](/docs/frontend-only): You run the frontend; the API runs somewhere else. danwo covers the browser's side.
  - [Staging](/docs/staging): Test the real deployment, with your providers' real sandboxes, before you release.
  - [Production](/docs/production): A short smoke test after each deploy, with a dedicated test account. Never the matrix.
  - [Which should I use?](/docs/which-setup): A few questions to find your setup, and which one to use for each purpose.

  - **Core concepts**
  - [Agent and locators](/docs/agent-and-locators): Two ways to write a step. Locators name an element exactly; the agent takes a plain-English instruction. Use both in one test.
  - [Agent steps](/docs/agent-steps): The agent's four calls, act, assert, extract and waitFor, with examples, parameters and limits.
  - [Replay cache](/docs/replay-cache): Agent steps are recorded the first time they pass and replayed after that, with no model calls.
  - [Emulators](/docs/emulators): Local stand-ins for the services your app calls, answering on the real hostnames behind danwo's proxy, with no change to your code.
  - [Seeding and state](/docs/emulator-state): Start an emulator with the data your test needs, and read back what your app did at it.
  - [Isolation](/docs/isolation): Every test, and every retry, starts from the same seeded state, so no test depends on another one.
  - [Flight records](/docs/flight-records): Every run keeps a record of what happened, on the screen and behind it, so you can replay a test without running it again.

  - **Fault matrix**
  - [Overview](/docs/fault-matrix): Replay one test under every fault it could meet, and check your app coped with each one.
  - [Writing invariants](/docs/invariants): An invariant is the rule the fault matrix checks after every trial. Write one by comparing your app with the provider.
  - [Running it](/docs/run-the-matrix): Run the fault matrix on a test, a chosen set of faults, or a single fault.
  - [Reading results](/docs/matrix-results): Find the failed trials in the dashboard, and see what each fault did to your app.
  - [Planning and budget](/docs/matrix-planning): How danwo picks which faults to run, how to preview the plan, and how to run more or fewer.
  - [Fault kinds](/docs/fault-kinds): Every kind of fault the matrix can inject, what it simulates, and what it catches.
  - [Common findings](/docs/common-findings): The bugs the fault matrix finds most often, what each looks like, and how to fix it.

  - **Real stacks**
  - [When you need it](/docs/real-stacks): Test an app that is more than one process, a frontend, an API and a worker, with every outside call emulated.
  - [Several apps](/docs/stack-environment): Start a frontend, an API and workers together with stackEnvironment, in order, wired to each other, behind one proxy.
  - [Background jobs](/docs/background-jobs): Route your app's Inngest events through danwo, wait for the runs they start, and fault the sends.
  - [WebSockets and SSE](/docs/sockets-and-streams): Live updates over WebSockets and server-sent events go through danwo's proxy, are recorded, and can be broken on purpose.
  - [Outside hosts](/docs/outside-hosts): Decide what happens to calls no emulator answers, keep analytics out of your runs, and catch live keys before they leak.
  - [The Node preload](/docs/node-preload): How danwo routes a Node app's calls through its proxy without code changes, and what to do when a start script gets in the way.
  - [Processes](/docs/processes): danwo stops everything it starts, when a run passes, fails, is interrupted or is killed. Here's how, and what your app should do.
  - [Databases](/docs/stack-databases): Put your app's Postgres and Redis behind danwo, so every test starts from clean data and the matrix can fault the statements.
  - [Your app's data](/docs/app-data): Read and seed your app's own database from a test, so invariants check what was saved and not only what the screen showed.
  - [A worked example](/docs/stack-example): A frontend, an API and a background worker, started together, tested end to end, then broken with the fault matrix.

  - **Writing tests**
  - [Visual comparison](/docs/visual-comparison): Compare the page, or one element, with a baseline image, on web, Android and iOS. Mask what changes, set how strict, update baselines.
  - [TypeScript in tests](/docs/typescript): What test and config files may contain, since danwo runs them with Node's own type stripping.
  - [Secrets](/docs/secrets): Configure passwords, keys and codes by name. Tests and the agent use the name; the value never reaches the model, a record or a report.
  - [Email and 2FA codes](/docs/email-and-otp): Read sign-in codes and magic links from the mail your app sent, type authenticator codes, and replay it all with no model.
  - [Saved sessions](/docs/sessions): Sign in once per worker, and start every test that needs it already signed in.
  - [A second person](/docs/two-people): Open another user's browser in the same test, for chat, sharing and anything one person sees another do.
  - [Time travel](/docs/time-travel): Jump days ahead in a test, so trials end, subscriptions renew, retries run and tokens expire in seconds.
  - [Database and cache](/docs/data-faults): Put a fault proxy in front of your own Postgres and Redis, and let the matrix break the calls your tests make.
  - [Integration lint](/docs/integration-lint): Every run is checked for risky provider usage, from the calls and webhooks danwo already saw, with nothing to write.
  - [Debugging a failure](/docs/debugging): Read a failed run's page from top to bottom, and know what each error code asks you to look at.

  - **Platforms**
  - [Web](/docs/web): danwo drives your web app in a real Chromium browser, behind its proxy, with locators, an agent and a recording of every test.
  - [Android setup](/docs/mobile): Get this machine ready to test a React Native or Expo app on an Android emulator with danwo.
  - [Android builds](/docs/android-build): Build an Expo app as a release APK that trusts danwo's proxy, and reuse it until its sources change.
  - [Android tests](/docs/android-tests): Bind an emulator to the run, then write the same locators, checks, agent steps and invariants as on the web.
  - [Parallel emulators](/docs/parallel-emulators): Give each worker its own Android emulator, sized to what this machine can run.
  - [iOS setup](/docs/ios-setup): Get a Mac ready to test a React Native or Expo app on an iOS Simulator with danwo.
  - [iOS builds](/docs/ios-build): Build an Expo app as a Release iOS Simulator app, and reuse it until its sources change.
  - [iOS tests](/docs/ios-tests): Bind an iOS Simulator to the run, then run the same tests, agent steps, invariants and matrix as on Android.
  - [Playwright Test](/docs/playwright): Keep your Playwright tests and add danwo's emulators, invariants and fault matrix to them.

  - **Running**
  - [CI and GitHub](/docs/ci): Run danwo in GitHub Actions and get a check on every pull request, with each failing line annotated.
  - [Pull request comment](/docs/pr-comment): One comment on each pull request, edited by every run, with each test, each failure and what the matrix found.
  - [Shards and JUnit](/docs/shards): Split a big suite across machines, join the results, and report to any CI with JUnit.
  - [Dashboard](/docs/dashboard): Browse every run on your machine, see which tests break under which faults, and open any recording.
  - [Recordings](/docs/recordings): Every test's flight record in the dashboard, its video, steps, console, network and every provider call, and a prompt to fix it.
  - [Reading failures](/docs/reading-failures): Every failed test gets a verdict that says whose failure it was, the app's, the test's, the environment's or danwo's, and the evidence behind it.
  - [Live runs and reruns](/docs/live-runs): Watch tests and matrix trials stream into the dashboard as they run, and start, rerun or cancel runs from the page.
  - [Changed tests](/docs/impact): Run only the tests a change can affect, and see why each one was picked.
  - [Fidelity](/docs/fidelity): Check that each emulator answers like the real provider, against the provider's own sandbox.
  - [Fidelity test accounts](/docs/fidelity-accounts): Sign a test account in once, so the Gmail, Calendar, Drive and Microsoft Graph fidelity suites can run against the real APIs.
  - [Cleaning up sandboxes](/docs/fidelity-cleanup): How a live fidelity run tags what it makes, undoes it after each scenario, and sweeps up anything left behind.
  - [Configuration](/docs/configuration): A tour of danwo.config.ts, grouped by what each option is for.

  - **For coding agents**
  - [Guides for agents](/docs/for-coding-agents): danwo's guides for coding agents: the same knowledge as these docs, written densely, as raw markdown.
- Providers: The APIs danwo emulates

  - **Overview**
  - [Providers](/docs/providers): The third-party APIs danwo emulates, how to add one to your config, seed it and read what it saw.

  - **Payments**
  - [Stripe](/docs/providers/stripe): Customers, products and prices, payment intents, refunds and Checkout with its hosted page, plus Stripe's signed webhooks.
  - [Stripe billing](/docs/providers/stripe-billing): Subscriptions, setup intents, invoices and the billing portal, renewing on the emulator's clock so a test can jump a month ahead.
  - [Stripe.js and cards](/docs/providers/stripe-js): A stand-in for Stripe.js on js.stripe.com, with card fields a test can fill and Stripe's test cards deciding each outcome.
  - [Paystack](/docs/providers/paystack): Transactions paid on Paystack's hosted page with its test cards, bank transfer or USSD, plus plans, transfers, refunds and signed events.
  - [Flutterwave](/docs/providers/flutterwave): Flutterwave's v3 API with its hosted checkout, test cards, refunds, payment plans, transfers and virtual accounts.
  - [Bachs](/docs/providers/bachs): Bachs checkout sessions, subscriptions, card recovery, refunds and payouts on its sandbox and live hosts, settling on the emulator's clock.

  - **Email and messaging**
  - [Resend](/docs/providers/resend): Sending email, batches and scheduled sends, domains, API keys and signed webhooks on api.resend.com, with every message readable from a test.
  - [Twilio](/docs/providers/twilio): Text messages with status callbacks, texts to your app's numbers, Verify codes and the limits of a trial account.
  - [Slack](/docs/providers/slack): Slack app installs through OAuth, the Web API with its scope checks, incoming webhooks, and signed events, slash commands and interactions sent to your app.

  - **Identity**
  - [Google](/docs/providers/google): Sign in with Google on accounts.google.com, with seeded accounts, OAuth clients, tokens that refresh and access a user can revoke mid-test.
  - [Gmail, Calendar, Drive](/docs/providers/google-workspace): Gmail, Google Calendar and Google Drive for a signed-in user, with push notifications and history that a test can expire.
  - [Microsoft](/docs/providers/microsoft): Sign in with Microsoft, then Microsoft Graph's Outlook mail, calendars, OneDrive and change notifications for each seeded user.
  - [GitHub](/docs/providers/github): Sign in with GitHub, GitHub Apps and their installations, the REST API for repositories, issues, pull requests and checks, and signed webhooks.
  - [Auth0](/docs/providers/auth0): Auth0's Universal Login with sign-up, MFA and social connections, the authentication API's grants, and the Management API v2, on your tenant's own domain.
  - [Clerk](/docs/providers/clerk): A Clerk development instance on its real hosts, with the Backend API, the Frontend API serving ClerkJS and its sign-in components, the Account Portal, stable ids and Svix-signed webhooks.

  - **Storage**
  - [S3 and Tigris](/docs/providers/s3): S3 object storage for apps on AWS S3 or Tigris, with the AWS SDK and the Tigris SDK, presigned URLs, multipart uploads and signature checks.

  - **AI**
  - [Model APIs](/docs/providers/model-apis): The model APIs your app calls, OpenAI, Anthropic, the Vercel AI Gateway, Gemini, Perplexity and Bedrock, answered from scripts, with token counts and cost a test can check.
  - [Scripting replies](/docs/providers/model-scripts): Script what the model answers your app, text, tool calls, structured output or a refusal, matched by prompt, model, provider or tool, and change it mid-test.
  - [More model APIs](/docs/providers/model-providers): Gemini, Perplexity and Amazon Bedrock, answered from the same scripts as OpenAI and Anthropic, each in its own wire format.
  - [Composio](/docs/providers/composio): Composio's toolkits, tool execution, connected accounts with hosted connect links, and triggers, with tools that act on danwo's Google, Slack, GitHub and Microsoft emulators.

  - **Connectors**
  - [Nylas](/docs/providers/nylas): Nylas v3 hosted auth and grants, email, calendars and events, contacts and the scheduler, with signed webhooks and mail a test can deliver.
  - [Nango](/docs/providers/nango): Nango integrations, connect sessions with the hosted Connect UI, connections whose tokens refresh, the proxy, actions and records, routed to danwo's other emulators.
  - [Unipile](/docs/providers/unipile): Unipile's hosted auth links, connected LinkedIn, WhatsApp and mail accounts, chats, messages and email, with webhooks when the other side writes back.

  - **Realtime**
  - [Pusher](/docs/providers/pusher): Pusher Channels, the API your server triggers events on and the socket pusher-js keeps open, with private and presence channels, subscription counting, signed webhooks and Beams.
  - [Novu](/docs/providers/novu): Novu's server API, workflows run through your app's bridge or from seeded templates, the Inbox API and socket the browser uses, and emails sent through the Resend emulator.
  - [Tiptap](/docs/providers/tiptap): Tiptap Cloud collaboration, the socket editors sync documents over and the documents REST API, with a test that reads what a document says and makes the server misbehave.

  - **Infrastructure**
  - [AWS through MiniStack](/docs/providers/aws): Every other AWS service your app calls, from SQS to DynamoDB, forwarded by danwo's proxy to MiniStack, a local AWS emulator, with resets, recording and faults on top.
- Reference: API, config and CLI

  - **Overview**
  - [Reference](/docs/reference): Every part of danwo's API, config and CLI, generated from the code with danwo spec.

  - **Test API**
  - [test](/docs/reference/test): Declares tests, their invariants, saved sessions and fresh values; what a *.danwo.ts file is built from.
  - [Fixtures](/docs/reference/fixtures): What test bodies receive: the app, the screen and each provider's handle, added with test.extend.
  - [screen and Locator](/docs/reference/screen): Finding elements the way a user names them, acting on them, and the app and mail handles beside them.
  - [expect](/docs/reference/expect): Assertions on locators and pages that wait until they hold or time out.
  - [agent](/docs/reference/agent): Plain-English steps: act, assert, extract and waitFor, verified and cached for replay.
  - [Secrets](/docs/reference/secrets): Configured secrets, filled by name so the model never sees their values.

  - **Project**
  - [Config](/docs/reference/config): danwo.config.ts: defineConfig and every option.
  - [CLI](/docs/reference/cli): Every danwo command and its options.
  - [Environments](/docs/reference/environments): Starting the app and the emulators a worker's tests run against.
  - [Errors](/docs/reference/errors): Every error code a run reports, and what to do about it.
  - [Cache outcomes](/docs/reference/cache): What the replay cache did with each recorded step.
  - [Every export](/docs/reference/exports): Every name @danwo/sdk exports, with its kind and what it is: one list to search.

  - **Matrix and lint**
  - [Faults](/docs/reference/faults): The fault vocabulary danwo matrix plans from.
  - [Lint rules](/docs/reference/lint-rules): Every integration lint rule.

  - **Providers**
  - [Emulator helpers](/docs/reference/emulator-helpers): Reading what the app did at a provider, or acting as a provider's user.
- Examples: Projects to run

  - **Examples**
  - [Example projects](/docs/examples): Small apps with a real backend and emulated providers, each tested end to end by danwo with no real keys.
  - [AI chat with tools](/docs/examples/ai-chat): A support assistant on Next.js and the AI SDK: it streams answers through the Vercel AI Gateway, looks orders up and opens tickets in Postgres, and emails a copy through Resend, tested against scripted and faulted model answers with no model key.
  - [Login with Better Auth](/docs/examples/better-auth): Self-hosted sign-in with Better Auth: a Vite and React app on a Hono API and Postgres, with emailed codes through Resend, Google and GitHub sign-in, a password with a confirmed email, linked accounts and signed-in devices.
  - [Login with Clerk](/docs/examples/clerk-login): Signing in with Clerk on Next.js: Clerk's own components for sign-up and sign-in by emailed code or Google, organizations and invitations, and the app's users in Postgres from Clerk's webhooks.
  - [Commerce](/docs/examples/commerce): A small shop selling mugs, notebooks and prints: a Next.js storefront and admin, a Hono API on Postgres, and Stripe Checkout, Resend receipts and S3 pictures.
  - [Background jobs](/docs/examples/jobs): A team digest sent by background jobs on Inngest: a React page, a Hono API on Postgres, and a worker whose cron, fan-out, retries and onFailure send through Resend and bill through Stripe.
  - [SaaS with integrations](/docs/examples/saas): Relay, a team-notes app: workspaces on Clerk organizations, a Stripe trial and billing, Slack and Google Calendar connected by OAuth, live notes over Pusher, and Inngest jobs that send email through Resend.
  - [Next.js waitlist](/docs/examples/with-next): A waitlist on Next.js: the form saves an email to Postgres and sends a welcome email through Resend.
  - [Shop](/docs/examples/shop): A small app that sells credits through Stripe Checkout; danwo tests itself against it.
  - [Shop on Android and iOS](/docs/examples/shop-mobile): An Expo app that buys credits through Stripe Checkout in a Custom Tab or a Safari view; danwo tests it on an Android emulator or an iOS Simulator.
  - [Shop with Playwright](/docs/examples/shop-playwright): The shop's purchase test written for Playwright Test, with danwo's emulators, invariant and fault matrix.

## Guides for coding agents

- [CI, the GitHub check and the pull request comment](/guides/ci.md)
- [The dashboard](/guides/dashboard.md)
- [Debugging a failure](/guides/debugging.md)
- [Email codes, magic links and 2FA](/guides/email-and-otp.md)
- [Checking the emulators against the real providers](/guides/fidelity.md)
- [Writing a first test](/guides/first-test.md)
- [Faults in the app's own database and cache](/guides/infrastructure.md)
- [Integration lint](/guides/lint.md)
- [Testing an app that calls a model](/guides/llm.md)
- [Locators or the agent](/guides/locators-vs-agent.md)
- [Invariants and the fault matrix](/guides/matrix.md)
- [Mobile apps on Android and iOS](/guides/mobile.md)
- [Using danwo from Playwright Test](/guides/playwright.md)
- [Emulating a provider](/guides/providers.md)
- [Secrets](/guides/secrets.md)
- [Saved sessions](/guides/sessions.md)
- [Time travel](/guides/time.md)