Skip to content

How Sisyphus works

You don’t need to know any of this to write a test. But knowing the main ideas makes everything else in these docs easier to follow.

your-project/
├─ sisyphus.yaml ← which apps to test and how to start them
├─ tests/
│ ├─ sign-in.sis.yaml ← one test: steps a person would take, and checks
│ └─ checkout.sis.yaml
└─ flows/
└─ login.sis.yaml ← steps several tests share, like "log in"
  • A project is a folder with a sisyphus.yaml. It usually lives inside the repository of the product it tests.
  • An app is something Sisyphus can start and drive: a website (with a URL), an Electron app, a macOS app. You give each one a short name in sisyphus.yaml.
  • A test is one behaviour a user cares about (“a wrong password shows an error”): a list of steps and checks, in a .sis.yaml file. It passes or fails.
  • A flow is a reusable list of steps with parameters, like a function: “log in as this user”. Tests call: it.
  • A suite is a named selection of tests (“smoke”, “nightly”) that you run together.

Then there are three ways to use them, all doing the same thing underneath:

  • Sisyphus Studio, the desktop app: write, record, debug and run tests visually.
  • sis, the command-line tool: run tests on your machine or in CI.
  • The MCP server (sis mcp): lets AI coding agents use Sisyphus.

Sisyphus doesn’t look at pixels and doesn’t need your source code. It sees your app the way assistive technology such as a screen reader does: as a list of elements, each with a role and a name. For a sign-in form it looks like this:

- main
- heading "Sign in"
- textbox "Email"
- textbox "Password"
- button "Sign in"
- link "Forgot your password?"

The role is what kind of thing it is (button, textbox, heading); the name is the words a person would use for it (its label or text).

A selector points at one of these lines, written the same way:

- click: button "Sign in"

That’s why tests read like instructions to a person, and why they keep working when you restyle the page, move things around or rename CSS classes. They only break when what a user sees changes, which is exactly when you want to know.

The same works for every kind of app: a page in a real browser, a native Mac app, and hybrid apps like Electron and Tauri, where one selector language reaches both the native menu bar and the web page inside the window.

  1. Start the app. Sisyphus opens the app the test names, and any dev server it needs.
  2. Run each step. Each step waits until its target is there and can be used (visible, enabled), up to a timeout (5 seconds by default), then acts like a person: clicks, types, presses keys.
  3. Check. An expect step keeps looking until what it expects is true, or the timeout runs out. That’s why you never need sleep.
  4. Clean up. Run the test’s teardown, quit what it started, close windows it left open.
  5. Report. Pass or fail, how long it took, and for a failure: the step, the reason, the nearest matches, a screenshot and the elements that were on screen.

Each test starts from a fresh app (a fresh browser profile on the web; slow desktop apps can stay open and get tidied up instead), so tests don’t depend on each other and can run in parallel.

A few rules make Sisyphus predictable:

  • A selector must match exactly one thing. If button "Delete" matches three buttons, the step fails with AMBIGUOUS_SELECTOR and lists them. Sisyphus never quietly picks the first one, because “the first one” is how tests end up clicking the wrong thing.
  • Steps act like a person. If a dialog covers the button, the step fails with NOT_INTERACTABLE and says what’s on top, rather than clicking through it.
  • No AI decides anything while your tests run. The same test on the same app gives the same result.

Each run is saved in .sisyphus/runs/<run-id>/ inside your project: the results, and screenshots and element lists of failures. Studio’s Runs view shows them, sis show prints the latest, and sis stats finds tests that are flaky or slow over recent runs. The folder is git-ignored; the newest 50 runs are kept.

Next: Install Sisyphus.

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