Testing

Overview

folksbase uses two testing layers:

Vitest for unit tests — fast, focused tests for business logic
Playwright for E2E tests — browser-based tests against the full running app

Unit Tests (Vitest)

Where Tests Live

Tests go in __tests__/ directories next to the file being tested:

src/
├── services/
│   ├── contacts.service.ts
│   └── __tests__/
│       └── contacts.service.test.ts
├── repositories/
│   ├── contacts.repository.ts
│   └── __tests__/
│       └── contacts.repository.test.ts

Running Tests

# Run all unit tests
pnpm test

# Run tests for a specific package
pnpm --filter @folksbase/api test

# Run a single test file
pnpm --filter @folksbase/api test src/services/__tests__/csv-ai.service.test.ts

Writing Tests

Mock all external dependencies. Tests should be fast and isolated — no real database, Redis, or API calls.

import { describe, it, expect, vi, beforeEach } from "vitest";

// Mock external dependencies
vi.mock("@folksbase/db");
vi.mock("@/lib/redis.js");

describe("contacts.service", () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it("creates a contact with normalized email", async () => {
    // Arrange
    const mockCreate = vi.fn().mockResolvedValue({ id: "abc", email: "test@example.com" });
    // ... setup mocks

    // Act
    const result = await createContact({ email: "TEST@Example.COM" });

    // Assert
    expect(result.email).toBe("test@example.com");
    expect(mockCreate).toHaveBeenCalledOnce();
  });
});

What to Test

Business logic in services (happy path + error cases)
Repository query behavior (mocked DB responses)
Edge cases: empty inputs, missing data, concurrent operations
Error handling: verify errors propagate correctly

What NOT to Test

Drizzle query builder syntax — trust the ORM
Zod schema validation — trust Zod
Framework internals — trust Next.js and Hono

Test Configuration

Vitest config lives in each app’s vitest.config.ts. The API config sets up path aliases so imports like @/lib/logger.js and @folksbase/db resolve correctly in tests:

resolve: {
  alias: {
    "@": resolve(__dirname, "src"),
    "@folksbase/db": resolve(__dirname, "../../packages/db/src/index.ts"),
    "@folksbase/types": resolve(__dirname, "../../packages/types/src/index.ts"),
  },
},

Important: Use Valid UUIDs in Tests

Route param validators enforce UUID format. Always use valid UUIDs in test fixtures, not arbitrary strings:

// ❌ Will fail validation
const contactId = "c-1";

// ✅ Use a real UUID
const contactId = "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11";

E2E Tests (Playwright)

Where Tests Live

E2E tests live in apps/web/e2e/ with config in apps/web/playwright.config.ts.

Test Projects

Playwright is configured with three projects:

Project	Purpose
`setup`	Authenticates once, stores session in `e2e/.auth/user.json`
`no-auth`	Runs `auth.spec.ts` with empty storage (tests login flow)
`chromium`	Runs all other specs with stored auth (depends on `setup`)

Running E2E Tests

# Run all E2E tests
pnpm --filter @folksbase/web e2e

# Run with Playwright UI (interactive mode)
pnpm --filter @folksbase/web e2e:ui

# Run a single spec
pnpm --filter @folksbase/web exec playwright test e2e/auth.spec.ts --project=no-auth

Environment Variables

E2E tests require real Supabase credentials:

Variable	Purpose
`E2E_USER_EMAIL`	Test user email for authentication
`E2E_USER_PASSWORD`	Test user password
`PLAYWRIGHT_BASE_URL`	App URL (defaults to `http://localhost:3000`)

These are defined in apps/web/.env.example and read via process.env in the Playwright config.

Test Files

The E2E suite covers: auth, dashboard, navigation, contacts, imports, exports, tags, settings, and accessibility.

CI Integration

In CI, E2E tests run against the Vercel preview URL generated for each PR. The PLAYWRIGHT_BASE_URL is overridden to point to the preview deployment.

Storybook

UI components are documented with Storybook 8. Stories live alongside their components as *.stories.tsx files.

pnpm --filter @folksbase/web storybook        # Run locally on port 6006
pnpm --filter @folksbase/web build-storybook  # Build static output

When adding a new UI component, include a story file covering its variants and states. Storybook auto-deploys to Netlify on pushes to main when component or config files change.

Getting Started

Features

Architecture

Background Jobs

API

Deployment

Contributing

Overview

Unit Tests (Vitest)

Where Tests Live

Running Tests

Writing Tests

What to Test

What NOT to Test

Test Configuration

Important: Use Valid UUIDs in Tests

E2E Tests (Playwright)

Where Tests Live

Test Projects

Running E2E Tests

Environment Variables

Test Files

CI Integration

Storybook

​Overview

​Unit Tests (Vitest)

​Where Tests Live

​Running Tests

​Writing Tests

​What to Test

​What NOT to Test

​Test Configuration

​Important: Use Valid UUIDs in Tests

​E2E Tests (Playwright)

​Where Tests Live

​Test Projects

​Running E2E Tests

​Environment Variables

​Test Files

​CI Integration

​Storybook

Overview

Unit Tests (Vitest)

Where Tests Live

Running Tests

Writing Tests

What to Test

What NOT to Test

Test Configuration

Important: Use Valid UUIDs in Tests

E2E Tests (Playwright)

Where Tests Live

Test Projects

Running E2E Tests

Environment Variables

Test Files

CI Integration

Storybook