Your first test
In this tutorial you’ll test a sign-in page: a wrong password should show an error, and the right one should get you in. Use your own app if it has a sign-in page, and follow along with its words instead of ours.
You’ll need Sisyphus installed and your app running, say at http://localhost:3000.
-
Create a project
A project is a folder with a
sisyphus.yamlin it. Put it in your app’s repository, so tests live next to the code they test.Click New project… and pick your repository’s folder. Sisyphus creates a
sisyphus.yamlthere, with an example test.Terminal window cd my-appsis initOpen
sisyphus.yamlin your editor and set your app’s URL:sisyphus.yaml sisyphus: 1apps:web:browser: chromiumurl: http://localhost:3000defaults:timeout: 5sscreenshots: on-failurewebis the app’s name; tests refer to it. You can let Sisyphus start your dev server too. -
See what Sisyphus sees
Sisyphus finds things on screen by their role and name, the way a screen reader does. Ask it what’s on your page:
Click Inspect, then your app. You get a screenshot next to the list of elements; click either to see the selector for an element.
Terminal window sis inspect web- main- region "Sign in"- heading "Sign in"- text "Email"- textbox "Email"- text "Password"- textbox "Password"- button "Sign in"Every line is a selector you can paste into a test.
textbox "Email"is the email field;button "Sign in"is the button. -
Write the test
Create
tests/sign-in.sis.yaml:tests/sign-in.sis.yaml sisyphus: 1name: Wrong password shows an error, right one signs inapp: websteps:- fill: textbox "Email" = demo@example.com- fill: textbox "Password" = wrong-password- click: button "Sign in"- expect: alerttext: Wrong email or password- fill: textbox "Password" = the-right-password- click: button "Sign in"- expect: heading "My todos"Read it out loud: it’s what you’d tell a colleague to try. A few things to notice:
namesays what should happen. When it fails, the name tells you what’s broken.fillreplaces what’s in a field.clickclicks.expectchecks the screen.expect: heading "My todos"passes once that heading is visible. Withtext:it also checks the text inside.- There are no waits. Every step waits up to 5 seconds for its target, and every
expectkeeps checking until it passes.
-
Run it
Select the test in the Tests list and click Run. Tick Show the app in Run’s options to watch it.
Terminal window sis run # every test in the projectsis run --headed # and watch the browser do it✓ Wrong password shows an error, right one signs in 0.6s1 passed, 0 failed in 0.6s -
Break it on purpose
A test is only useful if it fails when something’s wrong. Change the last step to a heading that doesn’t exist,
heading "My tasks", and run again:✗ Wrong password shows an error, right one signs in 5.6s · tests/sign-in.sis.yamlat steps[6]:13 expect: heading "My tasks"ELEMENT_NOT_FOUND no visible element matches `heading "My tasks"`did you mean: heading "My todos" · region "My todos"screenshot: …/.sisyphus/runs/2026-11-15T14-50-24Z-353c/01-tests-sign-in/001-fail-steps-6.pngtree: …/.sisyphus/runs/2026-11-15T14-50-24Z-353c/01-tests-sign-in/fail-steps-6.tree.yaml0 passed, 1 failed in 5.6sYou get the step and its line, what went wrong, the closest things that were on screen, a screenshot, and the whole screen’s elements. That’s usually enough to know whether the test or the app is wrong. Put it back and it passes again.
What you’ve learned
Section titled “What you’ve learned”- A project is a
sisyphus.yamlthat names your apps. - A test is steps and checks, written with the role and name of what’s on screen.
- Sisyphus waits by itself, so tests have no sleeps.
- A failure tells you where, why, and what was there instead.
- Test a desktop app: the same thing with a macOS app.
- A tour of Studio: record tests instead of typing them.
- Finding elements: what to do when
button "Save"isn’t enough. - Organising a suite: from one test to hundreds.
