> 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/workspaces-and-urls.md). # Workspaces & Application URLs Create a QA workspace, point it at the environments you want tested, and ground it in the project it belongs to A **workspace** is one application under test. Everything else in TestDrive hangs off it: the URLs it runs against, the credentials it signs in with, the tests it runs, and everything it has learned about your app. Keep one workspace per product, not per environment — environments are application URLs *inside* a workspace, so the knowledge and tests are shared across them. ## Creating a Workspace From the TestDrive list, click **New QA workspace**. A name is all that's required; a description helps when the list grows. You can link a Darcy Project at the same time, or later from settings. New workspaces open the **setup guide** automatically: | Step | Required? | What it's for | | ----------------------------- | --------- | ---------------------------------------------------------------------- | | **Add application URLs** | Yes | Where TestDrive runs your tests | | **Link a Darcy Project** | Optional | Grounds runs in the project's context and unlocks pull-request testing | | **Equip the workspace agent** | Optional | Extra skills and integrations for the agent that drives the browser | | **Use TestDrive from Slack** | Optional | Report issues from a channel and get evidence back in the thread | | **Add credentials** | Optional | Give TestDrive a login | | **Connect via MCP** | Optional | Drive the workspace from your editor | | **Create your first test** | Optional | Describe one thing that must keep working | You can reopen it any time from **Setup guide** in the workspace header. ## Application URLs An application URL is a **named target**: the URL to test, and the domains TestDrive is permitted to reach while it's there. | Field | What it does | | ------------------- | ----------------------------------------------------------- | | **Name** | How you'll refer to it — "Staging", "Preview", "Production" | | **URL** | Where the run starts | | **Allowed domains** | The hosts TestDrive may access during the run | | **Set as default** | The target used when a test doesn't name one | {% hint style="info" %} **Allowed domains are a boundary, not a convenience.** They're what keeps a test on your application rather than wandering into third-party sites it happens to link to. Include the identity provider and any API host your app genuinely needs. {% endhint %} URLs can be archived when an environment goes away; archived URLs stop appearing as run targets but leave existing run history intact. ### Choosing a Target at Run Time | Where | Behavior | | ---------------------------- | -------------------------------------------------------------------------------------------------------- | | **On a test** | Each test can pin a specific URL, or use **Workspace default** | | **On a manual run** | If more than one URL is active, you pick which to run against — selecting several queues one run per URL | | **On a schedule or trigger** | Automations can name the URLs they target | That's what makes "run the smoke tests against staging every night, and the full suite against the preview on every PR" a configuration rather than a fork in the suite. ## Linking a Darcy Project Linking a [Project](/organize/projects.md) does two things: * **Grounds the runs.** The agent gets the project's context — what this product is and what it's supposed to do — instead of inferring everything from the DOM. * **Unlocks pull-request testing.** The project's GitHub connection is what lets TestDrive see pull requests and their preview deployments. The workspace list shows which is which: **Project grounded** versus **App only**, and the header badges a connected workspace **GitHub connected** or **manual**. If a pull request has no detected preview deployment, TestDrive falls back to the **fallback preview URL** in workspace settings — worth setting if your previews aren't discoverable. ## Workspace Settings Open **Settings** from the workspace header for the rest: | Setting | What it controls | | --------------------------------- | ------------------------------------------------------ | | **Name and description** | How the workspace appears in the list | | **Linked project** | Grounding and GitHub connection | | **Pull-request testing** | Whether PRs trigger runs, and the fallback preview URL | | **Agent skills and integrations** | What the workspace agent can use while it tests | | **Run concurrency** | How many runs this workspace may have in flight | ## Working in a Workspace The workspace has seven tabs: | Tab | What's there | | -------------------------- | ------------------------------------------------------------------------------------ | | **Overview** | The state of the workspace at a glance | | **Tests** | Your acceptance tests — see [Tests & Scripts](/build/testdrive/tests-and-scripts.md) | | **Runs** | Run history, filterable by trigger and outcome | | **Credentials** | Identities this workspace can run as | | **Application URLs** | Execution targets and their permitted domains | | **Schedules and Triggers** | Schedules, webhooks, and GitHub triggers | | **Knowledge** | What TestDrive has learned about the app | ## Next Steps | Goal | Documentation | | --------------------------------- | -------------------------------------------------------------------- | | Let TestDrive sign in | [Credentials & Sign-In](/build/testdrive/credentials-and-sign-in.md) | | Write your first test | [Tests & Scripts](/build/testdrive/tests-and-scripts.md) | | Automate when runs happen | [Running Tests](/build/testdrive/running-tests.md) | | Ground the workspace in a project | [Projects](/organize/projects.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/workspaces-and-urls.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.