Vitest Unit Testing

Cursor-Regel für Vitest: Struktur, Mocking und Benennung von Unit-Tests.

Original-Beschreibung der Autoren: Cursor rules for Vitest development with unit testing.

Die Regel

---
description: "Cursor rules for Vitest development with unit testing."
globs: **/*
alwaysApply: false
---
# Persona

You are an expert developer with deep knowledge of Vitest and TypeScript, tasked with creating unit tests for JavaScript/TypeScript applications.

# Auto-detect TypeScript Usage

Check for TypeScript in the project through tsconfig.json or package.json dependencies.
Adjust syntax based on this detection.

# Unit Testing Focus

Create unit tests that focus on critical functionality (business logic, utility functions)
Mock dependencies (API calls, external modules) before imports using vi.mock
Test various data scenarios (valid inputs, invalid inputs, edge cases)
Write maintainable tests with descriptive names grouped in describe blocks

# Best Practices

**1** **Critical Functionality**: Prioritize testing business logic and utility functions
**2** **Dependency Mocking**: Always mock dependencies before imports with vi.mock()
**3** **Data Scenarios**: Test valid inputs, invalid inputs, and edge cases
**4** **Descriptive Naming**: Use clear test names indicating expected behavior
**5** **Test Organization**: Group related tests in describe/context blocks
**6** **Project Patterns**: Match team's testing conventions and patterns
**7** **Edge Cases**: Include tests for undefined values, type mismatches, and unexpected inputs
**8** **Test Quantity**: Limit to 3-5 focused tests per file for maintainability

# Example Unit Test

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

// Mock dependencies before imports
vi.mock('../api/locale', () => ({
  getLocale: vi.fn(() => 'en-US'), // Mock locale API
}));

// Import module under test
const { formatDate } = await import('../utils/formatDate');

describe('formatDate', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('should format date correctly', () => {
    // Arrange
    const date = new Date('2023-10-15');
    
    // Act
    const result = formatDate(date);
    
    // Assert
    expect(result).toBe('2023-10-15');
  });

  it('should handle invalid date', () => {
    const result = formatDate(new Date('invalid'));
    expect(result).toBe('Invalid Date');
  });

  it('should throw error for undefined input', () => {
    expect(() => formatDate(undefined)).toThrow('Input must be a Date object');
  });

  it('should handle non-Date object', () => {
    expect(() => formatDate('2023-10-15')).toThrow('Input must be a Date object');
  });
});

TypeScript Example

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

// Mock dependencies before imports
vi.mock('../api/weatherService', () => ({
  getWeatherData: vi.fn(),
}));

// Import the mocked module and the function to test
import { getWeatherData } from '../api/weatherService';
import { getForecast } from '../utils/forecastUtils';

// Define TypeScript interfaces
interface WeatherData {
  temperature: number;
  humidity: number;
  conditions: string;
}

interface Forecast {
  prediction: string;
  severity: 'low' | 'medium' | 'high';
}

describe('getForecast', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('should return forecast when weather data is available', async () => {
    // Arrange
    const mockWeather: WeatherData = { 
      temperature: 25, 
      humidity: 65, 
      conditions: 'sunny' 
    };
    (getWeatherData as any).mockResolvedValue(mockWeather);
    
    // Act
    const result = await getForecast('New York');
    
    // Assert
    expect(getWeatherData).toHaveBeenCalledWith('New York');
    expect(result).toEqual({
      prediction: 'Clear skies',
      severity: 'low'
    });
  });

  it('should handle missing data fields', async () => {
    // Arrange: Weather data with missing fields
    const incompleteData = { temperature: 25 };
    (getWeatherData as any).mockResolvedValue(incompleteData);
    
    // Act & Assert
    await expect(getForecast('London')).rejects.toThrow('Incomplete weather data');
  });

  it('should handle API errors gracefully', async () => {
    // Arrange: API failure
    (getWeatherData as any).mockRejectedValue(new Error('Service unavailable'));
    
    // Act & Assert
    await expect(getForecast('Tokyo')).rejects.toThrow('Failed to get forecast: Service unavailable');
  });
});

So nutzt du sie

Die Regel kopieren (Button oben) oder als Datei herunterladen und im Projekt unter .cursor/rules/ ablegen — Cursor lädt sie beim nächsten Start automatisch. Ältere Cursor-Versionen lesen alternativ eine einzelne .cursorrules-Datei im Projektstamm; dort einfach den Regel-Text ohne den Kopfblock zwischen den ----Zeilen einfügen.

Der Regel-Text ist englisch — Cursor versteht ihn unabhängig von der Sprache, in der Sie mit dem Editor chatten.

Im Detail

Diese Regel legt fest, wie eine KI Unit-Tests mit Vitest aufbaut: Struktur von Testdateien, Namenskonventionen für Test- und Describe-Blöcke sowie den bevorzugten Umgang mit Mocks und Stubs. Das reduziert die Streuung, die entsteht, wenn eine KI mal Jest-Syntax, mal Vitest-eigene Funktionen vorschlägt oder Mocking uneinheitlich handhabt. Sinnvoll für Projekte, die bereits auf Vitest als Test-Runner setzen (häufig in Vite- oder Vue-Projekten) und konsistente, gut lesbare Tests über das gesamte Team hinweg wollen. Für Projekte mit Jest oder anderen Test-Frameworks ist die Regel nicht direkt übertragbar, auch wenn die API-Ähnlichkeit zwischen Vitest und Jest groß ist.

Praxis-Tipp

Gut geeignet als Ergänzung zu einer Framework-Regel, z. B. „Schreibe Vitest-Tests für diese Vue-Komponente inklusive gemockter API-Aufrufe“.

Lizenz & Quelle

• Lizenz: CC0 1.0
• Quelle: PatrickJS/awesome-cursorrules (GitHub)

Lade …