supatester-cli 1.0.7 → 1.0.9

package/README.md

@@ -1,3 +1,181 @@
 # Supatester CLI
 
-> Pre Release
+> Run Supabase test plans from the command line — the CI/CD companion for [Supatester](https://supatester.com).
+
+Supatester CLI executes Supatester test plan export files against a live Supabase instance, producing CI-friendly output.
+
+## Installation
+
+```bash
+npm install -g supatester-cli
+```
+
+## Quick Start
+
+```bash
+# 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-anon-key
+```
+
+cd cli
+npm run build
+node dist/bin/supatester.js run ./supatester-export-project.json --url https://nxwobgdsfgdsdwff.supabase.co --publishable-key "sb_publishable_KJhjshfosdjJHKjdisijdfnkd"
+
+
+## Usage
+
+```
+supatester run <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 (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):
+
+```bash
+supatester run ./tests.json -r junit --reporter-junit-export ./results.xml
+```
+
+### JSON
+
+Full run summary as JSON:
+
+```bash
+supatester run ./tests.json -r json --reporter-json-export ./results.json
+```
+
+### Multiple Reporters
+
+```bash
+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
+
+```yaml
+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
+
+```typescript
+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