Shared Testing Utilities in a Monorepo: Build Once, Test Everywhere

Shared Testing Utilities in a Monorepo: Build Once, Test Everywhere

Every package in your monorepo needs the same testing infrastructure: a React render wrapper with providers, mock API setup, test data factories, and a consistent test environment. If each package configures these independently, you end up with drift — different packages use different patterns, and fixing a bug in one test setup doesn't fix it everywhere.

The solution is a dedicated shared testing utilities package. Configure once, import everywhere.

Creating the Package

packages/
  test-utils/
    src/
      index.ts
      render.tsx
      server.ts
      factories.ts
      setup.ts
    package.json
    tsconfig.json
// packages/test-utils/package.json
{
  "name": "@my-org/test-utils",
  "version": "0.0.1",
  "private": true,
  "main": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "devDependencies": {
    "@testing-library/react": "^14.0.0",
    "@testing-library/user-event": "^14.0.0",
    "msw": "^2.0.0",
    "vitest": "^1.0.0"
  },
  "peerDependencies": {
    "react": ">=18"
  }
}

The package is private — it's not published to npm, just used within the monorepo.

Shared Render Wrapper

Every React test needs providers: Router, Redux store, React Query, theme, auth context. Wrapping these once in test-utils keeps each package's tests clean:

// packages/test-utils/src/render.tsx
import React, { ReactElement } from 'react';
import { render, RenderOptions } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ThemeProvider } from '@my-org/ui';

interface CustomRenderOptions extends Omit<RenderOptions, 'wrapper'> {
  initialEntries?: string[];
}

function createWrapper(options: CustomRenderOptions) {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: { retry: false },
      mutations: { retry: false },
    },
  });

  return function Wrapper({ children }: { children: React.ReactNode }) {
    return (
      <QueryClientProvider client={queryClient}>
        <ThemeProvider>
          <MemoryRouter initialEntries={options.initialEntries ?? ['/']}>
            {children}
          </MemoryRouter>
        </ThemeProvider>
      </QueryClientProvider>
    );
  };
}

function customRender(ui: ReactElement, options: CustomRenderOptions = {}) {
  return render(ui, { wrapper: createWrapper(options), ...options });
}

export * from '@testing-library/react';
export { customRender as render };

Usage in any package:

// packages/dashboard/src/__tests__/Dashboard.test.tsx
import { render, screen, userEvent } from '@my-org/test-utils';
import { Dashboard } from '../Dashboard';

test('shows empty state when no data', async () => {
  render(<Dashboard />);
  expect(screen.getByText('No data yet')).toBeInTheDocument();
});

Mock API Server (MSW)

Use Mock Service Worker for consistent API mocking. Define the server setup in test-utils:

// packages/test-utils/src/server.ts
import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';

// Default handlers — override in individual tests
export const defaultHandlers = [
  http.get('/api/user', () =>
    HttpResponse.json({ id: 1, name: 'Test User', email: 'test@example.com' })
  ),
  http.get('/api/teams', () =>
    HttpResponse.json([
      { id: 1, name: 'Engineering' },
      { id: 2, name: 'Design' },
    ])
  ),
];

export const server = setupServer(...defaultHandlers);

// Export http and HttpResponse so packages don't need to install msw directly
export { http, HttpResponse };
// packages/test-utils/src/setup.ts
import { server } from './server';
import '@testing-library/jest-dom';

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

In each package's vite.config.ts (or jest.config.ts):

// packages/dashboard/vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    environment: 'jsdom',
    setupFiles: ['@my-org/test-utils/setup'],
  },
});

Override handlers in individual tests:

// packages/dashboard/src/__tests__/Dashboard.test.tsx
import { render, screen } from '@my-org/test-utils';
import { server, http, HttpResponse } from '@my-org/test-utils/server';
import { Dashboard } from '../Dashboard';

test('shows error when API fails', async () => {
  server.use(
    http.get('/api/user', () => HttpResponse.json({ error: 'Unauthorized' }, { status: 401 }))
  );

  render(<Dashboard />);
  expect(await screen.findByText('Please log in')).toBeInTheDocument();
});

