Skip to content

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.

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.

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.

# 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).

# 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:.

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.

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.

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.

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.

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.

Made by Bussin Bytes© 2026 Bussin Bytes Ltd · sisyphus.bussinbytes.io