Local Development and Testing Guide¶

Complete reference for setting up, running, and testing the Microlearning Platform API locally. This guide covers the local environment used for both day-to-day development and integration testing.

Table of Contents¶

Architecture Overview
Prerequisites
Initial Setup (one-time)
Local Environment
Serving Edge Functions
Seeding Test Data
Running Tests
Common Workflows
Troubleshooting

1. Architecture Overview¶

The platform runs as Supabase Edge Functions (Deno + Hono). Locally, Supabase runs a full stack inside Docker (PostgreSQL, Auth, REST API, Studio) and serves your edge functions via supabase functions serve.

Local Environment¶

A single Supabase instance runs on the standard ports:

Service	Port	Purpose
API	54321	REST / Edge Functions endpoint
Database	54322	PostgreSQL
Studio	54323	Supabase Studio UI
Inbucket	54324	Local email (auth emails)
SMTP	54325	SMTP relay
POP3	54326	POP3 relay

Project Root
├── supabase/              # Supabase config and migrations
│   ├── config.toml        # Supabase configuration
│   └── migrations/        # SQL migration files
│
├── functions/             # Edge function source
├── .env.local             # Local environment variables
└── .env.staging           # Staging environment variables

2. Prerequisites¶

Install the following before starting:

Tool	Version	Install
Deno	>= 2.0	`curl -fsSL https://deno.land/install.sh \\| sh`
Supabase CLI	>= 2.0	`brew install supabase/tap/supabase`
Docker	Desktop or Colima	docker.com / `brew install colima`

Verify your setup:

deno --version
supabase --version
docker info

macOS note: If you are using Colima instead of Docker Desktop, see docs/troubleshooting/COLIMA_FIX.md for known issues and fixes.

3. Initial Setup (one-time)¶

3.1 Clone and enter the repository¶

git clone <repo-url> core
cd core

3.2 Create environment files¶

cp .env.local.example .env.local

The default .env.local.example ships with the standard Supabase local dev keys -- no changes required for basic local development.

4. Local Environment¶

The local environment is used for both day-to-day feature development and integration testing. It runs on ports 54321-54326.

4.1 Start¶

deno task local:start

On first run this pulls Docker images and applies all migrations (~1-2 minutes). Subsequent starts are faster.

URLs after startup:

Service	URL
API / Functions	`http://127.0.0.1:54321/functions/v1/<fn>`
REST API	`http://127.0.0.1:54321/rest/v1/`
Studio	`http://127.0.0.1:54323`
Database	`postgresql://postgres:postgres@127.0.0.1:54322/postgres`
Email (Inbucket)	`http://127.0.0.1:54324`

4.2 Stop¶

deno task local:stop

4.3 Reset database¶

Drops all data and re-applies every migration from scratch:

deno task local:reset

Use this when you add a new migration and want a clean slate.

4.4 Check status¶

deno task local:status

5. Serving Edge Functions¶

Supabase serves edge functions automatically when you run supabase start. The scripts below provide hot-reload serving for active development with explicit environment variable injection.

5.1 Functions (hot-reload)¶

Serves all functions against the local environment (.env.local):

deno task function:serve

With verbose debug logging:

deno task function:serve:verbose

Functions served: search, graph, content, home, user, metadata, snapshots

Access pattern: http://127.0.0.1:54321/functions/v1/<function-name>/<path>

Examples:

http://127.0.0.1:54321/functions/v1/graph/domains
http://127.0.0.1:54321/functions/v1/content/sparks/self-attention
http://127.0.0.1:54321/functions/v1/home/home
http://127.0.0.1:54321/functions/v1/user/me
http://127.0.0.1:54321/functions/v1/metadata/

6. Seeding Test Data¶

6.1 Test users¶

Creates four test users with specific roles (free, pro, premium, admin), test journeys, and learning events:

deno task local:seed

Test user credentials after seeding:

Role	Email	Password
Free	`free@test.musingly.ai`	`Test1234!`
Pro	`pro@test.musingly.ai`	`Test1234!`
Premium	`premium@test.musingly.ai`	`Test1234!`
Admin	`admin@test.musingly.ai`	`Test1234!`

Credentials are also written to .env.local automatically by the seed script.

6.2 Fixture data¶

Seeds additional domain/trail/concept/spark/beacon fixture data used by specific test suites:

deno task local:seed:data

6.3 Catalog journeys¶

Seeds catalog journey data for the journey-catalog endpoint tests:

deno task local:seed:catalog

6.4 Full setup (reset + all seeds)¶

The recommended setup before running the full test suite:

# Reset DB + seed users
deno task local:setup

6.5 Content seeding¶

# Import a content bundle
deno task content:import

# Seed curriculum data
deno task content:seed

7. Running Tests¶

7.1 Unit tests¶

Tests for source-level utilities in src/:

deno task test

