Supatester CLI

Run Supabase test plans from the command line — the CI/CD companion for Supatester.

Supatester CLI executes Supatester test plan export files against a live Supabase instance, producing CI-friendly output.

Installation

npm install -g supatester-cli

Quick Start

# Export a test plan from the Supatester desktop app using "Export for CLI"
# Then run it:
supatester run ./my-tests.json --url https://your-project.supabase.co --publishable-key your-publishable-key

Usage

supatester run <test file> [options]

Connection Options

| Flag | Env Variable | Description | |---|---|---| | --url <url> | SUPABASE_URL | Supabase project URL | | --publishable-key <key> | SUPABASE_ANON_KEY | Publishable (anon) key | | --secret-key <key> | SUPABASE_SERVICE_ROLE_KEY | Service-role (secret) key | | --custom-jwt <token> | SUPABASE_CUSTOM_JWT | Custom JWT for custom-jwt auth context | | --email <email> | SUPABASE_EMAIL | Email for email auth context | | --password <password> | SUPABASE_PASSWORD | Password for email auth context |

Execution Options

| Flag | Default | Description | |---|---|---| | --bail | false | Stop on first test failure | | --no-bail | — | Ignore stopOnFailure from test plans | | --test-plan <name> | all | Run only the specified test plan from a file that has multiple test plans (repeatable) | | --delay-request <ms> | 0 | Delay between requests | | --timeout <ms> | 0 | Overall timeout | | --timeout-request <ms> | 30000 | Per-request timeout | | --var "name=value" | — | Set a variable (repeatable) |

Reporter Options

| Flag | Default | Description | |---|---|---| | -r, --reporters <list> | cli | Comma-separated: cli, json, junit, progress | | --reporter-json-export <path> | ./supatester/results.json | JSON output path | | --reporter-junit-export <path> | ./supatester/results.xml | JUnit XML path |

Output Options

| Flag | Default | Description | |---|---|---| | --color <on\|off\|auto> | auto | Coloured output | | --disable-unicode | false | Plain text symbols | | -x, --suppress-exit-code | false | Always exit 0 | | --verbose | false | Show request/response data |

Exit Codes

| Code | Meaning | |---|---| | 0 | All tests passed | | 1 | One or more tests failed | | 2 | Run error (invalid file, connection failure, etc.) |

Reporters

CLI (default)

Pretty-printed terminal output:

supatester

→ 1. Auth Context Verification
  ✓ RPC get_user_context as Anonymous  (124ms)
  ✗ RPC get_user_context as Secret Key  (112ms)
    Error: Response does not contain "service_role"

┌─────────────────────────────────┬──────────┬──────────┐
│                                 │ executed │ failed   │
├─────────────────────────────────┼──────────┼──────────┤
│ tests                           │ 5        │ 1        │
└─────────────────────────────────┴──────────┴──────────┘

JUnit XML

For CI systems (GitHub Actions, GitLab CI, Azure DevOps, Jenkins):

supatester run ./tests.json -r junit --reporter-junit-export ./results.xml

JSON

Full run summary as JSON:

supatester run ./tests.json -r json --reporter-json-export ./results.json

Multiple Reporters

supatester run ./tests.json -r cli,junit,json \
  --reporter-junit-export ./reports/junit.xml \
  --reporter-json-export ./reports/results.json

CI/CD Examples

GitHub Actions

name: Supabase API Tests
on: [push, pull_request]

permissions:
  contents: read
  checks: write

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install -g supatester-cli
      - run: |
          supatester run ./tests/supabase-tests.json \
            --url ${{ secrets.SUPABASE_URL }} \
            --publishable-key ${{ secrets.SUPABASE_ANON_KEY }} \
            -r cli,junit \
            --reporter-junit-export ./reports/junit.xml
      - uses: dorny/test-reporter@v1
        if: always()
        with:
          name: Supabase Tests
          path: ./reports/junit.xml
          reporter: java-junit

Programmatic API

import { run } from 'supatester-cli'

const { run: summary } = await run({
  testPlan: require('./my-test-export.json'),
  url: process.env.SUPABASE_URL!,
  publishableKey: process.env.SUPABASE_ANON_KEY!,
  reporters: ['cli', 'junit'],
  reporter: {
    junit: { export: './results/junit.xml' }
  }
})

process.exit(summary.failures.length > 0 ? 1 : 0)

License

See LICENSE file