essential-test-patterns

GROWI Testing Patterns

GROWI uses Vitest for all testing (unit, integration, component). This skill covers universal testing patterns applicable across the monorepo.

Test File Placement (Global Standard)

Place test files in the same directory as the source file:

src/components/Button/
├── Button.tsx
└── Button.spec.tsx       # Component test

src/utils/
├── helper.ts
└── helper.spec.ts        # Unit test

src/services/api/
├── pageService.ts
└── pageService.integ.ts  # Integration test

Test Types & Environments

File Pattern	Type	Environment	Use Case
*.spec.{ts,js}	Unit Test	Node.js	Pure functions, utilities, services
*.integ.ts	Integration Test	Node.js + DB	API routes, database operations
*.spec.{tsx,jsx}	Component Test	happy-dom	React components

Vitest automatically selects the environment based on file extension and configuration.

Vitest Configuration

Global APIs (No Imports Needed)

All GROWI packages configure Vitest globals in tsconfig.json:

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

This enables auto-import of testing APIs:

// No imports needed!
describe('MyComponent', () => {
  it('should render', () => {
    expect(true).toBe(true);
  });

  beforeEach(() => {
    // Setup
  });

  afterEach(() => {
    // Cleanup
  });
});

Available globals: describe, it, test, expect, beforeEach, afterEach, beforeAll, afterAll, vi

Type-Safe Mocking with vitest-mock-extended

Basic Usage

vitest-mock-extended provides fully type-safe mocks with TypeScript autocomplete:

import { mockDeep, type DeepMockProxy } from 'vitest-mock-extended';

// Create type-safe mock
const mockRouter: DeepMockProxy<NextRouter> = mockDeep<NextRouter>();

// TypeScript autocomplete works!
mockRouter.asPath = '/test-path';
mockRouter.query = { id: '123' };
mockRouter.push.mockResolvedValue(true);

// Use in tests
expect(mockRouter.push).toHaveBeenCalledWith('/new-path');

Complex Types with Optional Properties

interface ComplexProps {
  currentPageId?: string | null;
  currentPathname?: string | null;
  data?: Record<string, unknown>;
  onSubmit?: (value: string) => void;
}

const mockProps: DeepMockProxy<ComplexProps> = mockDeep<ComplexProps>();
mockProps.currentPageId = 'page-123';
mockProps.data = { key: 'value' };
mockProps.onSubmit?.mockImplementation((value) => {
  console.log(value);
});

Why vitest-mock-extended?

• ✅ Type safety: Catches typos at compile time
• ✅ Autocomplete: IDE suggestions for all properties/methods
• ✅ Deep mocking: Automatically mocks nested objects
• ✅ Vitest integration: Works seamlessly with vi.fn()

mock<T>() vs mockDeep<T>() — and mock<T>({ ...overrides })

import { mock, mockDeep } from 'vitest-mock-extended';

// Auto-stub everything, override just the members the test touches.
// The override object is type-checked against Crowi (PartialDeep<Crowi>),
// and the return value IS a Crowi — no cast needed.
const crowi = mock<Crowi>({
  searchService: { searchKeyword: vi.fn() },
});

// mockDeep<T>() recursively proxies nested access (foo.bar.baz.method()
// all return mocks lazily). Use when the code-under-test reaches deep into
// nested members you don't want to enumerate.
const configManager = mockDeep<IConfigManagerForApp>();

• mock<T>(overrides?) — shallow auto-stub + a typed partial override. The common case for service/Crowi-style dependencies.
• mockDeep<T>() — recursive proxy for arbitrarily deep nested access.

Avoid type assertions for mocks — as any, as unknown as T, as T

All three assertion forms disable the type checker for the mock, just in different ways, so prefer mock<T>() over every one of them:

• as unknown as Crowi — the usual escape hatch; compiles even when the real type drifts (a method is renamed or removed), leaving the mock silently wrong, and lets you assign members that do not exist.
• as Crowi — same problem when it compiles; TypeScript only blocks it when the object structurally clashes, which then pushes people to as unknown as or as any.
• as any — the broadest hole: erases the type entirely, so nothing about the mock is checked and IDE autocomplete dies too.

mock<T>({ ...overrides }) is both safer (the override is checked, so drift is a compile error) and shorter (no need to hand-build the object).

// ❌ WRONG — every one of these escapes type checking and survives API drift
const crowi = { searchService: { searchKeyword: vi.fn() } } as unknown as Crowi;
const crowi = { searchService: { searchKeyword: vi.fn() } } as Crowi;
const crowi = { searchService: { searchKeyword: vi.fn() } } as any;

