Documentation

Everything you need to get Stillworks running on your app.

Getting started

Connect your repo in under 2 minutes. No config files, no CI setup.

Click Connect GitHub on the homepage. Stillworks requests read-only access to your repositories — it never writes to your code.

Add your repository

From the dashboard, click Add repository. Pick your repo and paste the URL where your app is deployed (e.g. https://myapp.vercel.app).

Push and watch

Every push to your main branch automatically triggers a test run. Stillworks opens a real browser, visits each route, and reports back within 60 seconds.

✓ No test files to write. No YAML. No setup beyond step 2.

Route statuses

Each route gets one of five statuses after a run.

Accessible

Page loads, HTTP 200, content rendered, no fatal errors.

Warning

Page loads but has JS errors, a slow response, or minor issues worth watching.

Degraded

Page is accessible but an AI-detected interaction is broken — a button or form that doesn't work as expected.

Failed

Page is inaccessible — HTTP 404, 500, blank content, or network error.

Auth required

Route redirects to login. Provide test credentials in Settings to test it fully.

The overall run status is the worst status across all routes — one Failed route turns the whole run red.

AI interaction tests

Beyond checking if a page loads, Stillworks reads your component source code and generates real interaction tests — filling forms, clicking buttons, verifying success messages.

What it tests

Form submitFills inputs with test data, submits, verifies success state

Button clicksClicks interactive buttons, checks result or navigation

Auth flowsFills login form, verifies redirect after login

AssertionsChecks that a success message appears, or a URL changes

Result states

AI_PASS

All steps completed successfully.

AI_SKIP

A step couldn't run — element not found. Our selector was wrong, not your app.

AI_CLEAN

Static page with no interactions to test. This is a positive signal.

AI_FAIL

An assertion failed — button didn't work, success message never appeared. This is a real app bug.

AI_FAIL turns the route Degraded (orange). The page is still accessible but an interaction is broken. It does not count as a full failure in the pass/total metric.

Test credentials

Protected routes redirect to login. To test them, add a dedicated test account in your repo settings.

Create a test account in your app

Use a dedicated account like test@yourapp.com — never your personal account. Make sure it has access to the routes you want tested.

Add credentials in Stillworks

Go to Repo → Configure → Credentials and enter the email and password of your test account.

Stillworks handles the rest

On each run, Stillworks automatically detects the login page, signs in with your credentials, and tests protected routes as an authenticated user.

⚠ Credentials are stored encrypted and only decrypted inside the isolated test runner. They are never logged or stored in plaintext.

Notifications

Get alerted when a route breaks, by email, Slack, or Discord.

Email

Enabled by default. A report is sent after every run that has at least one failure. Configure the recipient in Settings → Notifications.

Slack

Paste your Slack Incoming Webhook URL in Repo → Configure → Slack webhook. Stillworks posts a message in your chosen channel after each run.

❌ clumsyquest/shop-frontend · a3f29c1
❌ 23/25 routes passing — 2 failed

✅ /checkout — Accessible
❌ /dashboard — Server error (5xx)

Discord

Same as Slack — paste your Discord Webhook URL in Repo → Configure → Discord webhook. Stillworks sends an embed with the full run summary.

GitHub integration

Commit status check

After each run, Stillworks posts a stillworks/routes status on your commit. It appears directly on the pull request as a green checkmark or red cross.

To block merges when tests fail, go to your GitHub repo → Settings → Branches → Branch protection rules → enable Require status checks to pass → search for stillworks/routes.

PR comment

When a push is linked to an open pull request, Stillworks automatically posts a comment with the full route summary — no need to open the dashboard.

✅ Stillworks — 23/25 routes passing
❌ /checkout — page vide (composant crash)
⚠️ /login — JS errors détectées

API reference

Trigger runs, read results, and manage repos programmatically. All endpoints are at https://stillworks-production.up.railway.app.

Authentication

All API calls require your personal token in the request header.

X-Stillworks-Token: YOUR_TOKEN

Get your token at Settings → API tokens. You can create multiple tokens and revoke them at any time.

User endpoints (token auth)

Get your API token

Go to Settings → API tokens to create a personal token. Tokens can be revoked at any time.

SDK

Use the SDK to trigger runs, read results, and integrate Stillworks into your own scripts — without writing HTTP calls manually.

Both SDKs use your personal API token and wrap the same endpoints as the API reference above.

Python

pip install stillworks-sdk

from stillworks_sdk import StillworksClient client = StillworksClient(token="swt_your_token") print(client.whoami()) # {'github_login': 'alice', 'plan': 'free'} print(client.repos()) # list of configured repos print(client.runs("alice", "my-app", limit=5)) # last 5 runs client.run_now("alice", "my-app") # trigger a run print(client.analytics(days=7)) # pass rate, broken routes

JavaScript / TypeScript

npm install stillworks-sdk-js

import { StillworksClient } from "stillworks-sdk-js"; const client = new StillworksClient("swt_your_token"); console.log(await client.whoami()); console.log(await client.repos()); console.log(await client.runs("alice", "my-app", 5)); await client.runNow("alice", "my-app"); console.log(await client.analytics(7));

Errors

Both SDKs raise typed exceptions:

StillworksErrorBase class — any API error. Has a .status_code attribute.

UnauthorizedErrorToken missing or invalid (HTTP 401).

RateLimitErrorMonthly run limit reached (HTTP 402). Upgrade to Pro.

Something missing or unclear?Contact us →