> 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/tests-and-scripts.md). # Tests & Scripts Write acceptance tests by hand or generate them from a spec, then let Darcy turn the ones that work into Playwright scripts An **acceptance test** is one thing that must keep working, written as a goal and an expected outcome. A **script** is the Playwright spec that replays it deterministically once the path is known. The two are deliberately separate. A test without a script still runs — the agent drives the browser and works it out. A test with a script runs the same way every time, in a fraction of the time. ## Writing a Test | Field | What to put in it | | -------------------- | --------------------------------------------------------------------------- | | **Name** | What it covers, in a few words | | **Goal** | What the user is trying to do — "sign in and download last month's invoice" | | **Expected outcome** | How you know it worked — "the PDF downloads and shows the correct total" | | **Credential** | Which identity to run as, or signed out | | **Application URL** | A specific target, or the workspace default | Under **Advanced**: | Field | What to put in it | | ----------------- | ---------------------------------------------------------------------------------- | | **Preconditions** | State the test assumes — "the account has at least one paid invoice" | | **Tags** | How schedules and triggers select groups of tests — `smoke`, `checkout`, `billing` | | **Tests** | **The interface — drives a browser**, or **The API — issues HTTP requests** | {% hint style="success" %} **Write the outcome the way you'd tell a colleague.** "The order confirmation shows the discounted total, not the list price" gives the agent something to verify. "Checkout works" doesn't. {% endhint %} ## Generating Tests From What You Already Wrote Nobody enjoys writing an acceptance suite from a blank page, and you usually don't have to — the promises are already written down somewhere. | Source | How it works | | ------------- | ------------------------------------------------------------------------------- | | **From Spec** | Reads the spec of the workspace's linked Darcy Project and drafts tests from it | | **From Doc** | Takes a `.txt` or `.md` document you upload or paste, up to 200,000 characters | Both produce **drafts** that arrive **disabled**, marked as generated, and waiting for you. That's on purpose: a generated test is a proposal about what matters, and you're the one who knows whether it does. Read them, fix the ones that are close, delete the ones that aren't, then approve and enable what's left. ## Approval and Enablement Two separate switches, and the distinction matters: | State | Meaning | | ------------------------------- | ---------------------------------------------------------------------- | | **Draft / Approved / Rejected** | Whether the test is agreed to be a correct statement of what must work | | **Enabled / Disabled** | Whether it participates in runs right now | Only tests that are **approved and enabled** are picked up by manual runs, schedules, and triggers. Disabling is how you park a test through a known-broken period without arguing about whether to delete it. The Tests tab filters by approval state, by source (manual, generated, or Slack), and by tag, and supports bulk **Approve**, **Enable**, **Disable**, **Build scripts**, **Run**, and **Export scripts**. ## Scripts A script is a Playwright spec attached to a test. Darcy can write it for you — **Generate with Darcy** on a test with no script, or **Build scripts** across a selection — and you can edit it or paste in your own. | Status | What it means | | -------------- | ----------------------------------------------------------------- | | **No script** | The agent drives the browser live each time | | **Generating** | Darcy is building it now | | **Ready** | Built and proven by a passing run | | **Unverified** | Saved but never run. A passing run marks it ready | | **Broken** | It ran and failed in a way that points at the script, not the app | Building a script queues a run of its own, tagged **script build**, because the only way to write a reliable script is to drive the real application while writing it. {% hint style="info" %} **Ready and unverified both run.** A new or hand-edited script doesn't sit on the bench waiting for a blessing — it's eligible for manual runs, schedules, and triggers, and the first passing run promotes it to ready. {% endhint %} Scripts are yours: **Export scripts** downloads the specs for the tests you've selected, so the suite TestDrive built for you can live in your repository too. ## When the App Breaks Versus When the Script Does A failing test isn't automatically a bug in your product. TestDrive distinguishes a test that failed because the application misbehaved from one that failed because the script no longer matches the interface — the second marks the script **broken** and asks to be rebuilt rather than filing the app as guilty. [Results & Evidence](/build/testdrive/results-and-evidence.md) covers how to read that verdict. ## Slack Triage Candidates Tests reported through Slack arrive as **triage candidates**: read-only, held apart from the ordinary suite, and not run with it until the reporter promotes them. See [TestDrive with Darcy](/build/testdrive/testdrive-with-darcy.md). ## Next Steps | Goal | Documentation | | ---------------------------------- | ---------------------------------------------------------------- | | Run what you've written | [Running Tests](/build/testdrive/running-tests.md) | | Read the verdict and the evidence | [Results & Evidence](/build/testdrive/results-and-evidence.md) | | Understand what TestDrive learned | [Application Knowledge](/build/testdrive/app-knowledge.md) | | Generate tests from a project spec | [Definition & Specs](/organize/projects/definition-and-specs.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/tests-and-scripts.md?ask=&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.