Skip to content

Commit f6027b9

Browse files
mandarinimandarini
committed
chore(repo): update testing doc
1 parent 18d4fab commit f6027b9

File tree

4 files changed

+286
-320
lines changed

4 files changed

+286
-320
lines changed

‎docs/TESTING.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,14 @@ Each package has unique testing requirements. Please refer to the individual REA
2222

2323
### Core Packages
2424

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

3434
### Common Test Commands
3535

‎packages/core/supabase-js/README.md‎

Lines changed: 1 addition & 312 deletions
Original file line numberDiff line numberDiff line change
@@ -146,318 +146,7 @@ npx nx build supabase-js --watch
146146

147147
### Testing
148148

149-
**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.
150-
151-
#### Prerequisites for All Integration Tests
152-
153-
1. **Docker** must be installed and running
154-
2. **Supabase CLI** must be installed (`npm install -g supabase` or via package manager)
155-
3. **Local Supabase instance** must be started:
156-
157-
```bash
158-
# Navigate to the supabase-js package directory
159-
cd packages/core/supabase-js
160-
161-
# Start Supabase (downloads and starts all required containers)
162-
npx supabase start
163-
164-
# The output will show:
165-
# - API URL: http://127.0.0.1:54321
166-
# - Database URL: postgresql://postgres:[email protected]:54322/postgres
167-
# - Studio URL: http://127.0.0.1:54323
168-
# - Anon key: [your-anon-key]
169-
# - Service role key: [your-service-role-key] # Important for some tests!
170-
171-
# Return to monorepo root for running tests
172-
cd ../../..
173-
```
174-
175-
#### Test Scripts Overview
176-
177-
| Script | Description | Requirements |
178-
| -------------------------- | ----------------------------------------- | --------------------------------------- |
179-
| `test` | Runs unit tests + type checking | None |
180-
| `test:all` | Unit + integration + browser tests | Supabase running |
181-
| `test:run` | Jest unit tests only | None |
182-
| `test:unit` | Jest unit tests in test/unit directory | None |
183-
| `test:coverage` | Unit tests with coverage report | None |
184-
| `test:integration` | Node.js integration tests | Supabase running + SERVICE_ROLE_KEY |
185-
| `test:integration:browser` | Browser tests using Deno + Puppeteer | Supabase running + Deno installed |
186-
| `test:edge-functions` | Edge Functions tests | Supabase running + Deno installed |
187-
| `test:types` | TypeScript type checking + JSR validation | None |
188-
| `test:bun` | Bun runtime compatibility tests | Supabase running + Bun installed |
189-
| `test:node:playwright` | WebSocket browser tests | Supabase running + Playwright |
190-
| Deno (see section below) | Deno runtime compatibility tests | Supabase running + Deno installed |
191-
| Expo (see section below) | React Native/Expo tests | Supabase running + dependencies updated |
192-
| Next.js (see below) | Next.js SSR tests | Supabase running + dependencies updated |
193-
194-
#### Unit Testing
195-
196-
```bash
197-
# Run all unit tests (Jest)
198-
npx nx test supabase-js
199-
200-
# Run only unit tests in test/unit directory
201-
npx nx test:unit supabase-js
202-
203-
# Run tests in watch mode during development
204-
npx nx test supabase-js --watch
205-
206-
# Run tests with coverage report
207-
npx nx test:coverage supabase-js
208-
```
209-
210-
#### Integration Testing
211-
212-
```bash
213-
# Prerequisites: Start Supabase first (see above)
214-
215-
# Run Node.js integration tests
216-
# IMPORTANT: Requires SUPABASE_SERVICE_ROLE_KEY environment variable
217-
cd packages/core/supabase-js
218-
export SUPABASE_SERVICE_ROLE_KEY="$(npx supabase status --output json | jq -r '.SERVICE_ROLE_KEY')"
219-
cd ../../..
220-
npx nx test:integration supabase-js
221-
222-
# Run browser-based integration tests (requires Deno)
223-
npx nx test:integration:browser supabase-js
224-
```
225-
226-
#### Running All Tests
227-
228-
```bash
229-
# This runs type checking, unit tests, and integration tests sequentially
230-
# NOTE: Will fail if Supabase is not running or dependencies not updated
231-
npx nx test:all supabase-js
232-
```
233-
234-
**Common Issues and Solutions:**
235-
236-
| Issue | Solution |
237-
| -------------------------------------------- | --------------------------------------------------------------- |
238-
| "Cannot find module 'https://deno.land/...'" | Deno tests incorrectly run by Jest - check `jest.config.ts` |
239-
| "Port 54322 already allocated" | Stop existing Supabase: `npx supabase stop --project-id <name>` |
240-
| "503 Service Unavailable" for Edge Functions | Supabase not running - start with `npx supabase start` |
241-
| "Uncommitted changes" during type check | Commit changes or add `--allow-dirty` to JSR publish |
242-
| Integration tests fail with auth errors | Export `SUPABASE_SERVICE_ROLE_KEY` (see Integration Testing) |
243-
244-
### Platform-Specific Testing
245-
246-
#### Expo Testing (React Native)
247-
248-
**Note:** For testing with local changes, use the Verdaccio workflow described in "Running Integration Tests Locally with Verdaccio" above.
249-
250-
```bash
251-
# Prerequisites:
252-
# 1. Supabase must be running (see Prerequisites)
253-
# 2. Packages published to Verdaccio (see Verdaccio section)
254-
255-
# Run Expo tests from the Expo test project
256-
cd packages/core/supabase-js/test/integration/expo
257-
echo 'registry=http://localhost:4873/' > .npmrc
258-
npm install
259-
npm test
260-
rm .npmrc
261-
cd ../../../..
262-
```
263-
264-
#### Next.js Testing (SSR)
265-
266-
**Note:** For testing with local changes, use the Verdaccio workflow described in "Running Integration Tests Locally with Verdaccio" above.
267-
268-
```bash
269-
# Prerequisites:
270-
# 1. Supabase must be running (see Prerequisites)
271-
# 2. Packages published to Verdaccio (see Verdaccio section)
272-
# 3. Install Playwright browsers and dependencies
273-
npx playwright install --with-deps
274-
275-
# Run Next.js tests from the Next test project
276-
cd packages/core/supabase-js/test/integration/next
277-
echo 'registry=http://localhost:4873/' > .npmrc
278-
npm install --legacy-peer-deps
279-
npm run test
280-
rm .npmrc
281-
cd ../../../..
282-
```
283-
284-
#### Deno Testing
285-
286-
**Note:** For testing with local changes, use the Verdaccio workflow described in "Running Integration Tests Locally with Verdaccio" above.
287-
288-
```bash
289-
# Prerequisites:
290-
# 1. Deno must be installed (https://deno.land)
291-
# 2. Supabase must be running (see Prerequisites)
292-
# 3. Packages published to Verdaccio (see Verdaccio section)
293-
294-
# Run Deno tests
295-
npx nx test:deno supabase-js
296-
```
297-
298-
### Edge Functions Testing
299-
300-
The project includes Edge Functions integration tests that require a local Supabase instance to be running.
301-
302-
```bash
303-
# Prerequisites:
304-
# 1. Ensure Docker is installed and running
305-
# 2. Navigate to the supabase-js package directory
306-
cd packages/core/supabase-js
307-
308-
# 3. Start Supabase locally (this will download and start all required containers)
309-
npx supabase start
310-
311-
# Wait for the output showing all services are ready, including:
312-
# - API URL: http://127.0.0.1:54321
313-
# - Database URL: postgresql://postgres:[email protected]:54322/postgres
314-
# - Edge Runtime container
315-
316-
# 4. Run the Edge Functions tests from the monorepo root
317-
cd ../../../ # Back to monorepo root
318-
npx nx test:edge-functions supabase-js
319-
```
320-
321-
**Important Notes:**
322-
323-
- The Edge Functions tests will fail with 503 errors if Supabase is not running
324-
- If you encounter port conflicts (e.g., "port 54322 already allocated"), stop any existing Supabase instances:
325-
326-
```bash
327-
npx supabase stop --project-id <project-name>
328-
# Or stop all Docker containers if unsure:
329-
docker ps | grep supabase # List all Supabase containers
330-
```
331-
332-
- The tests use the default local development credentials (anon key)
333-
- Edge Functions are automatically served when `supabase start` is run
334-
335-
#### Bun Testing
336-
337-
**Note:** For testing with local changes, use the Verdaccio workflow described in "Running Integration Tests Locally with Verdaccio" above.
338-
339-
```bash
340-
# Prerequisites:
341-
# 1. Bun must be installed (https://bun.sh)
342-
# 2. Supabase must be running (see Prerequisites)
343-
# 3. Packages published to Verdaccio (see Verdaccio section)
344-
345-
# Run Bun tests
346-
npx nx test:bun supabase-js
347-
```
348-
349-
#### Running Integration Tests Locally with Verdaccio
350-
351-
For the most accurate testing that mirrors CI exactly, use a local Verdaccio registry. This approach:
352-
- Tests the actual published package (not just source code)
353-
- Mirrors the exact CI workflow
354-
- Works for all integration test types (Next.js, Expo, Bun, Deno)
355-
356-
**Setup:**
357-
358-
```bash
359-
# Terminal 1: Start local Verdaccio registry (stays running)
360-
npx nx local-registry
361-
362-
# Terminal 2: Build and publish packages to local registry
363-
npx nx run-many --target=build --all
364-
npx nx populate-local-registry
365-
```
366-
367-
**Run Integration Tests:**
368-
369-
```bash
370-
# Example: Test with Bun
371-
cd packages/core/supabase-js/test/integration/bun
372-
echo 'registry=http://localhost:4873/' > .npmrc
373-
bun install
374-
bun test
375-
rm .npmrc # Clean up
376-
cd ../../../..
377-
378-
# Example: Test with Next.js
379-
cd packages/core/supabase-js/test/integration/next
380-
echo 'registry=http://localhost:4873/' > .npmrc
381-
npm install --legacy-peer-deps
382-
npm test
383-
rm .npmrc
384-
cd ../../../..
385-
386-
# Example: Test with Expo
387-
cd packages/core/supabase-js/test/integration/expo
388-
echo 'registry=http://localhost:4873/' > .npmrc
389-
npm install
390-
npm test
391-
rm .npmrc
392-
cd ../../../..
393-
394-
# Example: Test with Deno
395-
cd packages/core/supabase-js/test/deno
396-
echo 'registry=http://localhost:4873/' > .npmrc
397-
npm install
398-
npm test
399-
rm .npmrc
400-
cd ../../../..
401-
```
402-
403-
**Tips:**
404-
- Keep Verdaccio running in Terminal 1 for multiple test runs
405-
- Only rebuild/republish when you change source code
406-
- Registry runs on `http://localhost:4873/`
407-
- To stop Verdaccio: Ctrl+C in Terminal 1
408-
409-
#### WebSocket Browser Testing
410-
411-
```bash
412-
# Prerequisites:
413-
# 1. Supabase must be running (see Prerequisites)
414-
# 2. Build the UMD bundle first:
415-
npx nx build supabase-js
416-
417-
# Run WebSocket browser tests with Playwright
418-
cd packages/core/supabase-js/test/integration/node-browser
419-
npm install
420-
cp ../../../dist/umd/supabase.js .
421-
npm run test
422-
cd ../../..
423-
```
424-
425-
#### CI/CD Testing
426-
427-
When running on CI, the tests automatically publish packages to a local Verdaccio registry. The CI pipeline:
428-
429-
1. Builds all packages with current dependencies
430-
2. Starts a local Verdaccio registry
431-
3. Publishes all packages to Verdaccio
432-
4. Integration tests install from Verdaccio, ensuring they test the actual built packages
433-
434-
### Local Testing with Your Changes
435-
436-
The platform-specific tests (Expo, Next.js, Deno, Bun) install from registries rather than directly importing from source. This ensures they test the actual built packages as they would be consumed by users.
437-
438-
**For local development:** Use the Verdaccio workflow described in "Running Integration Tests Locally with Verdaccio" above. This mirrors CI exactly and allows you to test your local changes before pushing.
439-
440-
### Test Coverage
441-
442-
#### Viewing Coverage Reports
443-
444-
```bash
445-
# Generate coverage report
446-
npx nx test:coverage supabase-js
447-
448-
# Serve coverage report locally (opens interactive HTML report)
449-
npx nx serve:coverage supabase-js
450-
# This starts a local server at http://localhost:3000 with the coverage report
451-
```
452-
453-
The coverage report shows:
454-
455-
- Line coverage
456-
- Branch coverage
457-
- Function coverage
458-
- Uncovered lines with highlights
459-
460-
Coverage results are also automatically uploaded to Coveralls in CI for tracking over time.
149+
Please read our [testing guide](./TESTING.md) for detailed instructions on how to run your tests locally.
461150

462151
### Contributing
463152

0 commit comments

Comments
 (0)