Skip to content

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.

  1. Create a project

    A project is a folder with a sisyphus.yaml in 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.yaml there, with an example test.

    Open sisyphus.yaml in your editor and set your app’s URL:

    sisyphus.yaml
    sisyphus: 1
    apps:
    web:
    browser: chromium
    url: http://localhost:3000
    defaults:
    timeout: 5s
    screenshots: on-failure

    web is the app’s name; tests refer to it. You can let Sisyphus start your dev server too.

  2. 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.

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

  3. Write the test

    Create tests/sign-in.sis.yaml:

    tests/sign-in.sis.yaml
    sisyphus: 1
    name: Wrong password shows an error, right one signs in
    app: web
    steps:
    - fill: textbox "Email" = demo@example.com
    - fill: textbox "Password" = wrong-password
    - click: button "Sign in"
    - expect: alert
    text: 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:

    • name says what should happen. When it fails, the name tells you what’s broken.
    • fill replaces what’s in a field. click clicks.
    • expect checks the screen. expect: heading "My todos" passes once that heading is visible. With text: it also checks the text inside.
    • There are no waits. Every step waits up to 5 seconds for its target, and every expect keeps checking until it passes.
  4. Run it

    Select the test in the Tests list and click Run. Tick Show the app in Run’s options to watch it.

    ✓ Wrong password shows an error, right one signs in 0.6s
    1 passed, 0 failed in 0.6s
  5. 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.yaml
    at 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.png
    tree: …/.sisyphus/runs/2026-11-15T14-50-24Z-353c/01-tests-sign-in/fail-steps-6.tree.yaml
    0 passed, 1 failed in 5.6s

    You 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.

  • A project is a sisyphus.yaml that 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.
Made by Bussin Bytes© 2026 Bussin Bytes Ltd · sisyphus.bussinbytes.io