Skip to main content
stably fix is a headless command that automatically diagnoses test failures and applies AI-generated fixes. Designed for unattended execution, it’s ideal for self-healing CI pipelines, background maintenance agents, and automated test repair workflows. 
# Auto-detects the last test run (local or CI)
stably fix

# With explicit run ID
stably fix <runId>
For interactive debugging, use the Interactive Agent instead. stably fix is optimized for automated, hands-off repair.

​
How It Works

1

Run tests

Execute your test suite with stably test. The Stably Reporter captures failure context — screenshots, traces, DOM snapshots, and logs.
2

AI diagnoses each failure

stably fix analyzes the failure context to determine why each test failed and categorizes the issue.
3

Fixes are applied

The AI generates targeted code changes and applies them to your test files.
4

Review the results

View the diagnosis report and applied fixes. In CI, fixes can be committed and pushed automatically.

​
Run ID Detection

stably fix automatically detects which test run to fix using this fallback chain:
  1. Explicit argument — stably fix <runId>
  2. CI environment — detected from CI provider variables (GitHub Actions, Azure DevOps, Bitbucket, GitLab, CircleCI, Jenkins, and others via the env-ci library)
  3. Last local run — read from .stably/last-run.json (written automatically by stably test)
In most cases, just run stably test followed by stably fix — no run ID needed.
When tests fail, the Stably Reporter also prints a ready-to-copy stably fix <runId> command in the terminal output.

​
Diagnosis Categories

Each failure is categorized to help you understand at a glance whether it needs attention or has already been addressed:
CategoryWhat it means
Test OutdatedThe test references selectors or flows that have changed in your app
Actual BugThe test caught a real bug in your application
UnstableThe test fails intermittently due to timing or race conditions
UI ChangeThe UI changed intentionally and the test needs to reflect the new design
MiscellaneousOther issues that don’t fit the categories above

​
Monitoring Fix Sessions

When stably fix runs, it automatically creates an automation — a real-time view of the agent’s progress visible on the Stably web dashboard. This is especially useful in CI pipelines, Docker containers, and other non-interactive environments where you can’t see the terminal.
Stably fix automation showing real-time agent progress on the web dashboard
From the dashboard you can:
  • Watch progress live — see the current phase, activity log, and files being fixed
  • Send messages to the agent — provide guidance or corrections while the agent works, even in CI
  • View the final report — when complete, the automation shows a summary with links to the autoheal report
Fix automations track these phases: initializing → triage → fixing → validation → complete
Automation creation is best-effort and non-blocking. If the connection fails, the CLI continues normally — your commands are never interrupted.
$ stably fix run_abc123

Analyzing 3 failures...

checkout.spec.ts > complete purchase
  Issue: Selector '.checkout-button' not found
  Fix: Updated to '[data-testid="checkout-btn"]'
  ✓ Fixed

login.spec.ts > invalid credentials
  Issue: Error message assertion failed
  Fix: Updated expected text to match new design
  ✓ Fixed

Summary: 2 auto-fixed, 1 requires manual review

​
CI Integration

​
GitHub Actions: Self-Healing Pipeline

# .github/workflows/self-healing-tests.yml
name: Self-Healing Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test-and-fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci && npx stably install

      - name: Run tests
        id: test
        continue-on-error: true
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
        run: npx stably test

      - name: Auto-fix failures
        if: steps.test.outcome == 'failure'
        env:
          STABLY_API_KEY: ${{ secrets.STABLY_API_KEY }}
          STABLY_PROJECT_ID: ${{ secrets.STABLY_PROJECT_ID }}
        run: npx stably fix

      - name: Commit fixes
        if: steps.test.outcome == 'failure'
        run: |
          git config user.name "stably-bot"
          git config user.email "bot@stably.ai"
          git add tests/
          git commit -m "fix: auto-repair failing tests" || exit 0
          git push

​
Background Agent Integration

# Called by AI coding agents for autonomous test maintenance
# Chain test execution with automatic repair

stably test || stably fix

# Full pipeline: test → fix → verify
stably test || (stably fix && stably test)

​
Autofix on Scheduled Runs

When running tests on Stably Cloud Runner, you can enable autofix to run automatically after each scheduled run — no CLI invocation needed.

​
Enabling Autofix

From the Dashboard: When creating or editing a scheduled test run, toggle “Auto-fix failing tests”. In stably.yaml: Add autofix: true to any schedule definition:
stably.yaml
schedules:
  nightly-regression:
    cron: "0 2 * * *"
    stablyTestArgs: "--project regression"
    autofix: true
You can enable autofix on some schedules and leave it off on others — it’s configured per schedule.

​
Viewing Results

After autofix completes, results appear in your test runs table under the “Diagnosis & Fix” column:
  • Fixing — autofix is still running
  • Diagnosed — analysis is complete, with issue counts by category
  • Review fix — click to see the full report and code changes
  • No fix available — the issue was identified but couldn’t be automatically repaired
Click “Review fix” to open the detailed report, which includes:
  • Each failing test with its diagnosis
  • The code changes that were applied
  • A link to the generated pull request (if your repo is connected to GitHub)

​
Configuration

Fine-tune how the fix agent behaves using the agent.fix section in stably.yaml:
stably.yaml
agent:
  fix:
    maxTurnsPerIssue: 30               # Max turns per issue (default: 50)
    maxParallelWorkers: 3              # Max parallel workers for fixing issues (default: 2)
    skipAfterConsecutiveUnfixed: 3     # Skip tests unfixed 3+ consecutive runs
    rules: |                           # Custom instructions for the fix agent
      Prefer data-testid selectors over CSS selectors.
      Always add comments explaining selector changes.
OptionTypeDescription
maxTurnsPerIssuenumberMaximum AI turns per issue (default: 50)
maxParallelWorkersnumberNumber of issues to fix in parallel (default: 2)
skipAfterConsecutiveUnfixednumberSkip tests that have failed to fix this many times in a row — saves AI costs on persistently broken tests
rulesstringCustom instructions appended to the agent’s system prompt (e.g., selector preferences, coding conventions). Use YAML `` for multi-line rules

​
Next Steps

Run Tests

Run tests locally or in CI with stably test

Test Reporter

Stream test results and traces to Stably

Scheduled Runs

Configure when your tests run automatically

Alerting

Get notified about test failures and fixes