xtablo-source/apps/api/docs/VITEST_MIGRATION.md

Vitest Migration Summary

Overview

Successfully migrated the test suite from Node.js built-in test runner to Vitest with global setup/teardown for database initialization.

Changes Made

1. Dependencies Added

pnpm add -D vitest@latest @vitest/ui@latest

• vitest: Modern test runner with better DX
• @vitest/ui: Visual test runner UI

2. Configuration Files Created

vitest.config.ts

• Test environment: Node.js
• Global setup/teardown hooks configured
• Test files: src/__tests__/**/*.test.ts
• Single fork mode for consistency
• Timeout: 30s per test, 60s per hook

src/__tests__/globalSetup.ts

• Exports setup() function that runs once before all tests
  • Creates test database and users
  • Generates access tokens
• Exports teardown() function that runs once after all tests
  • Cleans up all test data

src/__tests__/setup.ts

• Per-test-file setup (currently minimal)
• Can be extended for per-file setup needs

3. Test Files Converted

All test files migrated from Node.js test API to Vitest API:

Import Changes

// Before
import assert from "node:assert/strict";
import { describe, it } from "node:test";

// After
import { describe, it, expect } from "vitest";

Assertion Changes

// Before
assert.strictEqual(actual, expected);
assert.ok(value);

// After
expect(actual).toBe(expected);
expect(value).toBeTruthy();

Files Converted (14 files)

• auth/auth.test.ts
• auth/maybeAuth.test.ts
• middlewares/middlewares.test.ts
• routes/user.test.ts
• routes/stripe.test.ts
• routes/tablo.test.ts
• routes/tasks.test.ts
• routes/public.test.ts
• routes/invite.test.ts
• routes/tablo_data.test.ts
• routes/notes.test.ts
• helpers/auth.test.ts
• helpers/uriComponent.test.ts
• helpers/slots.test.ts

4. Package.json Scripts Updated

{
  "test": "NODE_ENV=test vitest run",
  "test:watch": "NODE_ENV=test vitest",
  "test:ui": "NODE_ENV=test vitest --ui"
}

Benefits of Vitest

1. Better Global Setup: Proper global setup/teardown hooks that run once for entire test suite
2. Faster Test Runs: Smart test running with better parallelization
3. Better DX:
   • Instant feedback with watch mode
   • Visual UI for debugging tests
   • Better error messages
4. Modern API: Expect-style assertions that are more readable
5. Vite Integration: Can leverage Vite's module resolution if needed

Test Database Setup

The global setup now properly:

1. Creates 3 test users before any tests run
2. Populates all main database tables with test data
3. Generates access tokens for each user
4. Makes test data available via testUtils
5. Cleans up everything after all tests complete

Running Tests

# Run all tests once
npm test

# Watch mode - re-runs on changes
npm run test:watch

# Visual UI
npm run test:ui

Next Steps

To run tests successfully, ensure:

1. Supabase is running: supabase start

2. Environment variables are set in .env.test:

   • SUPABASE_URL
   • SUPABASE_SERVICE_ROLE_KEY
   • SUPABASE_CONNECTION_STRING
   • Other required env vars

3. Database schema is up to date:

   supabase db reset
   

Troubleshooting

"Invalid API key" error

• Check .env.test has correct SUPABASE_SERVICE_ROLE_KEY
• Ensure Supabase local is running
• Verify SUPABASE_URL points to the correct instance

Test data not available

• Check that global setup completed successfully
• Look for errors in the global setup output
• Verify database connection is working

Tests failing after migration

• Check assertion syntax has been converted correctly
• Verify imports use Vitest instead of Node test
• Look for async/await issues in test setup

Documentation

See src/__tests__/README.md for detailed documentation on:

• Test data structure
• How to use test utilities
• Example test patterns
• File organization