Writing good tests
A test suite is only valuable if people trust it. These habits are what make the difference between a suite that catches bugs for years and one that everyone learns to ignore.
Test one behaviour, and name it
Section titled “Test one behaviour, and name it”A test checks one thing a user cares about, and its name says what should happen:
| Good | Not so good |
|---|---|
| Wrong password shows an error | Login test 3 |
| Clearing completed todos keeps the open ones | Todos |
| A phone screen shows the whole sign-in form | Responsive |
When a test fails, its name is the first thing anyone reads. “Wrong password shows an error ✗” tells you what’s broken without opening anything.
Aim for 5 to 20 steps. Longer tests usually check several behaviours: split them.
Make every test stand alone
Section titled “Make every test stand alone”Each test sets up what it needs (signs in, creates the record it edits) and never relies on another test having run first.
Chained tests (“test 2 needs the project test 1 created”) fail together, can’t be run one at a time, and can’t run in parallel. Put shared steps in a flow instead, and reset data with a setup step.
Check what the user sees
Section titled “Check what the user sees”# Good: what a person would look for- expect: text "Payment received"- expect: button "Pay now" enabled: false
# Fragile: internal details a user never sees- expect: "#div-42 > span.msg-success"Point at things by role and visible name first. Use an id (#save) only when there’s no good name, and ask for one to be added if you can (data-testid on the web).
Never sleep
Section titled “Never sleep”# Don't- click: button "Save"- wait: 2s- expect: text "Saved"
# Do- click: button "Save"- expect: text "Saved"Every step waits for its target, and every expect retries until it passes. A fixed sleep is either too short (flaky) or too long (slow), often both. If something takes longer than 5 seconds, raise that one step’s timeout:.
End with a check
Section titled “End with a check”A test that only clicks proves nothing broke loudly. End each part of a test with an expect that proves it worked: the record appears, the counter changed, the dialog closed.
Don’t repeat yourself; reuse flows
Section titled “Don’t repeat yourself; reuse flows”Signing in, creating a project, opening a document: write those once as flows and call: them. When the sign-in page changes, you fix one file instead of forty tests. sis validate points out steps that repeat an existing flow.
Same test, different inputs: use data
Section titled “Same test, different inputs: use data”Ten copies of a test that differ in one value are ten tests to maintain. Use data: instead: one test, one row per case, one result per row.
Keep secrets out of tests
Section titled “Keep secrets out of tests”Write ${secret.PASSWORD}, not the password. Secrets come from the environment or .sisyphus/secrets.env and are masked in every result. See Variables and secrets.
Review tests like code
Section titled “Review tests like code”Tests live in your repository and change with your product. Review them in pull requests: is the name a behaviour? Does it stand alone? Does it check what matters? This applies doubly to tests written by AI agents.
