Testing Guide

May 13, 2026 · View on GitHub

This monorepo uses Nx for orchestrating tests across all packages. Each package has its own testing requirements and infrastructure.

Quick Start

To run tests for any package:

# Complete test suites (recommended - handles Docker automatically)
pnpm nx test:auth auth-js                    # Complete auth-js test suite
pnpm nx test:storage storage-js              # Complete storage-js test suite
pnpm nx test:ci:postgrest postgrest-js      # Complete postgrest-js test suite
pnpm nx test functions-js                    # Standard test (uses testcontainers)
pnpm nx test realtime-js                     # Standard test (no Docker needed)
pnpm nx test supabase-js                    # Standard test (unit tests only)

# E2E tests (require local Supabase running — see E2E section below)
pnpm nx test:e2e auth-js                     # Auth-js Playwright e2e tests
pnpm nx test:e2e realtime-js                 # Realtime-js Playwright e2e tests

Package-Specific Testing Guides

Each package has unique testing requirements. Please refer to the individual README files for detailed instructions:

Core Packages

Package	Docker Required	Test Command	Documentation
auth-js	✅ Yes (GoTrue + PostgreSQL)	`pnpm nx test:auth auth-js`	Testing Guide
functions-js	✅ Yes (Deno relay via testcontainers)	`pnpm nx test functions-js`	Testing Guide
postgrest-js	✅ Yes (PostgREST + PostgreSQL)	`pnpm nx test:ci:postgrest postgrest-js`	Testing Guide
realtime-js	❌ No (uses mock WebSockets)	`pnpm nx test realtime-js`	Testing Guide
storage-js	✅ Yes (Storage API + PostgreSQL + Kong)	`pnpm nx test:storage storage-js`	Testing Guide
supabase-js	❌ No (unit tests only)	`pnpm nx test supabase-js`	Testing Guide

Coverage Commands

# Run tests with coverage
pnpm nx test supabase-js --coverage
pnpm nx test:coverage realtime-js
pnpm nx test:ci functions-js                 # Includes coverage

E2E Tests (Playwright)

The auth-js and realtime-js packages include Playwright end-to-end tests that run against their example apps and a local Supabase instance.

Prerequisites

Supabase running locally — Start the local Supabase stack via the supabase-js setup target:
```
pnpm nx test:supabase:setup supabase-js
```
Playwright Chromium — Installed automatically by the test:e2e target (no separate install needed).

Each example directory ships with a .env.local.ci file pre-configured for the default local Supabase instance (http://127.0.0.1:54321). The test:e2e target copies this file to .env.local automatically.

If you're using a custom local Supabase setup, create .env.local manually in the example directory:

Package	Directory	Variables
`auth-js`	`packages/core/auth-js/example/react/`	`VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY`
`realtime-js`	`packages/core/realtime-js/example/`	`NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`

Running E2E Tests

# Run individually
pnpm nx test:e2e auth-js
pnpm nx test:e2e realtime-js

# Run both sequentially (avoids port conflicts)
pnpm nx run-many --target=test:e2e --projects=auth-js,realtime-js --parallel=1

Note: Run with --parallel=1 when running both together — the apps use different ports (5173 and 3000) but share the same local Supabase, and sequential execution avoids potential resource conflicts.

What the Tests Cover

Package	Test file	Scenarios
`auth-js`	`example/react/tests/auth-flows.spec.ts`	Sign-up, sign-in, sign-out, anonymous auth, magic link, session persistence
`realtime-js`	`example/tests/chat.spec.ts`	Send messages, room switching, broadcast between clients, presence

Playwright Reports

On failure, test traces and screenshots are saved locally. In CI, Playwright HTML reports are uploaded as workflow artifacts.

Prerequisites

Node.js 20+ - Required for all packages
Docker - Required for auth-js, functions-js, postgrest-js, and storage-js
Ports - Various packages use different ports for test infrastructure (see individual READMEs)

CI Testing

In CI environments, tests are run automatically using GitHub Actions. The CI pipeline:

Sets up Node.js and Docker
Installs dependencies
Runs tests for all affected packages
Generates coverage reports

For CI-specific test commands, many packages have a test:ci target that includes coverage reporting.

Troubleshooting

For package-specific issues, consult the troubleshooting section in each package's README. Common issues:

Port conflicts: Check if required ports are already in use
Docker not running: Ensure Docker Desktop is started
Container cleanup: Use pnpm nx test:clean-post <package> if containers weren't properly removed

Contributing Tests

When adding new features or fixing bugs:

Write tests that cover your changes
Ensure all existing tests pass
Update test documentation if you change testing infrastructure
Follow the testing patterns established in each package

For more details on contributing, see CONTRIBUTING.md.