> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/build/testdrive.md).

# TestDrive

Autonomous QA — AI agents exercise your real product in a browser, learn its flows, and prove each change delivers what was promised

**TestDrive is autonomous QA for your product.** Agents drive your real application in a real browser, learn how it works as they go, and tell you — with screenshots, video, and traces — whether the thing you shipped actually does what you said it would.

{% hint style="success" %}
**A pull request that proves itself**: A developer opens a PR against the checkout flow. TestDrive picks it up, signs into the preview deployment, walks the six acceptance tests that cover checkout, and posts a verdict with a video of the one that failed — before a human has looked at the diff.
{% endhint %}

## Who Is This For?

| You are…                 | TestDrive gives you…                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **An engineering team**  | Acceptance tests on every pull request, without writing and maintaining the whole suite by hand                          |
| **A product owner**      | Evidence that delivered work matches the spec, in plain language rather than test output                                 |
| **A QA engineer**        | Generated Playwright scripts you can read, edit, and keep, plus an agent that handles the flows you haven't scripted yet |
| **A support or CS lead** | A way to report a bug from Slack and get an investigated, reproducible answer back                                       |

## Key Benefits

| Benefit                       | What It Means                                                               | Business Impact                                            |
| ----------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **It tests the real thing**   | Runs against a live URL in a browser, signed in as a real user              | Catches what unit tests can't — the flow, not the function |
| **It learns your app**        | Every run records what it discovered about routes, flows, and behaviors     | Tests get faster and more accurate the longer you use it   |
| **It writes its own scripts** | Agent runs can be promoted into Playwright specs you own                    | A deterministic suite without the authoring cost           |
| **It brings evidence**        | Screenshots, video, traces, network and console logs on every failure       | Less time reproducing, more time fixing                    |
| **It starts from your spec**  | Generate acceptance tests from a Darcy Project spec or an uploaded document | Coverage that traces back to what was actually promised    |

## How TestDrive Works

```mermaid
flowchart TD
    A["Workspace<br/>points at your app"] --> B["Acceptance tests<br/>written, or generated from a spec"]
    B --> C{"Does the test<br/>have a script?"}
    C -->|No| D["Agent drives the browser<br/>and works it out"]
    C -->|Yes| E["Playwright script replays<br/>the known path"]
    D --> F["Run<br/>manual, PR, schedule, or webhook"]
    E --> F
    F --> G["Report<br/>verdict + evidence"]
    F --> H["Knowledge<br/>what it learned about the app"]
    H --> D
```

| Step                                   | What Happens                                                                                               |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **1. Point it at your app**            | A **workspace** holds one product: its URLs, its credentials, its tests, and everything it has learned     |
| **2. Describe what must keep working** | Each **acceptance test** is a goal and an expected outcome, written by you or generated from a spec        |
| **3. Let it figure out the how**       | With no script, the agent drives the browser itself. A successful path can be saved as a Playwright script |
| **4. Run it**                          | By hand, on every pull request, on a schedule, or from a webhook your CI fires                             |
| **5. Read the evidence**               | Each run produces a report: what passed, what failed, and the screenshots, video, and traces to prove it   |

## Core Concepts

| Term                | What it is                                                                                                            |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Workspace**       | One application under test, with its own URLs, credentials, tests, and knowledge                                      |
| **Application URL** | A named target to run against — production, staging, a preview — and the domains TestDrive may touch while testing it |
| **Acceptance test** | A goal and an expected outcome. The unit of "this must keep working"                                                  |
| **Script**          | A Playwright spec attached to a test, generated by Darcy or written by you                                            |
| **Run**             | One execution of a set of tests against one URL, producing a report and evidence                                      |
| **Knowledge**       | What TestDrive has learned about your app — its routes, flows, elements, and quirks                                   |

## Getting Started

{% stepper %}
{% step %}
**Create a workspace** Open **TestDrive** from the navigation and click **Create your first workspace**. Name it after the product it will test.
{% endstep %}

{% step %}
**Follow the setup guide** New workspaces open a setup guide that walks the rest: application URLs, an optional linked Project, credentials, Slack triage, MCP, and your first test. Only the first is required.
{% endstep %}

{% step %}
**Add an application URL** Point at the environment you want tested and list the domains TestDrive is allowed to reach while it's there. See [Workspaces & Application URLs](/build/testdrive/workspaces-and-urls.md).
{% endstep %}

{% step %}
**Give it a way in** If your app needs a login, add a credential. TestDrive learns the sign-in once and replays it. See [Credentials & Sign-In](/build/testdrive/credentials-and-sign-in.md).
{% endstep %}

{% step %}
**Write one test** Describe a single thing that must keep working — "a signed-in user can add an item to the cart and check out." See [Tests & Scripts](/build/testdrive/tests-and-scripts.md).
{% endstep %}

{% step %}
**Run it** Start a manual run, read the report, and then decide what should trigger it automatically. See [Running Tests](/build/testdrive/running-tests.md).
{% endstep %}
{% endstepper %}

## Availability

TestDrive is enabled per organization and per plan, and opening it needs TestDrive permission. If it isn't in your navigation, it isn't turned on for your account — talk to your administrator.

## Next Steps

| Goal                                      | Documentation                                                            |
| ----------------------------------------- | ------------------------------------------------------------------------ |
| Set up the workspace and its targets      | [Workspaces & Application URLs](/build/testdrive/workspaces-and-urls.md) |
| Let TestDrive sign in as a real user      | [Credentials & Sign-In](/build/testdrive/credentials-and-sign-in.md)     |
| Write tests, or generate them from a spec | [Tests & Scripts](/build/testdrive/tests-and-scripts.md)                 |
| Run on PRs, schedules, and webhooks       | [Running Tests](/build/testdrive/running-tests.md)                       |
| Read a report and its evidence            | [Results & Evidence](/build/testdrive/results-and-evidence.md)           |
| Understand what TestDrive has learned     | [Application Knowledge](/build/testdrive/app-knowledge.md)               |
| Use it from chat, Slack, and your editor  | [TestDrive with Darcy](/build/testdrive/testdrive-with-darcy.md)         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.darcyiq.com/build/testdrive.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.