---
description: Rules for consistent and type-safe mocking in Vitest tests
globs: "**/*.test.{ts,tsx,js,jsx}"
alwaysApply: true
---

# Spy Mocking Rules for Vitest Tests

## Mocking Approach

When mocking packages or files in Vitest-based tests, follow these rules:

1. Use `vi.mock()` with the `spy: true` option for all package and file mocks
2. Place all mocks at the top of the test file before any test cases
3. Use `vi.mocked()` to type and access the mocked functions
4. Implement mock behaviors in `beforeEach` blocks
5. Mock all required dependencies that the test subject uses

## Mock Implementation Rules

1. Mock implementations should be placed in `beforeEach` blocks
2. Each mock implementation should return a Promise for async functions
3. Mock implementations should match the expected return type of the original function
4. Use `vi.mocked()` to access and implement mock behaviors
5. Mock all required properties and methods that the test subject uses

## Avoided Patterns

The following mocking patterns should be avoided:

1. Direct function mocking without `vi.mocked()`
2. Mock implementations outside of `beforeEach` blocks
3. Mocking without the `spy: true` option
4. Inline mock implementations within test cases
5. Mocking only a subset of required dependencies

## Best Practices

1. Mock at the highest level of abstraction needed
2. Keep mock implementations simple and focused
3. Use type-safe mocking with `vi.mocked()`
4. Document complex mock behaviors
5. Group related mocks together