Supatester CLI

The Supatester CLI (supatester-cli) runs Supatester test plan export files from the command line (node.js), producing CI-friendly pass/fail output. It is the headless companion to the desktop app.

Installation

npm install -g supatester-cli

Exporting a Test Plan

In the desktop app, open the Automated Testing page, select your test plan, and click Export. This produces a self-contained JSON export file that includes all requests and test cases.

Basic Usage

supatester run ./my-tests.json \
  --url https://your-project.supabase.co \
  --publishable-key your-anon-key

Command Reference

supatester run <file> [options]

Connection Options

Flag	Environment 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 token. Note: Must be used in conjunction with --publishable-key or --secret-key flag
--email <email>	SUPABASE_EMAIL	Email for email auth context
--password <password>	SUPABASE_PASSWORD	Password for email auth context

All connection flags have environment variable equivalents. In CI pipelines, use environment variables (or secrets) instead of passing credentials as flags.

Execution Options

Flag	Default	Description
--bail	false	Stop after the first test failure.
--no-bail	—	Ignore any stopOnFailure setting in the test plan.
--test-plan <name>	all	Run only the named test plan. Repeatable to run multiple by name.
--delay-request <ms>	0	Pause between each request (milliseconds).
--timeout <ms>	0	Maximum total run time (0 = no limit).
--timeout-request <ms>	30000	Per-request timeout.
--var "name=value"	—	Set a variable. Repeatable for multiple variables.
--snapshot <snapshot name>	—	Supply a snapshot name (create in desktop app) to run against.

Reporter Options

Flag	Default	Description
-r, --reporters <list>	cli	Comma-separated list of reporters: cli, json, junit, progress
--reporter-json-export <path>	./supatester/results.json	Output path for JSON reporter
--reporter-junit-export <path>	./supatester/results.xml	Output path for JUnit reporter
--reporter-cli-no-summary	false	Suppress the summary table in CLI output
--reporter-cli-no-failures	false	Suppress the failure detail section
--reporter-cli-no-banner	false	Suppress the Supatester ASCII banner
--reporter-cli-show-timestamps	false	Print timestamps for each test

Output Options

Flag	Default	Description
--color <on|off|auto>	auto	Enable/disable coloured terminal output
--disable-unicode	false	Replace symbols (✓ ✗) with plain text
-x, --suppress-exit-code	false	Always exit 0, even with failures
--verbose	false	Show detailed request/response data for each test
--snapshot <name>	—	Compare test responses against a named snapshot from the export file. If the snapshot is not found, exits with code 2 and lists available snapshots. Snapshot mismatches are reported as failures

Exit Codes

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

Reporters

CLI (default)

Human-readable terminal output with a summary table. Best for local runs and log review.

Progress

Minimal single-line progress indicator. Useful in terminals where full output is noisy.

JUnit XML

Produces a JUnit-format XML file compatible with all major CI systems. Use this reporter to publish test results as native CI test reports.

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

JSON

Produces a full run summary as a JSON file. Useful for downstream processing, custom dashboards, or storing result history.

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

Multiple Reporters at Once

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

CI/CD Integration

The CLI is designed to fit naturally into any CI/CD pipeline. The general pattern is the same regardless of the platform you use:

1. Install supatester-cli as part of your pipeline setup step.
2. Store credentials as encrypted secrets in your CI environment (URL, keys, passwords). Reference them as environment variables — the CLI reads SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_EMAIL, and SUPABASE_PASSWORD automatically.
3. Run the CLI pointing at your exported test plan JSON file (commit this file to your repository alongside your code).
4. Publish results — use the junit reporter to produce a JUnit XML file, then use your CI platform's native test reporting feature to surface pass/fail counts, trend charts, and failure details directly in the pipeline UI.
5. Control failure behaviour — by default, the CLI exits with code 1 on any test failure, which will cause most CI systems to fail the step. Use --suppress-exit-code if you want to collect results without blocking the pipeline.

GitHub Actions Example

The workflow requires secrets to connect to your Supabase project.

1. Go to your repo on GitHub → Settings → Secrets and variables → Actions.
2. Click New repository secret and add each of the following:

Secret Name	Value	Description
SUPABASE_URL	https://<project-ref>.supabase.co	Your Supabase project URL
SUPABASE_ANON_KEY	sb_publishable_...	Your project's publishable (anon) key

Where to find these: In your Supabase dashboard → Settings → API. The URL is the "Project URL" and the anon key is the "anon / public" key under "Project API Keys".

Optional: Authentication Contexts

If your test plan includes tests that use the secret, Custom JWT, Email auth context, you also need:

Secret Name	Value
SUPABASE_SERVICE_ROLE_KEY	sb_secret_... (service_role key from Supabase dashboard)
SUPABASE_CUSTOM_JWT	eyJ... (service_role key from Supabase dashboard)
SUPABASE_EMAIL	test@test.com (Email User Account created in Supabase)
SUPABASE_PASSWORD	c0mpl3xPa55w0rd (service_role key from Supabase dashboard)

And add the necessary flags to the supatester run command in the workflow to suit your test cases:

--secret-key ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
--custom-jwt ${{ secrets.SUPABASE_CUSTOM_JWT }}
--email ${{ secrets.SUPABASE_EMAIL }}
--password ${{ secrets.SUPABASE_PASSWORD }}

Update the Workflow (if needed)

Edit .github/workflows/supatester.yml to match your test file name and add the authenticaiton context flags as previously discussed:

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: '20'
      - name: Install Supatester CLI
        run: npm install -g supatester-cli
      - name: Run Supabase Tests
        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
      - name: Publish Test Results
        uses: dorny/test-reporter@v1
        if: always()
        with:
          name: Supabase Tests
          path: ./reports/junit.xml
          reporter: java-junit

GitLab CI Example

Define SUPABASE_URL and SUPABASE_ANON_KEY as CI/CD variables in your GitLab project settings under Settings → CI/CD → Variables.

supabase-tests:
  image: node:20
  script:
    - npm install -g supatester-cli
    - supatester run ./tests/supabase-tests.json
        --url $SUPABASE_URL
        --publishable-key $SUPABASE_ANON_KEY
        -r cli,junit
        --reporter-junit-export ./reports/junit.xml
  artifacts:
    when: always
    reports:
      junit: ./reports/junit.xml

Programmatic API

For advanced use cases — such as running tests from within a Node.js script or custom tooling — the CLI also exposes a 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)

Supported Test Types

The CLI supports all request types that can be exported from the desktop app:

• SELECT, INSERT, UPDATE, DELETE queries from Basic and Advanced mode
• RPC function calls
• Storage operations (list, upload, download, delete, bucket management, etc.)
• Edge Function invocations
• Advanced chain-based queries (variables)

Testing with Anonymous user accounts from the CLI is not supported due to the requirement for interactive flows for CAPTCHA.