> 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/running-tests.md).

# Running Tests

Start a run by hand, or let pull requests, schedules, and webhooks start it for you

A **run** is one execution of a set of tests against one application URL. It produces a verdict, a report, and the evidence behind both.

## Starting a Run by Hand

Click **Run** in the workspace and the **Choose tests** picker opens. It lists only tests that are **approved, enabled, and ready to run** — a draft, a disabled test, or a test whose script is still generating isn't offered, and neither is one already in a run.

Tick what you want, or **All ready tests**, and click **Start run**. If the workspace has more than one active application URL you'll be asked which to run against; selecting several queues one run per URL so you can compare environments rather than blending them.

## What Can Trigger a Run

| Trigger            | When it fires                                       |
| ------------------ | --------------------------------------------------- |
| **Manual**         | You clicked Run                                     |
| **Pull request**   | A PR opened against the linked project's repository |
| **Script build**   | Darcy is building or rebuilding a script            |
| **Scheduled**      | A cron schedule you configured                      |
| **Webhook**        | An external system called your trigger URL          |
| **GitHub trigger** | A configured GitHub event                           |
| **Slack**          | A triage investigation started from Slack           |

The Runs tab filters by trigger, so "what did the nightly schedule do this week" and "what happened on PRs" are separate questions with separate answers.

## Pull-Request Testing

With a linked project and its GitHub connection, TestDrive can test a pull request against its preview deployment — the change, in a browser, before review. Where no preview deployment is detected, the workspace's **fallback preview URL** is used.

This is the point of the whole feature for most teams: the acceptance tests that describe what you promised, run automatically against the change that claims to deliver it.

## Schedules

Schedules run on cron expressions. A schedule can name specific tests, select them **by tag**, or run everything eligible, and it can target particular application URLs.

Tag-based selection is the maintainable choice: tag a new test `smoke` and it joins the nightly run without anyone editing the schedule. If a schedule's selection stops matching anything runnable it's flagged as unresolvable, and it won't re-enable until the selection makes sense again.

## Webhook Triggers

A webhook trigger gives an external system a URL to call. TestDrive provides catalog support for common senders — including GitHub, Linear, CircleCI, Semaphore, and AWS EventBridge — plus a generic option for anything else, with per-source **event filters** so a trigger responds to the events you care about rather than every message the sender emits.

Each trigger has a **webhook URL** and a **signing secret**. The secret is shown once, when you create it.

{% hint style="warning" %}
**Save the signing secret when it's shown.** It isn't retrievable afterwards — you'd have to rotate it. Put it in your CI's secret store before you close the panel.
{% endhint %}

Like schedules, webhook triggers select tests by tag or by id, and only approved, enabled tests with a runnable script are eligible.

## One Run at a Time

A workspace runs **one run at a time**, and a run can contain many tests. The limit is per workspace, so two workspaces testing two products don't queue behind each other.

| Situation                                         | What happens                                                                          |
| ------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **You start a run while one is in progress**      | You're told the workspace has reached its concurrent run limit                        |
| **A webhook arrives while the workspace is busy** | It's acknowledged, and reported as not run rather than silently dropped               |
| **A scheduled run comes due**                     | Scheduled runs start regardless, so a nightly suite isn't skipped by a busy afternoon |

Workspace settings control the concurrency limit if your application can take more.

## Cancelling

A run in progress can be cancelled from its detail page. It stops where it is and keeps the evidence gathered up to that point, which is often enough to answer the question that made you cancel.

## Credits

Starting a run consumes credits. If your organization is out, the run is refused with **"Out of credits"** rather than failing partway through.

## Next Steps

| Goal                          | Documentation                                                            |
| ----------------------------- | ------------------------------------------------------------------------ |
| Read what a run produced      | [Results & Evidence](/build/testdrive/results-and-evidence.md)           |
| Write or generate more tests  | [Tests & Scripts](/build/testdrive/tests-and-scripts.md)                 |
| Add a target environment      | [Workspaces & Application URLs](/build/testdrive/workspaces-and-urls.md) |
| Trigger runs from 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/running-tests.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.