# vitest-guide

> Write comprehensive Vitest tests following UI-Doc conventions. Provides type-safe mocking patterns, test organization, and project-specific testing guidance. Use when implementing or reviewing tests.

- Author: github-actions[bot]
- Repository: gherrink/ui-doc
- Version: 20260129151824
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/gherrink/ui-doc
- Web: https://mule.run/skillshub/@@gherrink/ui-doc~vitest-guide:20260129151824

---

---
name: vitest-guide
description: Write comprehensive Vitest tests following UI-Doc conventions. Provides type-safe mocking patterns, test organization, and project-specific testing guidance. Use when implementing or reviewing tests.
---

# Vitest Guide Skill

Write comprehensive Vitest tests following UI-Doc project conventions. This skill provides patterns for mocking, assertions, and test organization.

## Quick Reference

**Framework:** Vitest with TypeScript
**Test Location:** `packages/*/tests/*.test.ts`
**Run Tests:** `pnpm test` or `pnpm --filter @ui-doc/<package> test`

## Core Patterns

### Test Structure

```typescript
import { beforeEach, describe, expect, it, vi } from 'vitest'

describe('componentName', () => { // Use camelCase starting lowercase
  beforeEach(() => {
    vi.clearAllMocks()
  })

  describe('methodName', () => {
    it('should [expected behavior]', () => {
      // Arrange
      // Act
      // Assert
    })
  })
})
```

### Throw-Only Functions

Functions that only throw need explicit `never` return type:

```typescript
// Testing error throwing
function throwError(): never {
  throw new CustomError('message')
}

expect(throwError).toThrow(CustomError)
```

### Type-Safe Mocking

```typescript
// Function mock with type inference
const mockFn = vi.fn<ClassName['methodName']>()

// Mock with return value
const mockParse = vi.fn<Parser['parse']>().mockReturnValue([])

// Sequential return values
vi.fn<Reader['read']>()
  .mockReturnValueOnce(firstResult)
  .mockReturnValueOnce(secondResult)
```

### Module Mocking

```typescript
// Full module mock (hoisted)
vi.mock('@ui-doc/core', () => ({
  UIDoc: vi.fn(),
}))

// Spy on specific method
vi.spyOn(fs, 'readFile').mockResolvedValue('content')
```

## Naming Conventions

- **Files:** kebab-case matching source: `UIDoc.ts` → `ui-doc.test.ts`
- **Describe blocks:** Component/function name
- **Test titles:** `'should [action] when [condition]'`

## Assertions

```typescript
// Value equality
expect(result).toEqual(expected)
expect(result).toBe(exactValue)

// Mock verification
expect(mockFn).toHaveBeenCalledWith(arg1, arg2)
expect(mockFn).toHaveBeenCalledTimes(2)

// Object matching
expect(obj).toMatchObject({ key: 'value' })

// Type checking
expect(instance).toBeInstanceOf(ClassName)

// Async errors
await expect(asyncFn()).rejects.toThrow('error message')
```

See [vitest-patterns.md](./references/vitest-patterns.md) for comprehensive patterns.
See [ui-doc-conventions.md](./references/ui-doc-conventions.md) for project-specific conventions.