Testing

Testing Levels

Level	What	Tool
Branch preview	Full-stack functional test via CF Pages preview URL	Cloudflare Pages
Unit tests	Isolated function/module tests	Vitest
Integration tests	Multi-tenant isolation, API route behavior	Vitest + Neon test DB
Type checking	Compile-time type safety	npx astro check

Branch Preview Workflow

The primary testing mechanism is Cloudflare Pages branch previews. Every feature branch gets a live, fully functional deployment:

# 1. Create a feature branch
git checkout -b feature/add-csv-export

# 2. Push — Pages automatically builds and deploys a preview
git push origin feature/add-csv-export
# → https://convertella-admin-feature-add-csv-export.pages.dev

# 3. Test the feature end-to-end in the preview URL:
#    - OTP login flow
#    - CSV export downloads
#    - Data shows correctly in tables
#    - No console errors

# 4. Fix issues → push again → preview updates automatically

# 5. Merge to default branch → production deploy

# 6. Delete branch → preview deactivated automatically

What to test in a branch preview:

• Full authentication flow (OTP send → receive email → enter code → session created)
• Data load (units, leads, agents, documents render correctly)
• Mutations (create/update/delete operations via CRM UI)
• Cross-feature impact (does your change break another page?)
• Mobile responsiveness (resize browser to mobile widths)
• All before merge to the default branch

Limitations to be aware of:

• Previews share the testing Neon database — test data collisions can occur between branches
• OTP emails go to real email addresses — use your own inbox, not customer emails
• Cloudflare API calls (R2 uploads, custom hostnames) execute against testing resources

Unit Tests

Standard Vitest suites alongside source code:

npm run test              # Run all tests
npx vitest run src/lib/otp/__tests__/hash.test.ts  # Single test file
npx vitest --watch        # Watch mode during development

Test File	What It Tests
tests/multi-tenant-isolation.test.ts	Tenant A cannot read tenant B’s data
tests/tenant-invariants.test.ts	Tenant context always set in middleware
tests/api-favorites-route.test.ts	Favorites API auth-required scenarios
src/lib/otp/__tests__/hash.test.ts	OTP SHA-256 + pepper hashing
src/lib/otp/__tests__/normalize.test.ts	Phone/email E.164 normalization

Smoke Test

npm run test:smoke

A headless browser test that verifies the buyer portal loads and renders without errors.

Type Checking

npx astro check          # Full project type check
npx tsc --noEmit         # TypeScript compiler check

Both are run before any commit or deploy.

Testing Conventions

1. Test files are placed alongside source code in __tests__/ directories or in the top-level tests/ folder
2. Naming follows *.test.ts convention
3. Database tests use the testing database (same as local dev)
4. No test data leaks between test runs — beforeEach cleanup ensures isolation
5. Integration tests verify tenant isolation at the API level