Testing
Have your agent write workflow tests, run them locally or in the cloud sandbox, and verify a commit once for every deployment.
Experimental. Automated testing is new and still evolving. The behavior described here works today, but details may change. If anything looks off, contact us.
Workflow tests catch a broken checkout, booking, or inventory change before customers see it. Ask your coding agent, or Starcat Developer in the Build tab, to cover a workflow; it writes and maintains the tests. Run them locally with npm test, or in the cloud sandbox from the Tests tab.
How It Works
Each test walks a workflow the way a customer would ("add two items to the cart, check out, confirm the order shows up") and checks the result.
Tests run in an 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.
What Kinds of Test to Write
Your app's AGENTS.md tells every agent to write only four kinds of test:
| Kind | What it checks |
|---|---|
| Workflow | Calls the app's real routes against the test database in the order a person would (sign in, add to cart, check out), including edge cases such as stock running out. |
| Screen | Renders a page with Testing Library on top of the real test backend. |
| Structure | Checks an app-wide rule by reading code or manifests. |
| End-to-end smoke | Drives a real browser through one happy path of a critical flow. At most one per flow, because they are slow. |
No pure unit tests and no mocked tests. A function tested on its own, or a seam replaced with
vi.mock, can pass while checkout breaks. A price or tax rule is tested through the route that uses
it, by checking what it stored.
The Tests Tab
To see and run your tests:
Open your app
Go to the Tests tab
Run the suite
Click Run all to run everything, or Run next to a single workflow to run just that one.
Output streams live. Each workflow then shows pass or fail, duration, and failure details.
The Tests tab runs the suite in the app's cloud sandbox, which must be running. If it isn't, open the app's Build tab to start it, then run again.
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.
A local npm test run doesn't verify a commit. Run the full suite in the cloud sandbox: Run all in the Tests tab, or run_project_tests from your coding agent on a Read & write connection.
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
Ask your coding agent, or Starcat Developer, in plain English:
Add a test for the checkout flow: adding items, paying with a test card, and seeing the order in adminWrite a test that makes sure two people can't book the same time slotCover the inventory workflow: placing an order reduces stock, and you can't order more than is in stockThe agent writes the test, runs it, and fixes the code if it finds a real bug. The workflow appears in the Tests tab.
Building with Tests First
Describe the behavior before the agent builds a feature. The tests become your acceptance criteria.
How to Do It
Describe the behavior
List what a person does and what should happen:
Before building anything, write tests for a gift card feature:
- someone buys a $50 gift card and receives the code by email
- someone pays for part of an order with a gift card and the rest by credit card
- someone can't spend the same gift card balance twiceReview the test names
The tests appear in the Tests tab, named as your sentences. Ask for anything missing. They fail at this point, which is expected.
Ask for the feature
Now build the gift card feature until all those tests passThe agent builds and reruns until they pass.
Before reworking something that already works, ask the agent to cover the current behavior first, then make the change:
Before changing anything: make sure the checkout workflow has tests covering
ordering, payment, and the confirmation email. Then change shipping to be
calculated by weight instead of a flat rate.When Not to Bother
Skip tests for copy, styling, layout, and one-off content edits; check those in the preview. Use them for money, bookings, inventory, accounts, or anything with rules.
Running Tests Locally
Locally, the suite is a standard Vitest project. From your app directory:
npm testLocal runs use the same isolated database and stand-ins and need no real credentials. See Running Locally.
npm run test:e2e runs the end-to-end suite with Playwright against your running dev server. It
writes real data to the data store your .env.local points at.
From your coding agent, list_project_tests, run_project_tests and get_test_run list, run and
read the suites in the cloud sandbox. They need agent:tests:run, and the end-to-end suite needs a
Read & write connection. See Tools & Permissions.
Common Questions
Do tests cost anything or affect my customers?
No. They run against an isolated copy and use a little sandbox compute while running.
My commit shows that tests failed. What do I do?
Open the Tests tab to see which workflow failed, ask the agent to fix it, then run the full suite so the new commit gets Verified.
My app doesn't have any tests yet.
Deployments continue without a verification badge. Ask the agent to cover your most important workflow.
Can I test a single workflow without running everything?
Yes. In the Tests tab, click Run next to any individual workflow.
Next: Publishing & Deployment
Deploy a verified commit to a preview or production