`
- Add `data-testid` for easy querying in tests
- Mock EVERY component imported by the component under test
### 3. Main Describe Block
```typescript
describe('MyComponent', () => {
// Helper function
function renderMyComponent(props?: Partial
) {
// ...
}
// Reset mocks before each test
beforeEach(() => {
vi.clearAllMocks();
});
// Test cases
it('should render sub-components with correct props', () => {
// Test...
});
});
```
**Structure Rules:**
- Main describe uses the component name
- Contains one `renderMyComponent` helper function at the top
- Includes `beforeEach` to clear mocks
- All test cases use the `renderMyComponent` helper
### 4. renderMyComponent Helper Function
**Purpose:** Factory function that renders the component with default or custom props.
**Pattern:**
```typescript
function renderMyComponent(props?: Partial) {
const defaultProps: MyComponentProps = {
title: 'Test Title',
onSubmit: vi.fn(),
items: [],
};
return render();
}
```
**Rules:**
- Accept partial props (optional)
- Define sensible defaults for all required props
- Use `vi.fn()` for callback props
- Spread defaults first, then custom props
- Return the result of `render()`
### 5. Testing Sub-Component Props
**Access the mock to verify props:**
```typescript
import { SubComponentA } from '../src/components/SubComponentA';
it('should pass correct props to SubComponentA', () => {
renderMyComponent({ title: 'My Title', count: 5 });
expect(SubComponentA).toHaveBeenCalledWith(
expect.objectContaining({
title: 'My Title',
count: 5
}),
expect.anything() // React context
);
});
```
**Rules:**
- Import the mocked component at the top
- Use `expect(MockedComponent).toHaveBeenCalledWith()`
- Use `expect.objectContaining()` to match props
- Use `expect.anything()` as second arg (React context)
### 6. Testing Callbacks
**Simulate callback invocation to test handlers:**
```typescript
it('should call onSubmit when button is clicked', () => {
const mockOnSubmit = vi.fn();
const { SubButton } = require('../src/components/SubButton');
renderMyComponent({ onSubmit: mockOnSubmit });
// Get the onClick prop passed to SubButton
const onClickProp = SubButton.mock.calls[0][0].onClick;
// Simulate the click
onClickProp();
expect(mockOnSubmit).toHaveBeenCalled();
});
```
**Rules:**
- Pass `vi.fn()` as callback props
- Extract callback from mock's call arguments
- Invoke the callback to test the handler
- Assert the handler was called correctly
### 7. Testing Conditional Rendering
**Test different branches:**
```typescript
it('should render ErrorMessage when error prop is provided', () => {
const { ErrorMessage } = require('../src/components/ErrorMessage');
renderMyComponent({ error: 'Something went wrong' });
expect(ErrorMessage).toHaveBeenCalledWith(
expect.objectContaining({
message: 'Something went wrong'
}),
expect.anything()
);
});
it('should not render ErrorMessage when no error', () => {
const { ErrorMessage } = require('../src/components/ErrorMessage');
renderMyComponent({ error: null });
expect(ErrorMessage).not.toHaveBeenCalled();
});
```
### 8. Testing Lists and Iterations
**Test components rendered in loops:**
```typescript
it('should render ListItem for each item', () => {
const { ListItem } = require('../src/components/ListItem');
const items = [
{ id: '1', name: 'Item 1' },
{ id: '2', name: 'Item 2' },
{ id: '3', name: 'Item 3' }
];
renderMyComponent({ items });
expect(ListItem).toHaveBeenCalledTimes(3);
expect(ListItem).toHaveBeenNthCalledWith(
1,
expect.objectContaining({ id: '1', name: 'Item 1' }),
expect.anything()
);
expect(ListItem).toHaveBeenNthCalledWith(
2,
expect.objectContaining({ id: '2', name: 'Item 2' }),
expect.anything()
);
expect(ListItem).toHaveBeenNthCalledWith(
3,
expect.objectContaining({ id: '3', name: 'Item 3' }),
expect.anything()
);
});
```
## Workflow
### Create Workflow
1. **Identify the component** - Determine which component to test
2. **Locate the component file** - Use Glob to find the component definition
3. **Read the component** - Understand props, sub-components, logic branches
4. **Identify sub-components** - List all imported components to mock
5. **Ensure `__tests__` exists** - Create folder if needed (sibling to `/src`)
6. **Verify @testing-library/react** - Check package.json
7. **Create test file** in `__tests__/MyComponent.spec.tsx` with:
- All required imports (including React)
- Mock declarations for all sub-components
- Main describe block
- `renderMyComponent` helper function
- `beforeEach` to clear mocks
- Test cases covering all scenarios
### Update Workflow
1. **Read existing test and component** - Compare current state
2. **Identify changes**:
- New sub-components → Add mocks
- Changed props → Update test cases
- New logic branches → Add test cases
- Removed functionality → Remove tests
3. **Apply updates using Edit tool** - Targeted changes only
4. **Verify coverage** - Ensure all logic branches tested
### Update Guidelines
- **Preserve structure** - Use Edit tool, not Write
- **Maintain consistency** - Follow existing patterns
- **Keep descriptive names** - Clear, behavior-focused
- **Don't delete passing tests** - Only update broken/obsolete tests
- **Add missing coverage** - Test new logic and props
## Best Practices
1. **Test Logic, Not UI** - Focus on props passed and callbacks invoked
2. **Mock All Sub-Components** - Test the component in complete isolation
3. **Descriptive Test Names** - Explain expected behavior clearly
4. **Clear Mocks Between Tests** - Use `beforeEach` with `vi.clearAllMocks()`
5. **Test All Branches** - Cover conditional rendering, loops, error states
6. **Test Callbacks** - Simulate sub-component callbacks to test handlers
7. **Use expect.objectContaining** - Match specific props without over-specifying
## Common Pitfalls to Avoid
1. ❌ **Don't Import Sub-Components Normally** - They should be mocked, not imported
2. ❌ **Don't Forget React Import** - Required for JSX in this project
3. ❌ **Don't Forget beforeEach** - Mocks persist between tests
4. ❌ **Don't Test UI Appearance** - Focus on logic and prop passing
5. ❌ **Don't Skip expect.anything()** - It's needed as the second argument for React context
6. ❌ **Don't Forget to Mock Everything** - ALL sub-components must be mocked
## Example Reference
See `examples.md` in the same directory for complete working examples of:
- Simple component with sub-components
- Component with conditional rendering
- Component with lists and iterations
- Component with callbacks and handlers
- Component with complex prop passing
- Component with multiple branches
## Important Notes
### File Organization
- Tests in `__tests__/` at package root (sibling to `/src`)
- Use `.tsx` extension
- Match component name exactly
### Dependencies
- Ensure `@testing-library/react` is installed
- Use `vi.mock()` for all sub-components
- Mock at the module level, not inside tests
### Test Quality
- Many small tests > few large tests
- Test happy path and error cases
- Test all conditional branches
- Descriptive test names
- Simple, focused tests
### Running Tests
After creating/updating:
1. Run `pnpm test` to verify tests pass
2. Run `pnpm lint` to check linting
3. Run `pnpm build` to verify TypeScript compiles
### Mocking Best Practices
- Always use `vi.fn()` for mock components
- Return simple `` elements with `data-testid`
- Clear mocks in `beforeEach`
- Import mocked components when you need to assert on them
- Use `expect.objectContaining()` to verify props