Tests

Test failures provide specific diagnostic information. Check error messages, verify test environment configuration, and ensure mocks are properly set up.

Module Resolution Errors

Symptoms: Tests fail during import with Cannot find module '@workspace/auth'.

Diagnosis: Workspace packages not built or Vitest path resolution not configured.

Solution:

Build workspace packages before testing:

pnpm build
pnpm test

Verify vitest.config.mts includes tsconfigPaths() plugin:

import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";
import { defineConfig } from "vitest/config";

export default defineConfig({
  plugins: [react(), tsconfigPaths()], // Required for @workspace/* imports
  test: {
    globals: true,
    environment: "jsdom",
  },
});

Wrong Test Environment

Symptoms: API route tests fail with document is not defined or window is not defined.

Diagnosis: Test using wrong environment (jsdom vs node).

Solution:

API routes, middleware, and server actions need Node environment:

/** @vitest-environment node */

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

Components and hooks use jsdom (default, no annotation needed).

Mock Not Working

Symptoms: Tests fail because mocked functions not being called or returning wrong values.

Diagnosis: Mock defined after import or not properly reset between tests.

Solution:

Define mocks before importing module:

import { vi } from "vitest";

// ✅ Mock BEFORE import
vi.mock("@workspace/auth/server", () => ({
  getCurrentSession: vi.fn(),
}));

// Now import the module that uses auth
import { MyComponent } from "../my-component";

test("works", () => {
  vi.mocked(getCurrentSession).mockResolvedValue({ user: {...} });
  // Test code
});

Reset mocks between tests:

import { beforeEach, vi } from "vitest";

beforeEach(() => {
  vi.clearAllMocks();
});

TestServicesProvider Missing

Symptoms: Components throw useServices must be used within a ServicesProvider.

Diagnosis: Component using useServices() but not wrapped with provider in test.

Solution:

import { render } from "@testing-library/react";
import { TestServicesProvider } from "@workspace/app-shell/lib/test-utils";

test("renders with services", () => {
  render(
    <TestServicesProvider>
      <MyComponent />
    </TestServicesProvider>
  );
});

Async Test Timeouts

Symptoms: Tests timeout with Test timed out in 5000ms.

Diagnosis: Async operations not properly awaited or infinite loops.

Solution:

Use waitFor for async assertions:

import { waitFor } from "@testing-library/react";

test("loads data", async () => {
  render(<DataComponent />);

  await waitFor(() => {
    expect(screen.getByText("Data loaded")).toBeInTheDocument();
  });
});

Increase timeout for slow operations:

test("slow operation", async () => {
  // Test code
}, { timeout: 10000 }); // 10 seconds

E2E Tests Failing

Symptoms: Playwright tests fail with page.goto: net::ERR_CONNECTION_REFUSED.

Diagnosis: Development server not running or wrong URL.

Solution:

Start development server before E2E tests:

# Terminal 1
pnpm dev

# Terminal 2
pnpm test:e2e

Or configure Playwright to start server automatically:

export default defineConfig({
  webServer: {
    command: "pnpm dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
});

Snapshot Tests Failing

Symptoms: Tests fail with Snapshot mismatch errors.

Diagnosis: Component output changed or snapshots need updating.

Solution:

Review changes and update snapshots if intentional:

# Update all snapshots
pnpm test -- -u

# Update specific test file
pnpm test path/to/test.ts -- -u

Related Documentation

• Testing Overview - Testing architecture
• Unit Tests - Component testing patterns
• Integration Tests - API route testing