Test Data Factories

Factories generate consistent, typed test data. Define them once in test-utils:

// packages/test-utils/src/factories.ts

export interface User {
  id: number;
  name: string;
  email: string;
  role: 'admin' | 'member';
  createdAt: string;
}

export interface Team {
  id: number;
  name: string;
  members: User[];
}

let userCounter = 1;
let teamCounter = 1;

export function createUser(overrides: Partial<User> = {}): User {
  return {
    id: userCounter++,
    name: `User ${userCounter}`,
    email: `user${userCounter}@example.com`,
    role: 'member',
    createdAt: new Date().toISOString(),
    ...overrides,
  };
}

export function createTeam(overrides: Partial<Team> = {}): Team {
  return {
    id: teamCounter++,
    name: `Team ${teamCounter}`,
    members: [createUser()],
    ...overrides,
  };
}

export function createAdminUser(overrides: Partial<User> = {}): User {
  return createUser({ role: 'admin', ...overrides });
}

Usage:

import { createUser, createTeam, createAdminUser } from '@my-org/test-utils';

test('admin can invite members', async () => {
  const admin = createAdminUser({ name: 'Alice' });
  const team = createTeam({ members: [admin] });

  // test with typed, deterministic data
});

Shared Vitest Configuration

Create a base Vitest config that each package extends:

// packages/test-utils/src/vitest.config.base.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export const baseConfig = defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    setupFiles: ['@my-org/test-utils/setup'],
    globals: true,
    css: false,
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
      exclude: ['**/__tests__/**', '**/index.ts'],
    },
  },
});
// packages/dashboard/vite.config.ts
import { mergeConfig } from 'vitest/config';
import { baseConfig } from '@my-org/test-utils/vitest.config.base';

export default mergeConfig(baseConfig, {
  test: {
    // Dashboard-specific overrides
  },
});

Custom Matchers

Define project-specific custom matchers once:

// packages/test-utils/src/matchers.ts
import { expect } from 'vitest';

expect.extend({
  toBeValidEmail(received: string) {
    const pass = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(received);
    return {
      pass,
      message: () => `expected ${received} to be a valid email`,
    };
  },

  toBeWithinRange(received: number, floor: number, ceiling: number) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        `expected ${received} to be within range ${floor} - ${ceiling}`,
    };
  },
});

declare module 'vitest' {
  interface Assertion {
    toBeValidEmail(): void;
    toBeWithinRange(floor: number, ceiling: number): void;
  }
}

Add to setup.ts:

import './matchers';

Exporting Everything from index.ts

// packages/test-utils/src/index.ts
export * from './render';
export * from './server';
export * from './factories';
export * from './matchers';
export { baseConfig } from './vitest.config.base';

Workspace Configuration

In your monorepo root (npm workspaces example):

// package.json
{
  "workspaces": ["packages/*"],
  "scripts": {
    "test": "turbo run test",
    "test:watch": "turbo run test:watch"
  }
}

Packages declare the dependency:

// packages/dashboard/package.json
{
  "devDependencies": {
    "@my-org/test-utils": "*"
  }
}

The * means "any version from the workspace" — npm/pnpm/yarn resolves this to the local package.

Updating Shared Utilities

When you update test-utils, all dependent packages are affected. In Turborepo or Nx, this means they'll re-run their tests automatically on the next affected run.

For breaking changes to shared utilities (renaming a factory, changing render behavior), update test-utils first, then fix all consumers in the same PR. The dependency graph makes it easy to find every consumer:

# Nx
nx show projects --affected --base=main

# Turborepo
turbo run test --filter=...@my-org/test-utils --dry-run

Summary

A shared testing utilities package is one of the highest-leverage investments in a monorepo:

  1. Consistent render wrapper — all packages use the same providers
  2. Shared MSW server — default handlers and override pattern
  3. Typed factories — deterministic test data with overrides
  4. Base Vitest config — extend once, inherit everywhere
  5. Custom matchers — project-specific assertions

The initial setup takes an hour. The return is fewer flaky tests, easier refactors, and a consistent testing culture across every package in the repo.

Read more

Start now free