テスト ベストプラクティス

実際の信頼性を提供する効果的で保守しやすいテストを書くためのガイドラインです。E2E テストの優先、モッキングの最小化、実装ではなく動作のテストに焦点を当てた6つのルールを含みます。

基本的な考え方

1. ユニットテストより E2E テストを優先する - 独立した部品ではなく、システム全体をテストする
2. モッキングを最小化する - 複雑なモックが必要な場合は、E2E テストを書く
3. 実装ではなく動作をテストする - ユーザーが見て実行することをテストする
4. React コンポーネントを直接テストしない - E2E を通じてテストする

適用タイミング

以下の場合にこのガイドラインを参照してください:

• どのタイプのテストを書くか決定する時
• 新しい E2E またはユニットテストを書く時
• テストコードをレビューする時
• テストをリファクタリングする時

ルール概要

テスト戦略 (重要)

prefer-e2e-tests - @rules/prefer-e2e-tests.md

デフォルトで E2E テストを使用します。純粋な関数に対してのみユニットテストを書いてください。

// E2E テスト (推奨) - 実際のユーザーフローをテスト
test("user can place an order", async ({ page }) => {
  await createTestingAccount(page, { account_status: "active" });
  await page.goto("/catalog");
  await page.getByRole("heading", { name: "Example Item" }).click();
  await page.getByRole("link", { name: "Buy" }).click();
  // ... 完全なフロー
  await expect(page.getByAltText("Thank you")).toBeVisible();
});

// ユニットテスト - 純粋な関数のみ
test("formatCurrency formats with two decimals", () => {
  expect(formatCurrency(1234.5)).toBe("$1,234.50");
});

avoid-component-tests - @rules/avoid-component-tests.md

React コンポーネントをユニットテストしないでください。E2E またはテストしないでください。

// 悪い例: コンポーネントのユニットテスト
describe("OrderCard", () => {
  test("renders amount", () => {
    render(<OrderCard amount={100} />);
    expect(screen.getByText("$100")).toBeInTheDocument();
  });
});

// 良い例: E2E テストがコンポーネントを自然にカバーする
test("order history shows orders", async ({ page }) => {
  await page.goto("/orders");
  await expect(page.getByText("$100")).toBeVisible();
});

minimize-mocking - @rules/minimize-mocking.md

モックはシンプルに保ってください。3 個以上のモックが必要な場合は、E2E テストを書いてください。

// 悪い例: モックが多すぎる = E2E テストを書く
vi.mock("~/lib/auth");
vi.mock("~/lib/transactions");
vi.mock("~/hooks/useAccount");

// 良い例: ローダーテストのシンプルな MSW モック
mockServer.use(
  http.get("/api/user", () => HttpResponse.json({ name: "John" })),
);

E2E テスト (高)

e2e-test-structure - @rules/e2e-test-structure.md

E2E テストは frontend/ ではなく e2e/tests/ に配置してください。

// e2e/tests/order.spec.ts
import { test, expect } from "@playwright/test";
import { addAccountBalance, createTestingAccount } from "./utils";

test.describe("Orders", () => {
  test.beforeEach(async ({ page, context }) => {
    await createTestingAccount(page, { account_status: "active" });
    let cookies = await context.cookies();
    let account_id = cookies.find((c) => c.name === "account_id").value;
    await addAccountBalance({ account_id, amount: 10000, replaceBalance: true });
  });

  test("place order with default values", async ({ page }) => {
    await page.goto("/catalog");
    // ... ユーザーフロー
  });
});

e2e-selectors - @rules/e2e-selectors.md

アクセシブルなセレクターを使用してください: role > label > text > testid。

// 良い例: ロールベース (推奨)
await page.getByRole("button", { name: "Submit" }).click();
await page.getByRole("heading", { name: "Dashboard" });

// 良い例: ラベルベース
await page.getByLabel("Email").fill("test@example.com");

// OK: アクセシブルなセレクターが存在しない場合は Test ID
await expect(page.getByTestId("balance")).toHaveText("$1,234");

// 悪い例: CSS セレクター
await page.locator(".btn-primary").click();

ユニットテスト (中)

unit-test-structure - @rules/unit-test-structure.md

ユニットテストは純粋な関数のみです。ソースファイルと同じ場所に配置してください。

// app/utils/format.test.ts
import { describe, test, expect } from "vitest";
import { formatCurrency } from "./format";

describe("formatCurrency", () => {
  test("formats positive amounts", () => {
    expect(formatCurrency(1234.5)).toBe("$1,234.50");
  });

  test("handles zero", () => {
    expect(formatCurrency(0)).toBe("$0.00");
  });
});

キーファイル

• e2e/tests/ - E2E テスト (Playwright)
• e2e/tests/utils.ts - E2E テストユーティリティ
• vitest.config.ts - ユニットテスト設定
• vitest.setup.ts - MSW を使用したグローバルテスト設定
• app/utils/test-utils.ts - ユニットテストユーティリティ