diff --git a/.github/workflows/ci-supabase-js.yml b/.github/workflows/ci-supabase-js.yml index 309a59f32..9d909e39c 100644 --- a/.github/workflows/ci-supabase-js.yml +++ b/.github/workflows/ci-supabase-js.yml @@ -85,11 +85,8 @@ jobs: - name: Install dependencies run: npm ci --legacy-peer-deps - - name: Type Check - run: npx nx test:types supabase-js - - - name: Run Unit Tests + Coverage - run: npx nx test:coverage supabase-js + - name: Type Check + Unit Tests + Coverage + run: npx nx run-many --targets=test:types,test:coverage --projects=supabase-js - name: Upload coverage results to Coveralls uses: coverallsapp/github-action@v2 @@ -219,7 +216,7 @@ jobs: if: ${{ matrix.deno == '2.x' }} run: | cd packages/core/supabase-js/test/deno - npx nx test:edge-functions supabase-js + npm run test:edge-functions cd ../../.. - name: Stop Supabase @@ -344,9 +341,6 @@ jobs: echo "Verifying storage bucket exists" supabase db query "select id, name from storage.buckets where id = 'test-bucket';" - - name: Install Playwright browsers and dependencies - run: npx playwright install --with-deps - - name: Verify packages in Verdaccio run: | echo "Verifying @supabase/supabase-js is available in Verdaccio..." @@ -361,7 +355,7 @@ jobs: cd "$TEST_DIR" echo "registry=http://localhost:4873/" > .npmrc npm install --legacy-peer-deps - npx playwright install + npx playwright install --with-deps npm run test rm -f .npmrc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f7fe73d4..b5d3f3334 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -245,14 +245,14 @@ All pull requests must meet these requirements: Each package has its own testing requirements and infrastructure. For comprehensive testing information, see: -- **[TESTING.md](./TESTING.md)** - Overview of testing across all packages +- **[TESTING.md](./docs/TESTING.md)** - Overview of testing across all packages - **Package-specific guides** - Detailed testing instructions in each package's README: - - [`supabase-js`](../packages/core/supabase-js/README.md) - - [`auth-js`](../packages/core/auth-js/README.md) - - [`functions-js`](../packages/core/functions-js/README.md) - - [`postgrest-js`](../packages/core/postgrest-js/README.md) - - [`realtime-js`](../packages/core/realtime-js/README.md) - - [`storage-js`](../packages/core/storage-js/README.md) + - [`supabase-js`](./packages/core/supabase-js/README.md) + - [`auth-js`](./packages/core/auth-js/README.md) + - [`functions-js`](./packages/core/functions-js/README.md) + - [`postgrest-js`](./packages/core/postgrest-js/README.md) + - [`realtime-js`](./packages/core/realtime-js/README.md) + - [`storage-js`](./packages/core/storage-js/README.md) ### Quick Testing Commands @@ -360,7 +360,7 @@ We are committed to providing a welcoming and inspiring community for all. Pleas ## 📄 License -By contributing to Supabase JS Libraries, you agree that your contributions will be licensed under the [MIT License](../LICENSE). +By contributing to Supabase JS Libraries, you agree that your contributions will be licensed under the [MIT License](./LICENSE). --- diff --git a/deno.lock b/deno.lock index 6e42c9b5d..eaabe6fe3 100644 --- a/deno.lock +++ b/deno.lock @@ -135,7 +135,7 @@ "npm:typedoc@~0.27.9", "npm:typescript@~5.8.3", "npm:verdaccio@^6.0.5", - "npm:vite@7.1.5", + "npm:vite@7.1.11", "npm:vitest@^3.2.4", "npm:webpack-cli@^5.1.4" ] @@ -146,7 +146,8 @@ "dependencies": [ "npm:@supabase/node-fetch@2.6.15", "npm:jest@^28.1.3", - "npm:ts-jest@^28.0.7" + "npm:ts-jest@^28.0.7", + "npm:tslib@2.8.1" ] } }, @@ -160,7 +161,8 @@ "npm:nanoid@^3.3.1", "npm:openai@^4.52.5", "npm:testcontainers@^8.5.1", - "npm:ts-jest@^29.4.2" + "npm:ts-jest@^29.4.2", + "npm:tslib@2.8.1" ] } }, @@ -174,6 +176,7 @@ "npm:node-abort-controller@^3.0.1", "npm:prettier@^2.6.2", "npm:ts-jest@^28.0.3", + "npm:tslib@2.8.1", "npm:tstyche@^4.3.0", "npm:type-fest@^4.32.0", "npm:wait-for-localhost-cli@3", @@ -194,6 +197,7 @@ "npm:jsdom@^16.7.0", "npm:mock-socket@^9.3.1", "npm:nyc@^15.1.0", + "npm:tslib@2.8.1", "npm:web-worker@1.2.0", "npm:ws@^8.18.2" ] @@ -209,6 +213,7 @@ "npm:pretty-quick@^3.1.0", "npm:ts-jest@29", "npm:ts-loader@^9.4.2", + "npm:tslib@2.8.1", "npm:webpack-cli@^5.0.1", "npm:webpack@^5.75.0" ] diff --git a/docs/TESTING.md b/docs/TESTING.md index c4aaf569d..6c0b92f10 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -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** | ❌ No (unit tests only) | `npx nx test supabase-js` | [Testing Guide](../packages/core/supabase-js/TESTING.md) | ### Common Test Commands @@ -78,4 +78,4 @@ When adding new features or fixing bugs: 3. Update test documentation if you change testing infrastructure 4. Follow the testing patterns established in each package -For more details on contributing, see [CONTRIBUTING.md](./CONTRIBUTING.md). +For more details on contributing, see [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/package-lock.json b/package-lock.json index c7f8d5080..d007b8cb6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -56,7 +56,6 @@ "jsonwebtoken": "^9.0.0", "nx": "21.6.2", "prettier": "^3.6.2", - "rimraf": "^6.0.1", "semantic-release-plugin-update-version-in-files": "^1.1.0", "ts-node": "^10.9.1", "tslib": "^2.3.0", @@ -3393,29 +3392,6 @@ "node": ">=18" } }, - "node_modules/@isaacs/balanced-match": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/@isaacs/balanced-match/-/balanced-match-4.0.1.tgz", - "integrity": "sha512-yzMTt9lEb8Gv7zRioUilSglI0c0smZ9k5D65677DLWLtWJaXIS3CqcGyUFByYKlnUj6TkjLVs54fBl6+TiGQDQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": "20 || >=22" - } - }, - "node_modules/@isaacs/brace-expansion": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/@isaacs/brace-expansion/-/brace-expansion-5.0.0.tgz", - "integrity": "sha512-ZT55BDLV0yv0RBm2czMiZ+SqCGO7AvmOM3G/w2xhVPH+te0aKgFjmBvGlL1dH+ql2tgGO3MVrbb3jCKyvpgnxA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@isaacs/balanced-match": "^4.0.1" - }, - "engines": { - "node": "20 || >=22" - } - }, "node_modules/@isaacs/cliui": { "version": "8.0.2", "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz", @@ -28494,109 +28470,6 @@ "node": ">=0.10.0" } }, - "node_modules/rimraf": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-6.0.1.tgz", - "integrity": "sha512-9dkvaxAsk/xNXSJzMgFqqMCuFgt2+KsOFek3TMLfo8NCPfWpBmqwyNn5Y+NX56QUYfCtsyhF3ayiboEoUmJk/A==", - "dev": true, - "license": "ISC", - "dependencies": { - "glob": "^11.0.0", - "package-json-from-dist": "^1.0.0" - }, - "bin": { - "rimraf": "dist/esm/bin.mjs" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/glob": { - "version": "11.0.3", - "resolved": "https://registry.npmjs.org/glob/-/glob-11.0.3.tgz", - "integrity": "sha512-2Nim7dha1KVkaiF4q6Dj+ngPPMdfvLJEOpZk/jKiUAkqKebpGAWQXAq9z1xu9HKu5lWfqw/FASuccEjyznjPaA==", - "dev": true, - "license": "ISC", - "dependencies": { - "foreground-child": "^3.3.1", - "jackspeak": "^4.1.1", - "minimatch": "^10.0.3", - "minipass": "^7.1.2", - "package-json-from-dist": "^1.0.0", - "path-scurry": "^2.0.0" - }, - "bin": { - "glob": "dist/esm/bin.mjs" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/jackspeak": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.1.1.tgz", - "integrity": "sha512-zptv57P3GpL+O0I7VdMJNBZCu+BPHVQUk55Ft8/QCJjTVxrnJHuVuX/0Bl2A6/+2oyR/ZMEuFKwmzqqZ/U5nPQ==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "@isaacs/cliui": "^8.0.2" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/lru-cache": { - "version": "11.2.1", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.1.tgz", - "integrity": "sha512-r8LA6i4LP4EeWOhqBaZZjDWwehd1xUJPCJd9Sv300H0ZmcUER4+JPh7bqqZeqs1o5pgtgvXm+d9UGrB5zZGDiQ==", - "dev": true, - "license": "ISC", - "engines": { - "node": "20 || >=22" - } - }, - "node_modules/rimraf/node_modules/minimatch": { - "version": "10.0.3", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.0.3.tgz", - "integrity": "sha512-IPZ167aShDZZUMdRk66cyQAW3qr0WzbHkPdMYa8bzZhlHhO3jALbKdxcaak7W9FfT2rZNpQuUu4Od7ILEpXSaw==", - "dev": true, - "license": "ISC", - "dependencies": { - "@isaacs/brace-expansion": "^5.0.0" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/rimraf/node_modules/path-scurry": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.0.tgz", - "integrity": "sha512-ypGJsmGtdXUOeM5u93TyeIEfEhM6s+ljAhrk5vAvSx8uyY/02OvrZnA0YNGUrPXfpJMgI1ODd3nwz8Npx4O4cg==", - "dev": true, - "license": "BlueOak-1.0.0", - "dependencies": { - "lru-cache": "^11.0.0", - "minipass": "^7.1.2" - }, - "engines": { - "node": "20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, "node_modules/rollup": { "version": "4.50.1", "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.50.1.tgz", diff --git a/package.json b/package.json index 272104fd1..a870f14ae 100644 --- a/package.json +++ b/package.json @@ -57,7 +57,6 @@ "jsonwebtoken": "^9.0.0", "nx": "21.6.2", "prettier": "^3.6.2", - "rimraf": "^6.0.1", "semantic-release-plugin-update-version-in-files": "^1.1.0", "ts-node": "^10.9.1", "tslib": "^2.3.0", diff --git a/packages/core/auth-js/package.json b/packages/core/auth-js/package.json index 03c00b1f2..4b7d8b67c 100644 --- a/packages/core/auth-js/package.json +++ b/packages/core/auth-js/package.json @@ -26,10 +26,9 @@ "directory": "packages/core/auth-js" }, "scripts": { - "clean": "rimraf dist docs", "coverage": "echo \"run npm test\"", - "build:node18": "npm run clean && npm run build:main && npm run build:module", - "build": "npm run clean && npm run build:main && npm run build:module", + "build:node18": "npm run build:main && npm run build:module", + "build": "npm run build:main && npm run build:module", "build:main": "tsc -p tsconfig.json", "build:module": "tsc -p tsconfig.module.json", "test:auth": "npm run test:clean && npm run test:infra && npm run test:suite && npm run test:clean", diff --git a/packages/core/functions-js/package.json b/packages/core/functions-js/package.json index fc4c0dc5b..c6072f063 100644 --- a/packages/core/functions-js/package.json +++ b/packages/core/functions-js/package.json @@ -7,9 +7,8 @@ "types": "dist/module/index.d.ts", "sideEffects": false, "scripts": { - "clean": "rimraf dist docs/v2", "format": "prettier --write \"{src,test}/**/*.ts\"", - "build": "npm run clean && npm run build:main && npm run build:module", + "build": "npm run build:main && npm run build:module", "build:main": "tsc -p tsconfig.json", "build:module": "tsc -p tsconfig.module.json", "docs": "typedoc src/index.ts --out docs/v2", diff --git a/packages/core/postgrest-js/package.json b/packages/core/postgrest-js/package.json index 944775157..8e402f91b 100644 --- a/packages/core/postgrest-js/package.json +++ b/packages/core/postgrest-js/package.json @@ -33,8 +33,7 @@ "directory": "packages/core/postgrest-js" }, "scripts": { - "clean": "rimraf dist docs/v2", - "build": "npm run clean && npm run build:cjs && npm run build:esm", + "build": "npm run build:cjs && npm run build:esm", "build:cjs": "tsc -p tsconfig.json", "build:esm": "cpy wrapper.mjs dist/esm/", "build:module": "npm run build:cjs", diff --git a/packages/core/realtime-js/package.json b/packages/core/realtime-js/package.json index ea320730c..c5cd68bf2 100644 --- a/packages/core/realtime-js/package.json +++ b/packages/core/realtime-js/package.json @@ -28,9 +28,7 @@ "author": "Supabase", "license": "MIT", "scripts": { - "clean": "rimraf dist docs/v2", - "format": "prettier --write \"{src,test}/**/*.ts\"", - "build": "npm run clean && npm run format && npm run build:main && npm run build:module", + "build": "npm run build:main && npm run build:module", "build:main": "tsc -p tsconfig.json", "build:module": "tsc -p tsconfig.module.json", "test": "vitest run", diff --git a/packages/core/storage-js/package.json b/packages/core/storage-js/package.json index 2ea89da30..df9cd4fb3 100644 --- a/packages/core/storage-js/package.json +++ b/packages/core/storage-js/package.json @@ -25,8 +25,7 @@ "directory": "packages/core/storage-js" }, "scripts": { - "clean": "rimraf dist docs/v2", - "build": "npm run clean && npm run build:main && npm run build:module && npm run build:umd", + "build": "npm run build:main && npm run build:module && npm run build:umd", "build:main": "tsc -p tsconfig.json", "build:module": "tsc -p tsconfig.module.json", "build:umd": "webpack", diff --git a/packages/core/supabase-js/README.md b/packages/core/supabase-js/README.md index 9bf7a7549..eefce4214 100644 --- a/packages/core/supabase-js/README.md +++ b/packages/core/supabase-js/README.md @@ -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:postgres@127.0.0.1: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 ` | -| "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:postgres@127.0.0.1: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 - # 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. +There's a complete guide on how to set up your environment for running locally the `supabase-js` integration tests. Please refer to [TESTING.md](./TESTING.md). ### Contributing diff --git a/packages/core/supabase-js/TESTING.md b/packages/core/supabase-js/TESTING.md new file mode 100644 index 000000000..a0f93d195 --- /dev/null +++ b/packages/core/supabase-js/TESTING.md @@ -0,0 +1,279 @@ +# 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. + +## 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:node:playwright` | WebSocket browser tests | Supabase running + Playwright | +| `test:bun` | Bun runtime compatibility tests | Supabase running + Bun installed | +| `test:types` | Type testing | None | +| `test:deno` | Deno runtime compatibility tests | Supabase running + Deno installed | +| `test:expo` | React Native/Expo tests | Supabase running + dependencies updated | +| `test:next` | Next.js SSR tests | Supabase running + dependencies updated | + +## Prerequisites for All Integration Tests + +1. **Docker** must be installed and running +2. **Supabase CLI** must be installed (`brew install supabase/tap/supabase` - [for other platforms read here](https://supabase.com/docs/guides/local-development/cli/getting-started?queryGroups=platform&platform=macos#installing-the-supabase-cli)) +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:postgres@127.0.0.1:54322/postgres +# - Studio URL: http://127.0.0.1:54323 +# - Publishable key: [your-publishable-key] +# - Secret key: [your-secret-key] +# - Service role key: [your-service-role-key] # Important for some tests! + +# Return to monorepo root for running tests +cd ../../.. +``` + +4. `SUPABASE_SERVICE_ROLE_KEY` env variable exported/available + +## Unit Testing + +Run these from the root of the repo: + +```bash +# 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 + +### Exporting `SUPABASE_SERVICE_ROLE_KEY` environment variable: + +```bash +# Prerequisites: Start Supabase first +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 +``` + +To run these tests successfully, you also need to have the Supabase CLI installed. [Here are instructions](https://supabase.com/docs/guides/local-development/cli/getting-started?queryGroups=platform&platform=macos#installing-the-supabase-cli) on how you can install it. Then you can run these tests: + +```bash +# Run browser-based integration tests (requires Deno) +npx nx test:integration:browser supabase-js +``` + +## Running All Tests + +Checklist: + +- [ ] Docker running +- [ ] Supabase local instance running +- [ ] Supabase CLI installed on machine +- [ ] `SUPABASE_SERVICE_ROLE_KEY` env var available/exported + +```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 | +| -------------------------------------------- | --------------------------------------------------------------- | +| "Port 54322 already allocated" | Stop existing Supabase: `npx supabase stop --project-id ` | +| "503 Service Unavailable" for Edge Functions | Supabase not running - start with `npx supabase start` | +| Integration tests fail with auth errors | Export `SUPABASE_SERVICE_ROLE_KEY` (see Integration Testing) | + +## Platform-Specific Testing + +Platform tests verify that the SDK works correctly across different runtime environments (Node.js, Deno, Bun, Expo, Next.js). To do that, we use a tool called [Verdaccio](https://verdaccio.org/), which will run a local Node.js private proxy registry, where we will publish our `@supabase/*-js` packages, and then install them in the different environments. + +### Verdaccio Workflow + +#### Setup + +From the root of the workspace, run: + +```bash +# Terminal 1: Start local Verdaccio registry (stays running) +npx nx local-registry + +# Terminal 2: Build and publish packages to local registry +npx nx run-many --target=build --all +npx nx populate-local-registry +``` + +**Important!** + +_After you finish_ testing, _reset_ your npm registry to point to npm: + +```bash +npm config set registry https://registry.npmjs.org/ +``` + +#### Update dependencies: + +```bash +# This will run `npm i` in each of the intergration tests directories, +# fetching the locally published packages +npx nx update:test-deps supabase-js +``` + +**Tips:** + +- Keep Verdaccio running in Terminal 1 for multiple test runs +- Only rebuild/republish when you change source code +- Registry runs on `http://localhost:4873/` +- To stop Verdaccio: Ctrl+C in Terminal 1 + +### Running the tests + +#### Expo Testing (React Native) + +```bash +cd packages/core/supabase-js +npx nx test:expo +``` + +or from the root of the workspace: + +```bash +npx nx run @supabase/supabase-js:"test:expo" +``` + +### Next.js Testing (SSR) + +```bash +cd packages/core/supabase-js +# Install Playwright browsers and dependencies +npx playwright install --with-deps +# Run the tests +npx nx test:next +``` + +or from the root of the workspace: + +```bash +npx nx run @supabase/supabase-js:"test:next" +``` + +### Deno Testing + +```bash +cd packages/core/supabase-js +# Deno must be installed (https://deno.land) +npx nx test:deno +``` + +or from the root of the workspace: + +```bash +npx nx run @supabase/supabase-js:"test:deno" +``` + +## Edge Functions Testing + +The project includes Edge Functions integration tests that require a local Supabase instance to be running. + +```bash +cd packages/core/supabase-js +npx nx test:edge-functions +``` + +or from the root of the workspace: + +```bash +npx nx run @supabase/supabase-js:"test:edge-functions" +``` + +**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 +# 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 +cd packages/core/supabase-js +npx nx test:bun +``` + +or from the root of the workspace: + +```bash +npx nx run @supabase/supabase-js:"test:bun" +``` + +### WebSocket Browser Testing + +```bash +cd packages/core/supabase-js +npx nx test:node:playwright +``` + +or from the root of the workspace: + +```bash +npx nx run @supabase/supabase-js:"test:node:playwright" +``` + +**Important!** + +After you finish testing, reset your npm registry to point to npm: + +```bash +npm config set registry https://registry.npmjs.org/ +``` + +## 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. diff --git a/packages/core/supabase-js/package.json b/packages/core/supabase-js/package.json index 867194cbd..0e217b0b1 100644 --- a/packages/core/supabase-js/package.json +++ b/packages/core/supabase-js/package.json @@ -25,8 +25,7 @@ "directory": "packages/core/supabase-js" }, "scripts": { - "clean": "rimraf dist docs/v2", - "build": "npm run clean && npm run build:main && npm run build:module && npm run build:umd", + "build": "npm run build:main && npm run build:module && npm run build:umd", "build:main": "tsc -p tsconfig.json", "build:module": "tsc -p tsconfig.module.json", "build:umd": "webpack --env mode=production", @@ -38,9 +37,12 @@ "test:integration": "jest --runInBand --detectOpenHandles test/integration.test.ts", "test:integration:browser": "deno test --allow-all test/integration.browser.test.ts", "test:edge-functions": "cd test/deno && npm run test:edge-functions", + "test:deno": "cd test/deno && npm run test", "test:watch": "jest --watch --verbose false --silent false", "test:node:playwright": "cd test/integration/node-browser && npm install && cp ../../../dist/umd/supabase.js . && npm run test", "test:bun": "cd test/integration/bun && bun install && bun test", + "test:expo": "cd test/integration/expo && npm test", + "test:next": "cd test/integration/next && npm test", "test:types": "tsd --files test/types/*.test-d.ts && jsr publish --dry-run --allow-dirty", "docs": "typedoc --entryPoints src/index.ts --out docs/v2", "docs:json": "typedoc --entryPoints src/index.ts --json docs/v2/spec.json --excludeExternals", diff --git a/packages/core/supabase-js/supabase/.temp/cli-latest b/packages/core/supabase-js/supabase/.temp/cli-latest index 2213dd2c1..8cbd83732 100644 --- a/packages/core/supabase-js/supabase/.temp/cli-latest +++ b/packages/core/supabase-js/supabase/.temp/cli-latest @@ -1 +1 @@ -v2.51.0 \ No newline at end of file +v2.53.6 \ No newline at end of file diff --git a/packages/core/supabase-js/test/integration/next/tsconfig.json b/packages/core/supabase-js/test/integration/next/tsconfig.json index 32d8de305..7792cbfbd 100644 --- a/packages/core/supabase-js/test/integration/next/tsconfig.json +++ b/packages/core/supabase-js/test/integration/next/tsconfig.json @@ -1,7 +1,11 @@ { "compilerOptions": { "target": "ES2017", - "lib": ["dom", "dom.iterable", "esnext"], + "lib": [ + "dom", + "dom.iterable", + "esnext" + ], "allowJs": true, "skipLibCheck": true, "strict": true, @@ -12,7 +16,7 @@ "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, - "jsx": "preserve", + "jsx": "react-jsx", "incremental": true, "plugins": [ { @@ -20,9 +24,20 @@ } ], "paths": { - "@/*": ["./*"] + "@/*": [ + "./*" + ] } }, - "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"], - "exclude": ["node_modules", "test/types/*.test-d.ts"] + "include": [ + "next-env.d.ts", + "**/*.ts", + "**/*.tsx", + ".next/types/**/*.ts", + ".next/dev/types/**/*.ts" + ], + "exclude": [ + "node_modules", + "test/types/*.test-d.ts" + ] }