> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing

> Verify a commit once, then reuse its test result across every deployment

<Warning>
  **Experimental.** Automated testing is new and still evolving. The behavior described here works
  today, but details may change. If anything looks off, [contact us](mailto:support@stardeck.ai).
</Warning>

Stardeck can test the workflows your business depends on—checkout, booking, inventory updates, order submission—so a broken change is caught before your customers ever see it. The agent runs tests while building, and you can run them yourself anytime from the **Tests** tab.

You don't write tests by hand. You ask the agent to cover a workflow, and it writes and maintains the tests for you.

## How It Works

Each test walks through a critical workflow the way a customer would—"add two items to the cart, check out, confirm the order shows up"—and checks the result. If the workflow breaks, the test fails.

Tests run in a safe, isolated copy of your app: a private in-memory database and stand-ins for email, payments, and sign-in. **Running tests never touches real customer data, never sends real emails, and never charges real cards.** That's why you can run them as often as you like.

## The Tests Tab

To see and run your tests:

<Steps>
  <Step title="Open your app">
    Open your app in Stardeck and click the **Cloud** button in the top-right.
  </Step>

  <Step title="Go to the Tests tab">
    Under **Observability**, open
    [**Tests**](https://www.stardeck.ai/projects/~/dashboard/observability/tests).
  </Step>

  <Step title="Run the suite">
    Click **Run all** to run everything, or **Run** next to a single workflow to run just that one.
  </Step>
</Steps>

While a run is in progress you'll see the output stream live. When it finishes, each workflow shows a green check or a red ✗, how long it took, and—if something failed—the details of what went wrong, so you (or the agent) can fix it.

<Note>
  Running tests needs your app's workspace to be open and started. If it isn't, you'll see a prompt
  to open the project first.
</Note>

## Verify Once, Deploy Quickly

When a full test run finishes, Stardeck compares the exact tested files with the commit that was created. If they match and every test passed, the commit gets a green **Verified** badge.

Production and preview deployments of that exact commit inherit the same badge. They do not rerun the suite, so redeploying a verified commit stays fast.

If files change after the test run, the resulting commit stays unverified until the full suite runs again. A filtered workflow run is useful for debugging, but only an unfiltered **Run all** result can verify a commit.

Deployments can still proceed from an unverified commit. Check for the green badge when you want confirmation that the exact deployed code passed its suite.

## Adding or Changing Tests

Just ask the agent, in plain English, to cover the workflows that matter. For example:

```
Add a test for the checkout flow: adding items, paying with a test card, and seeing the order in admin
```

```
Write a test that makes sure two people can't book the same time slot
```

```
Cover the inventory workflow—placing an order should reduce stock, and you can't order more than is in stock
```

The agent writes the test, runs it, and fixes the code if the test uncovers a real bug. You'll see the new workflow appear in the Tests tab.

<Tip>
  Describe the workflow the way you'd describe it to a new employee—the steps a customer takes and
  what should happen. That's exactly what makes a good test.
</Tip>

You can also flip the order: describe the tests *before* the agent builds a feature, so they become your acceptance criteria.

<Card title="Building with Tests" icon="flask-vial" href="/test-driven-development">
  Have the agent write the tests first, then build until they pass
</Card>

## Running Tests Locally

If you work on your app locally (for example with Claude Code), the test suite is a standard [Vitest](https://vitest.dev) project. From your app directory:

```bash theme={null}
npm test
```

The same hermetic database and service stand-ins are used locally, so local runs are safe and need no real credentials. See [Local Development](/local-claude-code/connect) for connecting your local environment.

## Common Questions

### Do tests cost anything or affect my customers?

No. Tests run against an isolated in-memory copy of your app—no real data, emails, payments, or customer impact. They use a little of your app's workspace compute while running, nothing more.

### My commit shows that tests failed. What do I do?

Open the Tests tab to see which workflow failed and why, then ask the agent to fix it. Run the full suite again after the fix so the new commit receives a green **Verified** badge.

### My app doesn't have any tests yet.

That's fine. Deployments continue without a verification badge. Ask the agent to add tests for your most important workflow to get started.

### Can I test a single workflow without running everything?

Yes. In the Tests tab, click **Run** next to any individual workflow.