Skip to content

sisyphus.yaml

sisyphus.yaml marks a project’s root. A folder below with its own sisyphus.yaml is a separate project. JSON Schema: schema/config.schema.json.

sisyphus: 1
apps: { … }
defaults: { … }
vars:
email: demo@example.com
suites: { … }
apps:
web: # a browser app
browser: chromium # chromium | firefox | webkit | chrome | msedge
url: ${env.BASE_URL:-http://localhost:3000}
serve: { command: npm run dev, ready: http://localhost:3000 }
setup: [ { call: login } ] # before every test that uses this app
teardown: [ { run: ./reset.sh } ] # after, always
desktop: # Electron
electron: { main: ./dist/main.js } # or executable: ./out/App.app/Contents/MacOS/App
editor: # native app, or Tauri
macos: { bundle: com.example.editor } # or app: ./App.app, or exe: ./bin/app
windows: { exe: ./target/debug/editor.exe } # WebView2 apps (Tauri…)
hybrid: # anything exposing Chrome DevTools (WebView2…)
cdp: { endpoint: http://127.0.0.1:9222, command: ./start-with-debugging.sh }
Key Notes
browser, url Web apps. Each test gets a fresh browser context
serve A dev server: command, and a ready URL to wait for. Started once per run
electron main: (a script run with Electron) or executable:
macos bundle:, app: or exe:; plus args, attach: true (use the running app, never quit it), keep_open: true (leave it running)
windows exe: (.exe may be left off), args, env, keep_open. Sisyphus starts it with WebView2’s remote debugging on and drives its web content, as with cdp:; native-only Windows apps and attach: true aren’t supported yet
linux Native app spec (adapter planned)
cdp endpoint, optional command (Sisyphus waits up to 20 s for the endpoint)
env On electron, macos, windows, linux: environment variables for the app
setup, teardown Steps around every test that uses the app; app_setup: false on a test skips them
reuse Keep a slow desktop app open between tests. See below

Every string is ${…} interpolated, so ${secret.API_KEY}, ${env.X} and ${project_dir} work. A native exe: starts in the project folder.

reuse: # or `reuse: true` for the defaults
on_launch: [ … ] # after every (re)launch: get to the start state
check: [ … ] # before each test: are we at the start state?
steps: [ … ] # optional extra reset after each test
close_windows: true # close windows/dialogs/menus the test opened (default)
discard: false # true (or a button name): answer "Don't Save" prompts

Native desktop apps only. See Desktop apps that start slowly.

defaults:
timeout: 5s # each step waits up to this for its target
screenshots: on-failure # never | on-failure | every-step
headless: true
step_delay: 300ms # pause before each step; default none
workers: 4 # tests at once; default 1
retries: 1 # reruns of a failing test; default 0
keep_runs: 50 # runs kept in .sisyphus/runs; 0 keeps all
a11y: warn # warn | strict | off
shell: sh # for run: commands without shell:; default sh (cmd on Windows)

shell: lets one suite’s run: commands work everywhere: with shell: sh, a Windows machine runs them in Git Bash (see run:).

suites:
smoke: { description: Every pull request, tags: [smoke] }
nightly: { paths: [tests], skip_tags: [manual], workers: 4, retries: 1 }

A suite takes paths (default: all), keeps tests with any of tags, drops those with any of skip_tags. workers and retries apply when it runs. Command-line paths and tags narrow it further; --workers and --retries override it.

*.load.yaml files (schema: schema/load.schema.json):

sisyphus: 1
name: Checkout under load
load:
test: tests/checkout.sis.yaml
target: https://staging.example.com
allow_hosts: [staging.example.com, "*.api.example.com"] # required
data: load/users.csv # one row per virtual user
ui: { users: 10, ramp: 30s, iterations: 1 }
replay: { users: 500, ramp: 60s, duration: 5m, think: 1s-3s }
thresholds: { http_p95: 800ms, error_rate: 1%, ui_failures: 0 }

replay.source: x.har replays your own recording; replay.correlate: [{ regex: 'csrf" value="([^"]+)' }] extracts extra values (as ${corr0}, …). See Load testing.

Path What Commit it?
.sisyphus/runs/<id>/ Results, screenshots, failure trees No
.sisyphus/elements/<app>.txt Elements the Inspector has seen, for completion Yes
.sisyphus/secrets.env Local secrets Never
.sisyphus/.gitignore Ignores all of the above except elements/ Yes
Made by Bussin Bytes© 2026 Bussin Bytes Ltd · sisyphus.bussinbytes.io