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-runSummary
A shared testing utilities package is one of the highest-leverage investments in a monorepo:
- Consistent render wrapper — all packages use the same providers
- Shared MSW server — default handlers and override pattern
- Typed factories — deterministic test data with overrides
- Base Vitest config — extend once, inherit everywhere
- 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.