Skip to main content

Source: ocean/docs/LOCAL_TESTING_README.md | ✏️ Edit on GitHub

Local Testing Environment

This directory contains documentation and guides for setting up and using the local Supabase testing environment.

Overview​

While we follow a cloud-first testing strategy (ADR-014), we maintain a local testing environment for specific use cases:

  • Database Development: Trigger and function development
  • Migration Testing: Safe schema change testing
  • Bug Reproduction: Debugging production issues locally
  • RLS Policy Testing: Testing Row Level Security policies

Quick Start​

# 1. Ensure Docker is running
docker ps

# 2. Start local Supabase
supabase start

# 3. Apply migrations
supabase db reset --no-seed

# 4. Run debug scripts
pnpm debug:user "test@example.com" "Test Org"

Documentation​

Setup & Configuration​

Debug Scripts​

  • /scripts/debug-user-creation.js - Interactive user creation debugger
  • /scripts/debug-user-creation.sql - SQL queries for troubleshooting
  • /scripts/test-local-user-creation.js - Automated test scenarios

Environment Configuration​

  • .env.local.test - Local environment variables (do not commit)
  • supabase/config.toml - Local Supabase configuration

Common Tasks​

Debug a Production Issue​

  1. Get error details from production logs
  2. Start local environment
  3. Reproduce issue with debug scripts
  4. Fix and test locally
  5. Deploy fix to production

Test a Migration​

  1. Create migration file
  2. Apply to local database
  3. Test functionality
  4. Test rollback scenario
  5. Apply to cloud environments

Verify RLS Policies​

  1. Create test users with different roles
  2. Test data access patterns
  3. Verify security boundaries
  4. Document expected behavior

Best Practices​

  1. Always test in cloud before deploying
  2. Reset database between test sessions
  3. Document findings in debug scripts
  4. Keep local in sync with production schema

Troubleshooting​

Common Issues​

  • Port conflicts: Stop other services using ports 54321-54324
  • Migration errors: Check for duplicate timestamps
  • Auth errors: Ensure using correct service keys
  • Connection refused: Check Docker containers are running

Getting Help​

  1. Check the LOCAL_TESTING_SETUP.md guide
  2. Review Supabase CLI docs
  3. Ask in team Slack channel
  4. Check Docker logs: docker logs supabase_db_ocean