7.2 E2E integration tests¶

All E2E tests run against the local environment (http://127.0.0.1:54321). The local environment must be running and seeded before executing any of these.

Quick setup before running:

deno task local:start
deno task local:setup

Run all E2E tests¶

deno task test:e2e:all

Run by suite¶

Suite	Command	Test Files
Graph API	`deno task test:e2e:graph`	`tests/e2e/graph/`
Catalog API	`deno task test:e2e:catalog`	`tests/e2e/catalog/`
Content API	`deno task test:e2e:content`	`tests/e2e/content/`
Me (User) API	`deno task test:e2e:me`	`tests/e2e/me/`
Home API	`deno task test:e2e:home`	`tests/e2e/home/`
Search API	`deno task test:e2e:search`	`tests/e2e/search/`
Metadata API	`deno task test:e2e:metadata`	`tests/e2e/metadata/`
Snapshots	`deno task test:e2e:snapshots`	`tests/e2e/snapshots/`
Protection / Security	`deno task test:e2e:protection`	`tests/e2e/protection/`
Health check only	`deno task test:e2e:graph:health`	`tests/e2e/graph/health.test.ts`

Graph suite -- individual test files¶

tests/e2e/graph/
├── health.test.ts           -- Health check for all edge functions
├── domains.test.ts          -- /domains/* function
├── concepts.test.ts         -- /concepts/* function
├── sparks.test.ts           -- /sparks-meta/* function
├── beacons.test.ts          -- /beacons/* function
├── explore.test.ts          -- /explore/* function
├── recommendations.test.ts  -- /recommendations/* function
├── learning-path.test.ts    -- /learning-path/* function
├── breadcrumb.test.ts       -- /breadcrumb/* function
└── links.test.ts            -- /links/* function

Me suite -- individual test files¶

tests/e2e/me/
├── profile.test.ts     -- GET /me
├── stats.test.ts       -- GET /me/stats
├── milestones.test.ts  -- GET /me/milestones
├── journeys.test.ts    -- GET/POST /me/journeys, /me/journeys/{id}
└── events.test.ts      -- GET/POST /me/events, /me/events/{sparkId}

7.3 Coverage report¶

deno task test:e2e:coverage

Produces a coverage.lcov file in the project root.

7.4 CI mode (JUnit XML output)¶

For CI systems that consume JUnit XML:

deno task test:e2e:ci
# Outputs: test-results.xml

deno task test:e2e:granular:ci
# Outputs: test-results-granular.xml

7.5 Smoke tests¶

Quick sanity checks against a running environment (no test data required):

deno task smoke:local      # Against http://127.0.0.1:54321
deno task smoke:staging    # Against staging
deno task smoke:production # Against production

7.6 Protection / security tests¶

Validates authentication enforcement, auth bypass prevention, and authorization boundaries:

deno task test:e2e:protection

# Or the older script-based version
deno task test:protection
deno task test:protection:verbose

8. Common Workflows¶

New developer setup (first time)¶

# 1. Start local environment
deno task local:start

# 2. Configure .env.local (usually works with defaults)
cp .env.local.example .env.local

# 3. Serve functions with hot-reload
deno task function:serve

# API now accessible at http://127.0.0.1:54321/functions/v1/

Full E2E test run¶

# Terminal 1: Start local environment
deno task local:start

# Terminal 1 (after it's up): Reset DB and seed all test data
deno task local:setup

# Terminal 2: Run all integration tests
deno task test:e2e:all

Add a new migration¶

# Create migration file
supabase migration new my_new_feature

# Apply to local (resets test data -- re-seed after)
deno task local:reset
deno task local:setup

Get a JWT token for manual API testing¶

# Test token (local environment test user)
deno task token:test

# Production token
deno task token:production

Refresh the OpenAPI spec¶

deno task openapi:offline

Writes to mcp/openapi.json. Run this after adding or modifying any route.

CI validation (lint + format + type check)¶

deno task ci:validate

Full CI pipeline locally¶

deno task ci:full        # ci:validate + test:e2e:all
deno task ci:simulate    # local:setup + function:serve + test:e2e:ci (JUnit)

Set up git hooks (pre-commit, pre-push)¶

deno task ci:setup-hooks

9. Troubleshooting¶

`supabase start` reports "already running" but tests or serve fail¶

The Docker containers are up but the REST API isn't responding. The local:start script detects this and prints the current status and exits cleanly. Run the status command to see what's actually running:

supabase status

If services are actually stuck, stop and restart:

deno task local:stop && deno task local:start

Port already in use¶

Another Supabase instance is using the port (possibly a default supabase start without a workdir):

# Check what's running
supabase status

# Stop the instance
supabase stop

# Then start again
deno task local:start

Tests fail with 401 / authentication errors¶

The test users haven't been seeded, or the .env.local keys are missing/wrong:

# Re-seed users
deno task local:seed

# Verify .env.local has the correct keys
supabase status
# Copy anon key and service_role key into .env.local

Tests fail with 404 / empty data responses¶

The database is empty or the seed data wasn't applied:

deno task local:setup     # Reset + seed users + seed fixture data

Database connection refused¶

Supabase isn't running. Start the local environment:

deno task local:start    # DB on port 54322

Direct database access (psql)¶

psql postgresql://postgres:postgres@127.0.0.1:54322/postgres

Docker not starting on macOS (Colima)¶

See docs/troubleshooting/COLIMA_FIX.md for the recommended fix, or docs/troubleshooting/SWITCH_TO_DOCKER_DESKTOP.md to migrate to Docker Desktop.

Quick Reference¶

Environment URLs¶

Environment	API Base	Studio	Database
Local	`http://127.0.0.1:54321/functions/v1`	`http://127.0.0.1:54323`	`postgresql://postgres:postgres@127.0.0.1:54322/postgres`

Edge Function Paths¶

Function	Local URL	Auth
`graph`	`http://127.0.0.1:54321/functions/v1/graph/*`	Optional
`content`	`http://127.0.0.1:54321/functions/v1/content/*`	Optional
`home`	`http://127.0.0.1:54321/functions/v1/home`	Optional
`search`	`http://127.0.0.1:54321/functions/v1/search/*`	Required
`metadata`	`http://127.0.0.1:54321/functions/v1/metadata`	Public
`snapshots`	`http://127.0.0.1:54321/functions/v1/snapshots/*`	Required
`user`	`http://127.0.0.1:54321/functions/v1/user/me/*`	Required
`journeys`	`http://127.0.0.1:54321/functions/v1/journeys/*`	Optional
`journey-catalog`	`http://127.0.0.1:54321/functions/v1/journey-catalog/*`	Optional
`domains`	`http://127.0.0.1:54321/functions/v1/domains/*`	Public
`concepts`	`http://127.0.0.1:54321/functions/v1/concepts/*`	Public
`health`	`http://127.0.0.1:54321/functions/v1/health`	Public

Task Cheat Sheet¶

# -- SETUP -----------------------------------------------------------------
deno task ci:setup-hooks          # Install git hooks

# -- LOCAL ENVIRONMENT -----------------------------------------------------
deno task local:start             # Start local Supabase
deno task local:stop              # Stop local Supabase
deno task local:reset             # Reset local database
deno task local:status            # Show local status
deno task local:seed              # Seed test users
deno task local:seed:data         # Seed fixture data
deno task local:seed:catalog      # Seed catalog journeys
deno task local:setup             # Reset + seed users

# -- SERVING FUNCTIONS -----------------------------------------------------
deno task function:serve          # Hot-reload (debug logging)
deno task function:serve:verbose  # Hot-reload (verbose)

# -- TESTING ---------------------------------------------------------------
deno task test                    # Unit tests
deno task test:e2e:all            # All E2E integration tests
deno task test:e2e:graph          # Graph API suite
deno task test:e2e:content        # Content API suite
deno task test:e2e:catalog        # Catalog API suite
deno task test:e2e:user           # User/Me API suite
deno task test:e2e:snapshots      # Snapshots suite
deno task test:e2e:protection     # Security / auth tests
deno task test:e2e:granular       # Granular function tests
deno task test:e2e:granular:health # Health check only
deno task test:e2e:coverage       # With LCOV coverage report
deno task test:e2e:ci             # JUnit XML output (CI)

# -- SMOKE TESTS -----------------------------------------------------------
deno task smoke:local             # Quick smoke vs. local
deno task smoke:staging           # Quick smoke vs. staging

# -- CI --------------------------------------------------------------------
deno task ci:validate             # Lint + format check + type check
deno task ci:full                 # Validate + full E2E test run
deno task ci:simulate             # Full CI pipeline locally

# -- DEVELOPMENT -----------------------------------------------------------
deno task check                   # Type check
deno task lint                    # Lint
deno task fmt                     # Format
deno task openapi:offline         # Regenerate OpenAPI spec
deno task token:test              # Get local test JWT token
deno task token:production        # Get production JWT token

Topic	Document
Platform concepts & API usage	getting-started/DEVELOPER_GUIDE.md
API reference (all endpoints)	api/README.md
E2E test framework internals	testing/INTEGRATION_TESTING_GUIDE.md
Environment variables reference	configuration/MULTI_ENV_CONFIGURATION.md
Authentication	authentication/AUTHENTICATION_GUIDE.md
Database setup & migrations	database/DATABASE_SETUP.md
Data seeding reference	database/DATA_HYDRATION_AND_SEEDING.md
Deployment	deployment/DEPLOYMENT_GUIDE.md
Troubleshooting	troubleshooting/TROUBLESHOOTING.md
Journeys API	JOURNEYS_API.md