Edge and API Testing Guide

​

Prerequisites

• Supabase CLI — Install globally or use npx supabase from the project root. See Install the Supabase CLI.
• Docker — Required for supabase start (local Postgres, Auth, etc.).
• Deno (optional) — For running Edge Function unit tests (deno test). Install from deno.land if you want to run npm run test:functions locally.

​

Full local stack

1. Start the local Supabase stack (Postgres, Auth, Realtime, Storage, etc.):
   npx supabase start
   
   Or: npm run supabase:start (if you use the npm script). Get the API URL and anon key with:
   npx supabase status
   
2. Serve Edge Functions with hot-reload:
   npm run supabase:functions:serve
   
   This runs the hardened wrapper scripts/setup/serve-functions.sh (not bare supabase functions serve). The wrapper is safe to run from any checkout — root or a git worktree — and fixes the two recurring multi-agent failure modes:
   • Worktree basename trap: the Supabase CLI names its Docker project after the working-directory basename, so a bare supabase functions serve from …/.claude/worktrees/<slug> targets a nonexistent <slug> stack and fails. The wrapper resolves the root checkout (via the git common-dir) and passes --workdir <root>, so every worktree shares the one canonical stack on :54321.
   • Edge-runtime name conflict: the CLI does not reap its supabase_edge_runtime_<project> container on an unclean exit, so the next serve dies with “container name is already in use”. The wrapper force-removes that one container first (it is recreated fresh every serve; the persistent db/kong/etc. stack is untouched). It also probes the gateway and reuses an already-running serve instead of starting a second one (SERVE_NO_REUSE=1 forces a fresh serve).

   ⚠️ Because the shared stack belongs to the root checkout, the wrapper serves root’s supabase/functions, not the functions you edited in a worktree. If you changed an edge function in a worktree, get it into root first (commit + check root out to your branch, or copy the changed supabase/functions/<fn> dirs into root) — the wrapper prints a loud warning when it detects this case. Omitting a function name serves all functions; hot-reload is on by default.

3. Invoke locally:
   • From the app: Point VITE_SUPABASE_URL at http://localhost:54321 and use supabase.functions.invoke('my-func', { body }).
   • From terminal (cURL):
     curl -i -X POST 'http://localhost:54321/functions/v1/my-func' \
       -H 'Authorization: Bearer <anon_key>' \
       -H 'Content-Type: application/json' \
       -d '{"key": "value"}'
     
     Use the anon key from npx supabase status.

​

Local env for Edge/API

• VITE_SUPABASE_URL=http://localhost:54321
• VITE_SUPABASE_PUBLISHABLE_KEY=<anon key from npx supabase status>

npx supabase status

​

Debugging with breakpoints

1. Start functions in inspect mode:
   npm run supabase:functions:serve:inspect
   
   This runs supabase functions serve --inspect-mode brk. Execution pauses on the first line when a request hits a function.
2. Attach Chrome DevTools:
   • Open Chrome and go to chrome://inspect.
   • Click Configure and add target 127.0.0.1:8083.
   • Under “Remote Target”, click Open dedicated DevTools for Node.
3. Trigger a function (e.g. cURL or the app). Execution will pause so you can set breakpoints, step through code, and inspect variables.

​

Deno unit tests

• supabase/functions/<name>/index.test.ts
• supabase/functions/<name>/index_test.ts

• generate-templated-pdf and similar: Set VITE_SUPABASE_URL=http://localhost:54321 and VITE_SUPABASE_PUBLISHABLE_KEY=<anon from npx supabase status>.
• hr-encrypt-bank-account: Set SUPABASE_URL=http://localhost:54321 (and optionally TEST_AUTH_TOKEN for authenticated tests).

npm run test:functions

​

API Gateway parity (local vs production)

​

Logs

• Local: Function stdout/stderr appear in the terminal where you ran supabase functions serve.
• Production: Use the Supabase Dashboard (Edge Function logs) or the CLI. Use structured logging in code (e.g. logger.info with correlationId, no PHI) for easier filtering.

​

Integration tests against local

1. Set VITE_SUPABASE_URL=http://localhost:54321 and SUPABASE_SERVICE_ROLE_KEY (and VITE_SUPABASE_PUBLISHABLE_KEY if tests use anon client). Get keys from npx supabase status after supabase start.
2. Run npm run supabase:functions:serve in a separate terminal.
3. Run integration tests, e.g.:
   npm run test:integration
   
   Or a subset, e.g.:
   npm run test:integration -- tests/integration/fa/fa-handle-bank-balance-updated.test.ts
   

​

Fast prod checks

• Dashboard: Use the Test tab for each function in the Supabase Dashboard to try different headers, payloads, and JWTs.
• cURL:
  curl -X POST 'https://<project-ref>.supabase.co/functions/v1/<func>' \
    -H 'Authorization: Bearer <ANON_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{"key": "value"}'
  

​

Troubleshooting checklist

​

See also

• TESTING_SETUP_AND_RUN.md — All test types and env vars
• EDGE_FUNCTIONS.md — Function reference, deployment, and JWT config
• SUPABASE_CLI_LOCAL_WORKFLOW.md — Migrations and local DB workflow