Skip to content

chore(repo): cleanup and update docs #1798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

chore(repo): cleanup and update docs #1798

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

16 changes: 8 additions & 8 deletions docs/TESTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,14 @@ Each package has unique testing requirements. Please refer to the individual REA

### Core Packages

| Package | Docker Required | Test Command | Documentation |
| ---------------- | ---------------------------------------- | -------------------------------- | ------------------------------------------------------------- |
| **auth-js** | ✅ Yes (GoTrue + PostgreSQL) | `npx nx test:auth auth-js` | [Testing Guide](packages/core/auth-js/README.md#testing) |
| **functions-js** | ✅ Yes (Deno relay via testcontainers) | `npx nx test functions-js` | [Testing Guide](packages/core/functions-js/README.md#testing) |
| **postgrest-js** | ✅ Yes (PostgREST + PostgreSQL) | `npx nx test postgrest-js` | [Testing Guide](packages/core/postgrest-js/README.md#testing) |
| **realtime-js** | ❌ No (uses mock WebSockets) | `npx nx test realtime-js` | [Testing Guide](packages/core/realtime-js/README.md#testing) |
| **storage-js** | ✅ Yes (Storage API + PostgreSQL + Kong) | `npx nx test:storage storage-js` | [Testing Guide](packages/core/storage-js/README.md#testing) |
| **supabase-js** | ❌ No (unit tests only) | `npx nx test supabase-js` | [Testing Guide](packages/core/supabase-js/README.md#testing) |
| Package | Docker Required | Test Command | Documentation |
| ---------------- | ---------------------------------------- | -------------------------------- | ---------------------------------------------------------------- |
| **auth-js** | ✅ Yes (GoTrue + PostgreSQL) | `npx nx test:auth auth-js` | [Testing Guide](../packages/core/auth-js/README.md#testing) |
| **functions-js** | ✅ Yes (Deno relay via testcontainers) | `npx nx test functions-js` | [Testing Guide](../packages/core/functions-js/README.md#testing) |
| **postgrest-js** | ✅ Yes (PostgREST + PostgreSQL) | `npx nx test postgrest-js` | [Testing Guide](../packages/core/postgrest-js/README.md#testing) |
| **realtime-js** | ❌ No (uses mock WebSockets) | `npx nx test realtime-js` | [Testing Guide](../packages/core/realtime-js/README.md#testing) |
| **storage-js** | ✅ Yes (Storage API + PostgreSQL + Kong) | `npx nx test:storage storage-js` | [Testing Guide](../packages/core/storage-js/README.md#testing) |
| **supabase-js** | ✅ Yes | `npx nx test supabase-js` | [Testing Guide](../packages/core/supabase-js/TESTING.md) |

### Common Test Commands

Expand Down
1 change: 1 addition & 0 deletions packages/core/supabase-js/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ docs/v2
# Test package-lock files (use local tarball, checksums change with builds)
test/*/package-lock.json
test/integration/*/package-lock.json
test/integration/*/bun.lock

.cursor/

Expand Down
275 changes: 1 addition & 274 deletions packages/core/supabase-js/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,280 +146,7 @@ npx nx build supabase-js --watch

### Testing

**Important:** The test suite includes tests for multiple runtime environments (Node.js, Deno, Bun, Expo, Next.js). Each environment has its own test runner and specific requirements.

#### Prerequisites for All Integration Tests

1. **Docker** must be installed and running
2. **Supabase CLI** must be installed (`npm install -g supabase` or via package manager)
3. **Local Supabase instance** must be started:

```bash
# Navigate to the supabase-js package directory
cd packages/core/supabase-js

# Start Supabase (downloads and starts all required containers)
npx supabase start

# The output will show:
# - API URL: http://127.0.0.1:54321
# - Database URL: postgresql://postgres:[email protected]:54322/postgres
# - Studio URL: http://127.0.0.1:54323
# - Anon key: [your-anon-key]
# - Service role key: [your-service-role-key] # Important for some tests!

# Return to monorepo root for running tests
cd ../../..
```

#### Test Scripts Overview

| Script | Description | Requirements |
| -------------------------- | ----------------------------------------- | --------------------------------------- |
| `test` | Runs unit tests + type checking | None |
| `test:all` | Unit + integration + browser tests | Supabase running |
| `test:run` | Jest unit tests only | None |
| `test:unit` | Jest unit tests in test/unit directory | None |
| `test:coverage` | Unit tests with coverage report | None |
| `test:integration` | Node.js integration tests | Supabase running + SERVICE_ROLE_KEY |
| `test:integration:browser` | Browser tests using Deno + Puppeteer | Supabase running + Deno installed |
| `test:edge-functions` | Edge Functions tests | Supabase running + Deno installed |
| `test:types` | TypeScript type checking + JSR validation | None |
| `test:bun` | Bun runtime compatibility tests | Supabase running + Bun installed |
| `test:node:playwright` | WebSocket browser tests | Supabase running + Playwright |
| Deno (see section below) | Deno runtime compatibility tests | Supabase running + Deno installed |
| Expo (see section below) | React Native/Expo tests | Supabase running + dependencies updated |
| Next.js (see below) | Next.js SSR tests | Supabase running + dependencies updated |

#### Unit Testing

```bash
# Run all unit tests (Jest)
npx nx test supabase-js

# Run only unit tests in test/unit directory
npx nx test:unit supabase-js

# Run tests in watch mode during development
npx nx test supabase-js --watch

# Run tests with coverage report
npx nx test:coverage supabase-js
```

#### Integration Testing

```bash
# Prerequisites: Start Supabase first (see above)

# Run Node.js integration tests
# IMPORTANT: Requires SUPABASE_SERVICE_ROLE_KEY environment variable
cd packages/core/supabase-js
export SUPABASE_SERVICE_ROLE_KEY="$(npx supabase status --output json | jq -r '.SERVICE_ROLE_KEY')"
cd ../../..
npx nx test:integration supabase-js

# Run browser-based integration tests (requires Deno)
npx nx test:integration:browser supabase-js
```

#### Running All Tests

```bash
# This runs type checking, unit tests, and integration tests sequentially
# NOTE: Will fail if Supabase is not running or dependencies not updated
npx nx test:all supabase-js
```

**Common Issues and Solutions:**

| Issue | Solution |
| -------------------------------------------- | --------------------------------------------------------------- |
| "Cannot find module 'https://deno.land/...'" | Deno tests incorrectly run by Jest - check `jest.config.ts` |
| "Port 54322 already allocated" | Stop existing Supabase: `npx supabase stop --project-id <name>` |
| "503 Service Unavailable" for Edge Functions | Supabase not running - start with `npx supabase start` |
| "Uncommitted changes" during type check | Commit changes or add `--allow-dirty` to JSR publish |
| Integration tests fail with auth errors | Export `SUPABASE_SERVICE_ROLE_KEY` (see Integration Testing) |

### Platform-Specific Testing

#### Expo Testing (React Native)

```bash
# Prerequisites:
# 1. Supabase must be running (see Prerequisites)
# 2. Update test dependencies and pack current build
cd packages/core/supabase-js
npm run update:test-deps:expo

# Run Expo tests from the Expo test project
cd test/integration/expo
npm install
npm test
cd ../../..
```

#### Next.js Testing (SSR)

```bash
# Prerequisites:
# 1. Supabase must be running (see Prerequisites)
# 2. Update test dependencies and pack current build
npx nx update:test-deps:next supabase-js

# 3. Install Playwright browsers and dependencies
npx playwright install --with-deps

# Run Next.js tests from the Next test project
cd packages/core/supabase-js/test/integration/next
npm install --legacy-peer-deps
npm run test
cd ../../..
```

#### Deno Testing

```bash
# Prerequisites:
# 1. Deno must be installed (https://deno.land)
# 2. Supabase must be running (see Prerequisites)
# 3. Update test dependencies:
npx nx update:test-deps:deno supabase-js

# Run Deno tests
npx nx test:deno supabase-js
```

### Edge Functions Testing

The project includes Edge Functions integration tests that require a local Supabase instance to be running.

```bash
# Prerequisites:
# 1. Ensure Docker is installed and running
# 2. Navigate to the supabase-js package directory
cd packages/core/supabase-js

# 3. Start Supabase locally (this will download and start all required containers)
npx supabase start

# Wait for the output showing all services are ready, including:
# - API URL: http://127.0.0.1:54321
# - Database URL: postgresql://postgres:[email protected]:54322/postgres
# - Edge Runtime container

# 4. Run the Edge Functions tests from the monorepo root
cd ../../../ # Back to monorepo root
npx nx test:edge-functions supabase-js
```

**Important Notes:**

- The Edge Functions tests will fail with 503 errors if Supabase is not running
- If you encounter port conflicts (e.g., "port 54322 already allocated"), stop any existing Supabase instances:

```bash
npx supabase stop --project-id <project-name>
# Or stop all Docker containers if unsure:
docker ps | grep supabase # List all Supabase containers
```

- The tests use the default local development credentials (anon key)
- Edge Functions are automatically served when `supabase start` is run

#### Bun Testing

```bash
# Prerequisites:
# 1. Bun must be installed (https://bun.sh)
# 2. Supabase must be running (see Prerequisites)
# 3. Update test dependencies:
npx nx update:test-deps:bun supabase-js

# Run Bun tests
npx nx test:bun supabase-js
```

#### WebSocket Browser Testing

```bash
# Prerequisites:
# 1. Supabase must be running (see Prerequisites)
# 2. Build the UMD bundle first:
npx nx build supabase-js

# Run WebSocket browser tests with Playwright
cd packages/core/supabase-js/test/integration/node-browser
npm install
cp ../../../dist/umd/supabase.js .
npm run test
cd ../../..
```

#### CI/CD Testing

When running on CI, the tests automatically use the latest dependencies from the root project. The CI pipeline:

1. Builds the main project with current dependencies
2. Creates a package archive (`.tgz`) with the latest versions
3. Uses this archive in Expo, Next.js, Deno, and Bun tests to ensure consistency

### Updating Test Dependencies

The platform-specific tests (Expo, Next.js, Deno, Bun) use a packaged version of supabase-js rather than directly importing from source. This ensures they test the actual built package as it would be consumed by users.

#### How It Works

1. **Build** the current supabase-js package
2. **Pack** it into a `.tgz` file (like `npm pack` does)
3. **Copy** the `.tgz` to the test directory
4. **Install** it in the test project

This mimics how real users would install and use the package.

#### Update Scripts

```bash
# Update ALL test environment dependencies at once
# This builds, packs, and installs in all test directories
npx nx update:test-deps supabase-js

# Or update specific test environments:
npx nx update:test-deps:expo supabase-js # Expo/React Native only
npx nx update:test-deps:next supabase-js # Next.js only
npx nx update:test-deps:deno supabase-js # Deno only
npx nx update:test-deps:bun supabase-js # Bun only
```

**When to Update:**

- After making changes to the source code
- Before running platform-specific tests locally
- When debugging test failures that might be due to stale dependencies

**Note:** CI automatically handles this, so manual updates are only needed for local development.

### Test Coverage

#### Viewing Coverage Reports

```bash
# Generate coverage report
npx nx test:coverage supabase-js

# Serve coverage report locally (opens interactive HTML report)
npx nx serve:coverage supabase-js
# This starts a local server at http://localhost:3000 with the coverage report
```

The coverage report shows:

- Line coverage
- Branch coverage
- Function coverage
- Uncovered lines with highlights

Coverage results are also automatically uploaded to Coveralls in CI for tracking over time.
Please read our [testing guide](./TESTING.md) for detailed instructions on how to run your tests locally.

### Contributing

Expand Down
Loading
Loading