Test Guidelines - Vitest / React Testing Library

This skill defines quality standards, structure, and naming conventions for test code using Vitest and React Testing Library.

How to Use This Skill

Quick Reference - Phase 2: Testing & Stories

テスト作成時:

• • Quick Referenceチェックリストで品質基準を確認
• • 詳細パターンが必要な場合はreferences/を参照
  • •test-patterns.md - 全テストシナリオのコード例
  • •aaa-pattern-guide.md - AAAパターンの詳細

test-reviewエージェントとの連携:

• •このスキルの基準でAAA準拠、カバレッジ、命名規則、動作テストを検証

Quick Reference

Use this checklist when writing or reviewing tests:

• • Explicit imports from vitest (no global definitions)
• • Test descriptions in Japanese with specific conditions and expected results
• • AAA pattern strictly followed with actual and expected variables
• • One test, one assertion (or object comparison for multiple properties)
• • No nested describe blocks
• • All branches and exception paths identified and tested
• • Testing behavior, not implementation details
• • Test file named [ComponentName].test.tsx or [functionName].test.ts
• • Test file placed in the same directory as the component/function
• • Snapshots limited to semantic HTML and accessibility attributes only

Core Principles

1. Explicit Imports

Always import necessary functions from vitest explicitly:

import { describe, expect, test, vi } from "vitest";

Rationale: Avoids relying on global definitions, making dependencies clear.

2. Descriptive Test Names (Japanese)

Write describe and test descriptions in Japanese with specific conditions and expected results:

test("商品が複数の場合、合計金額を返すこと", () => {
  // ...
});

Format: "when [condition], it should [result]"

3. AAA Pattern (Arrange-Act-Assert)

Strictly follow the AAA pattern with actual and expected variables:

test("商品が1つの場合、その価格を返すこと", () => {
  // Arrange
  const items = [{ price: 100 }];
  const expected = 100;

  // Act
  const actual = calculateTotal(items);

  // Assert
  expect(actual).toBe(expected);
});

Rationale: Makes tests easier to read, understand, and maintain.

4. One Test, One Assertion

Each test verifies one behavior. For multiple properties, use object comparison:

// ✅ Correct: Object comparison
test("ユーザー情報が正しいこと", () => {
  const expected = { name: "Taro", age: 30, email: "taro@example.com" };
  const actual = getUser();
  expect(actual).toEqual(expected);
});

5. Flat Structure (No Nested Describe)

Prohibit nested describe blocks. Use descriptive test names instead:

// ✅ Correct
describe("UserService", () => {
  test("ユーザーが存在する場合、ユーザー情報を返すこと", () => {});
  test("ユーザーが存在しない場合、エラーがスローされること", () => {});
});

6. Test Behavior, Not Implementation

Focus on what the component does, not how it does it:

// ✅ Testing user-visible behavior
test("カウンターが1増加すること", async () => {
  const { user } = render(<Counter />);
  const button = screen.getByRole("button", { name: "増やす" });
  await user.click(button);
  expect(screen.getByText("1")).toBeInTheDocument();
});

Test Structure Guidelines

Test File Organization

• •Naming: [ComponentName].test.tsx or [functionName].test.ts
• •Location: Same directory as the component/function being tested
• •Import Order:
  1. •External libraries (Testing utilities)
  2. •External libraries (Vitest)
  3. •Component or function under test

Shared Data Management

Place shared data in the top-level describe scope:

describe("formatDate", () => {
  // Shared data in top-level scope
  const testDate = new Date("2024-01-15T10:30:00");

  test("年月日形式でフォーマットされること", () => {
    // Use shared data
  });
});

When to Create Tests

Branch Coverage

Identify all branches and exception paths:

• •Conditional logic: Test all if/else branches
• •Switch statements: Test all cases including default
• •Error handling: Test both success and error paths
• •Edge cases: Test boundary conditions (empty, null, zero, max values)

Component Testing Focus

Test components based on user-visible behavior:

• •Rendering: Verify content appears correctly
• •User interactions: Test clicks, input, form submissions
• •State changes: Verify UI updates after state changes
• •Accessibility: Check ARIA attributes and semantic HTML

Quality Criteria

Meaningful Coverage

• •Not just line coverage: Ensure all logical branches are tested
• •Behavior coverage: Verify all user-facing behaviors
• •Error paths: Test error handling and edge cases

Test Maintainability

• •Clear structure: AAA pattern makes tests easy to understand
• •Descriptive names: Japanese descriptions explain what is being tested
• •No implementation details: Tests remain valid when refactoring

Snapshot Testing Limitations

Use snapshots only for:

• •Verifying semantic HTML structure
• •Checking accessibility attributes (aria-*, role, etc.)
• •Ensuring critical DOM structure remains stable

Do NOT use snapshots for:

• •CSS class names or inline styles
• •Testing visual appearance
• •Replacing proper assertions

Reference Documentation

For detailed code examples and patterns, consult:

• •

  references/test-patterns.md: Comprehensive examples including:

  • •Basic test structure
  • •Component testing patterns
  • •Shared data management
  • •Error case testing
  • •Form testing
  • •Import organization
  • •Snapshot testing usage
• •

  references/aaa-pattern-guide.md: In-depth AAA pattern guidance including:

  • •Why AAA pattern matters
  • •actual vs expected variables
  • •One test, one assertion principle
  • •Common anti-patterns to avoid
  • •Testing behavior vs implementation
  • •Async testing patterns
  • •Branch coverage examples

Summary

This skill emphasizes:

1. •Structure: AAA pattern with explicit actual and expected variables
2. •Clarity: Japanese test descriptions with specific conditions and results
3. •Coverage: All branches, edge cases, and error paths tested
4. •Behavior: Test what users see, not implementation details
5. •Quality: Meaningful coverage over line coverage metrics

Always prioritize test maintainability and readability over brevity.