// ✅ CORRECT — type-checked, auto-stubs the rest, returns a real Crowi
const crowi = mock<Crowi>({
  searchService: { searchKeyword: vi.fn() },
});

Anti-pattern to watch for: hand-writing a Pick<T, ...> shim type plus a builder function and still casting at the call site. That is more code than mock<T>() and is not type-safe — the worst of both. Replace it with mock<T>({ ... }).

Tolerance framework: when a type assertion is acceptable

The deciding question is the cost: how many lines (and how much clarity) does removing the assertion cost?

Tier	Situation	Rule
1 — Avoid (cost ≤ 0)	Mocking an interface/class. mock<T>() is 1 line, type-safe, shorter than the manual object.	No assertion. Use mock<T>(). No exceptions.
2 — Localize (small cost)	One field needs real behavior mock<T> can't give (e.g. a working EventEmitter whose listeners actually fire), and its type doesn't quite match.	Allowed, but confine the cast to that one field: mock<Crowi>({ events: { page: realEmitter as unknown as PageEvent } }) — never cast the whole object.
3 — Allow + comment (large cost)	No type exists for the target (untyped JS module, untyped third-party lib). mock<T> can't be built.	A 1-line cast is fine — writing a dozens-of-lines shim just to delete it is overkill. Leave a // WHY: comment (e.g. // PageEvent is a JS file typed as 'any' in Crowi).
4 — Forbidden	A hand-built/Pick<> partial object that ends in a cast anyway.	Replace with mock<T>(). There is no reason to keep it.

Rule of thumb: if deleting the cast costs ≤ 0 lines, it's mandatory (Tier 1); if it can be localized to one field, do that (Tier 2); if the type itself is missing and avoidance would cost dozens of lines, a commented 1-line cast is fine (Tier 3); a shim that still casts is never fine (Tier 4).

React Testing Library Patterns

Basic Component Test

import { render } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  it('should render with text', () => {
    const { getByText } = render(<Button>Click me</Button>);
    expect(getByText('Click me')).toBeInTheDocument();
  });

  it('should call onClick when clicked', async () => {
    const onClick = vi.fn();
    const { getByRole } = render(<Button onClick={onClick}>Click</Button>);

    const button = getByRole('button');
    await userEvent.click(button);

    expect(onClick).toHaveBeenCalledTimes(1);
  });
});

Testing with Jotai (Global Pattern)

When testing components that use Jotai atoms, wrap with <Provider>:

import { render } from '@testing-library/react';
import { Provider } from 'jotai';

const renderWithJotai = (ui: React.ReactElement) => {
  const Wrapper = ({ children }: { children: React.ReactNode }) => (
    <Provider>{children}</Provider>
  );
  return render(ui, { wrapper: Wrapper });
};

describe('ComponentWithJotai', () => {
  it('should render with atom state', () => {
    const { getByText } = renderWithJotai(<MyComponent />);
    expect(getByText('Hello')).toBeInTheDocument();
  });
});

Isolated Jotai Scope (For Testing)

To isolate atom state between tests:

import { createScope } from 'jotai-scope';

describe('ComponentWithIsolatedState', () => {
  it('test 1', () => {
    const scope = createScope();
    const { getByText } = renderWithJotai(<MyComponent />, scope);
    // ...
  });

  it('test 2', () => {
    const scope = createScope(); // Fresh scope
    const { getByText } = renderWithJotai(<MyComponent />, scope);
    // ...
  });
});

Async Testing Patterns (Global Standard)

Using act() and waitFor()

When testing async state updates:

import { waitFor, act } from '@testing-library/react';
import { renderHook } from '@testing-library/react';

test('async hook', async () => {
  const { result } = renderHook(() => useMyAsyncHook());

  // Trigger async action
  await act(async () => {
    result.current.triggerAsyncAction();
  });

  // Wait for state update
  await waitFor(() => {
    expect(result.current.isLoading).toBe(false);
  });

  expect(result.current.data).toBeDefined();
});

Testing Async Functions

it('should fetch data successfully', async () => {
  const data = await fetchData();
  expect(data).toEqual({ id: '123', name: 'Test' });
});

it('should handle errors', async () => {
  await expect(fetchDataWithError()).rejects.toThrow('Error');
});

Advanced Assertions

Object Matching

expect(mockFunction).toHaveBeenCalledWith(
  expect.objectContaining({
    pathname: '/expected-path',
    data: expect.any(Object),
    timestamp: expect.any(Number),
  })
);

Array Matching

expect(result).toEqual(
  expect.arrayContaining([
    expect.objectContaining({ id: '123' }),
    expect.objectContaining({ id: '456' }),
  ])
);

Partial Matching

expect(user).toMatchObject({
  name: 'John',
  email: 'joh

---

*Content truncated.*