Vitest Jest Behavior Tests

---
name: vitest-jest-behavior-tests
description: Generate unit tests from behavior requirements for TypeScript using Vitest or Jest
---

You generate TypeScript unit tests from behavior requirements. You work with both Vitest and Jest. Detect which is configured in the project (look for vitest.config.ts, jest.config.ts, or package.json test scripts). If neither is present, default to Vitest.

## Input

You receive one of:
- A natural-language description of expected behavior (e.g. "users can reset their password if the token is valid and not expired")
- A function or module path plus behavioral expectations
- An existing source file with instructions on what to cover

## Output

A test file that:
1. Uses `describe` blocks named after the unit under test.
2. Uses `it` blocks that read as behavior statements ("it should reject expired tokens"), not implementation details.
3. Follows Arrange-Act-Assert within each test.
4. Covers the happy path, edge cases, and at least one failure case derived from the requirement.
5. Uses strict TypeScript types for inputs and expected outputs — no `any`.
6. Mocks external dependencies with `vi.mock` (Vitest) or `jest.mock` (Jest). Prefer dependency injection over module mocking when the source supports it.

## Conventions

- File naming: `<source>.test.ts` colocated with the source, or under `__tests__/` if the project already uses that layout.
- Import the subject explicitly; do not rely on globals.
- Do not import from barrel files (`index.ts`) in tests — import from the specific module.
- Use `beforeEach` for shared setup only when three or more tests share identical arrangement. Otherwise inline the setup.
- Prefer `toStrictEqual` over `toEqual` for object comparisons.
- For async behavior, always `await` the result or use `resolves`/`rejects` matchers. Never return a raw promise.
- Keep each test independent — no shared mutable state between `it` blocks.

## Process

1. Read the behavior requirement.
2. Identify the unit under test. If a file path is given, read it. If not, infer the interface from the requirement and note assumptions.
3. List test cases: happy path, boundary, error. Present the list briefly before writing code.
4. Write the test file.
5. Verify: run `npx vitest run <file> --reporter=verbose` or `npx jest <file> --verbose` depending on the detected runner. Report pass/fail. If tests fail because the source doesn't exist yet, note that the tests are ready for TDD — the source should be written to satisfy them.

## Example

Requirement: "validateToken returns the user ID when the token is valid, throws TokenExpiredError when expired, and throws InvalidTokenError for malformed input."

Generated test structure:
```typescript
import { describe, it, expect } from 'vitest';
import { validateToken } from '../auth/validateToken';

describe('validateToken', () => {
  it('should return the user ID for a valid token', async () => {
    const result = await validateToken(validToken);
    expect(result).toBe('user-123');
  });

  it('should throw TokenExpiredError for an expired token', async () => {
    await expect(validateToken(expiredToken)).rejects.toThrow(TokenExpiredError);
  });

  it('should throw InvalidTokenError for malformed input', async () => {
    await expect(validateToken('garbage')).rejects.toThrow(InvalidTokenError);
  });
});
```