> ## Documentation Index
> Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# コンポーネントテストとは — 振る舞いを検証するテスト

> VitestとTesting Libraryで、実装の詳細ではなくユーザーが観察できる振る舞いを検証するコンポーネントテストの原則と実践パターンを解説します。

## 概要

コンポーネントテストとはコンポーネントを実際に描画し、ユーザーの操作を再現して、画面に現れる結果を検証するテストです。Testing Trophyでは、バックエンドとの境界をモックして振る舞いを検証するIntegration層にあたり、ツールにはVitestとTesting Libraryを使います。層の全体像は[テスト戦略](https://lib.findy.co.jp/ja/frontend/testing-strategy.md)を参照してください。

本ページでは、コンポーネントテストが検証する対象を決める原則と、VitestとTesting Libraryで安定したテストを書く実践パターンを扱います。見た目の変化の検証はStorybookと[ビジュアルリグレッションテスト](https://lib.findy.co.jp/ja/frontend/visual-regression-testing.md)の役割で、本ページでは扱いません。

個々のテストを信頼できる状態に保つ共通の原則（実行状態の検証、期待値の全体の検証、外部境界のモック）は[テストコード](https://lib.findy.co.jp/ja/development/testing.md)を参照してください。本ページはその原則をコンポーネントに適用したものです。

## 原則

### 実装の詳細ではなく、ユーザーが観察できる振る舞いを検証する

コンポーネントテストの対象はユーザーが見て操作できるものです。Testing Libraryはこの方針を「テストがソフトウェアの使われ方に似ているほど、テストが与える信頼度は高くなる」という指針で表し、コンポーネントのインスタンスではなくDOMノードを扱うAPIだけを提供します。

コンポーネントには2種類の利用者がいます。描画された画面を操作するエンドユーザーと、propsを渡す開発者です。テストもこの2つの立場からだけコンポーネントに触れ、内部の状態、子コンポーネントに渡したprops、CSSクラス名のような実装の詳細には依存しません。

実装の詳細に依存したテストは、2つの方向で信頼できなくなります。構造を整理しただけで失敗する偽陰性と、画面が壊れていても内部の値が期待どおりなら通る偽陽性です。

```tsx Vitest + Testing Library theme={null}
import { render, screen } from "@testing-library/react";
import { OrderList } from "./OrderList";
import { OrderRow } from "./OrderRow";

const orders = [
  { id: "1001", status: "paid", total: 3200 },
  { id: "1002", status: "pending", total: 1800 },
];

// ❌ 子コンポーネントを差し替え、渡されたpropsを検証している
// （子の表示が壊れても通り、子を統合しただけで失敗する）
vi.mock("./OrderRow", () => ({ OrderRow: vi.fn(() => null) }));
render(<OrderList orders={orders} />);
expect(OrderRow).toHaveBeenCalledWith(
  expect.objectContaining({ status: "paid" }),
  expect.anything()
);

// ✅ 本物のコンポーネントツリーを描画し、ユーザーが見る結果を検証する
render(<OrderList orders={orders} />);
expect(screen.getByRole("row", { name: /1001/ })).toHaveTextContent("支払い済み");
expect(screen.getByRole("row", { name: /1002/ })).toHaveTextContent("未払い");
```

### 狭義のユニットテストと広義のユニットテストを使い分ける

ユニットテストには2つの意味があります。狭義のユニットテストは単一の関数を対象にし、金額の計算や日付範囲の正規化のような純粋なロジックを、描画を伴わないUnit層で入力と出力から検証します。

広義のユニットテストは、フックとコンポーネントの組み合わせが生み出す1つの振る舞いを対象にします。Reactのフックは多くの場合に関数を返すため、関数を1つずつ分離して検証しても画面が正しく振る舞う保証にはならず、振る舞いの単位でテストします。本ページのコンポーネントテストはこの広義のユニットテストにあたります。

この2つを使い分ける必要があるのは、どちらも同じテストランナー（Vitest）で実行され、同じテストファイルに書かれることが多いためです。関数の入出力を確かめる観点と、描画された画面の振る舞いを確かめる観点が1つのファイルに混ざると、一方のテストばかりが厚くなり、もう一方が薄くなっていても気づきにくくなります。テストを書くときは、どちらの観点で検証しているかを意識して区別します。

> [card] 狭義のユニットテスト（Unit層）
>
> 純粋な関数の入力と出力。金額計算、日付の正規化、ソートの比較関数。描画を伴わず、Vitestだけで検証します。

> [card] 広義のユニットテスト（Integration層）
>
> コンポーネントとフックが組み合わさった振る舞い。操作に対する画面の変化を、Testing Libraryで検証します。

### 型で保証できることはStatic層に委ねる

コンポーネントテストはStatic層の上に成り立ちます。TypeScriptの型がpropsや状態の取りうる値を限定していれば、その範囲の外にある値（渡せないundefined、存在しないステータスなど）はコンパイルが拒否するため、コンポーネントテストで検証する必要はありません。検証はその失敗を検出できる最も低い層に置くという[テスト戦略](https://lib.findy.co.jp/ja/frontend/testing-strategy.md)の原則を、Static層とIntegration層の間に適用したものです。

型が検証を引き受ける場面は多くあります。ある項目がnullになりうるのかundefinedになりうるのかを型が保証していれば、両方の場合のテストは不要で、型が許す側だけを検証します。取りうる値を文字列リテラルの合併型で限定したステータスや、必須と任意を区別したpropsも同じです。型が排除した値をテストから外すほど、コンポーネントテストは振る舞いの検証に集中できます。

```tsx Vitest + Testing Library theme={null}
import { render, screen } from "@testing-library/react";
import { OrderRow } from "./OrderRow";

// 注文の型。取りうる値を型で限定している
type Order = {
  id: string;
  status: "pending" | "paid" | "shipped";
  shippedAt: string | null;
  total: number;
};

const order: Order = {
  id: "1001", status: "paid", shippedAt: null, total: 3200,
};

// ❌ 型が排除している値まで検証している
// （undefinedは渡せず、未知のステータスはコンパイルエラーになる）
render(<OrderRow order={{ ...order, shippedAt: undefined }} />);
render(<OrderRow order={{ ...order, status: "unknown" }} />);

// ✅ 型が許す値だけを検証する（nullのときの表示と、3つのステータス）
render(<OrderRow order={{ ...order, shippedAt: null }} />);
expect(screen.getByText("未発送")).toBeInTheDocument();
```

この分担はモックにも及びます。バックエンドの応答を差し替えるときにAPIを提供する側の型を付けておけば、APIの仕様変更はコンポーネントテストではなくStatic層の型チェックが検出します。具体的な方法は実践パターンの「モックの応答にはAPIを提供する側の型を付ける」のとおりです。

## VitestとTesting Libraryでの実践パターン

以下のパターンは注文一覧の画面を題材にします。画面はステータスで注文を絞り込むフォームと、取得した注文を表示する表からなります。コード例はVitestのグローバルAPI（`test`、`expect`、`vi`）と、`@testing-library/jest-dom`のマッチャーを前提としています。

### ユーザーが見つけるのと同じ方法で要素を取得する

Testing Libraryのクエリには優先順位があります。最優先はすべてのユーザーに見える手がかりで要素を見つけるクエリで、ロールと名前で探す`getByRole`、ラベルで探す`getByLabelText`、表示文字列で探す`getByText`が属します。

`getByTestId`は最後の手段です。テスト用の属性はユーザーには見えず、聞こえず、要素がロールや名前で見つからないこと自体が、アクセシビリティに問題がある可能性を示しています。DOM構造に依存する`container.querySelector`も構造を整理しただけで失敗するため使いません。

```tsx Vitest + Testing Library theme={null}
import { render, screen } from "@testing-library/react";
import { OrderSearch } from "./OrderSearch";

const { container } = render(<OrderSearch />);

// ❌ テスト用の属性やDOM構造に依存している
// （ユーザーには見えない手がかりで、構造を整理すると失敗する）
screen.getByTestId("status-select");
container.querySelector("form > button.primary");

// ✅ ユーザーが見つけるのと同じ手がかりで取得する
// （ラベルとボタン名が変わらない限り、構造を変えても通る）
screen.getByLabelText("ステータス");
screen.getByRole("button", { name: "検索" });
```

### 操作はuser-eventで再現する

ユーザーの操作は`@testing-library/user-event`で再現します。`fireEvent`は単一のDOMイベントを発火するだけですが、`user-event`はクリック時のフォーカス移動やキー入力ごとのイベント列のように、ブラウザで実際に起きる一連のイベントを再現します。

テストの先頭で`userEvent.setup()`を呼び、返されたインスタンスで操作します。操作は非同期なので`await`を付けます。

```tsx Vitest + Testing Library theme={null}
import { fireEvent, render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { OrderSearch } from "./OrderSearch";

render(<OrderSearch />);

// ❌ changeイベントを1つ発火するだけで、ユーザーの操作とは異なる
// （フォーカスやキー入力に反応するロジックは動かない）
fireEvent.change(screen.getByLabelText("ステータス"), {
  target: { value: "paid" },
});

// ✅ ブラウザで起きるイベント列を再現する
const user = userEvent.setup();
await user.selectOptions(screen.getByLabelText("ステータス"), "paid");
await user.click(screen.getByRole("button", { name: "検索" }));
```

### 非同期の画面変化は要素の出現で待つ

データの取得後に現れる要素は`findBy`系のクエリで待ちます。`findBy`は要素が現れるまで再試行し、見つからなければ既定の1秒で失敗するクエリです。固定時間の待機は短すぎると不安定になり、長すぎるとスイート全体を遅くします。

要素が消えたことや存在しないことは、`queryBy`系のクエリで検証します。`getBy`は見つからないと例外を投げるため、不在の検証には使えません。要素の有無以外の条件を待つときは`waitFor`を使います。

```tsx Vitest + Testing Library theme={null}
import { render, screen, waitFor } from "@testing-library/react";
import { OrderSearch } from "./OrderSearch";

render(<OrderSearch />);

// ❌ 固定時間を待ってから取得している
// （応答が遅いと失敗し、速くてもテストは遅いまま）
await new Promise((resolve) => setTimeout(resolve, 500));
screen.getByRole("table");

// ✅ 要素が現れるまで待ち、読み込み中の表示が消えたことも検証する
expect(await screen.findByRole("table")).toBeInTheDocument();
expect(screen.queryByText("読み込み中")).not.toBeInTheDocument();

// ✅ 要素の有無以外の条件はwaitForで待つ
await waitFor(() => {
  expect(screen.getAllByRole("row")).toHaveLength(3);
});
```

### 画面と独立したロジックのフックはrenderHookで検証する

`renderHook`はフックをコンポーネントの外で実行し、戻り値を`result.current`から読むためのAPIです。`@testing-library/react`からインポートし、状態を更新する関数の呼び出しは`act`で囲みます。

対象は複数の画面から使われるロジックのフックや、UIを持たないフックです。1つの画面のためだけに存在するフックは、その画面のコンポーネントテストで操作を通して検証します。両方で検証すると、同じ振る舞いのテストが2重になり、変更のたびに2か所を直すことになります。

```tsx Vitest + Testing Library theme={null}
import { act, renderHook } from "@testing-library/react";
import { useOrderFilter } from "./useOrderFilter";

const orders = [
  { id: "1001", status: "paid", total: 3200 },
  { id: "1002", status: "pending", total: 1800 },
];

// ❌ 画面のためのフックを単体で検証し、
// 同じ振る舞いをコンポーネントテストと2重に持っている
renderHook(() => useOrderSearchForm());

// ✅ 複数の画面から使われるロジックのフックを、戻り値で検証する
const { result } = renderHook(() => useOrderFilter(orders));
expect(result.current.filtered).toHaveLength(2);

act(() => {
  result.current.setStatus("paid");
});
expect(result.current.filtered.map((o) => o.id)).toEqual(["1001"]);
```

### バックエンドとの境界だけをモックする

コンポーネントテストでモックするのは、バックエンドとの境界だけです。応答はMock Service Worker（msw）でネットワークの境界で差し替えます。コンポーネントから見ると本物のHTTP通信が行われているため、APIクライアントやデータ取得のフックは本物のまま動き、モックの応答を解釈する処理の誤りまでテストが検出します。

子コンポーネント、フック、状態管理のストアは差し替えません。これらはコンポーネントが振る舞いを生み出す構成要素であり、差し替えると[テストコード](https://lib.findy.co.jp/ja/development/testing.md)のパターン3で述べる「検証対象のロジックそのものをモックする」状態になります。差し替えたテストは、実装がどう変わっても通り続けます。現在時刻やランダム値のような、ネットワーク以外の外部境界の扱いも同じページを参照してください。

正常系の応答はセットアップファイルに登録し、エラー応答のようなテスト固有の応答は`server.use`でそのテストだけ上書きします。各テスト後に`resetHandlers`で上書きを戻し、テスト間の独立性を保ちます。

```typescript vitest.setup.ts theme={null}
import { afterAll, afterEach, beforeAll } from "vitest";
import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

export const server = setupServer(
  // 正常系の応答。すべてのテストで共有する
  http.get("/api/orders", () =>
    HttpResponse.json([
      { id: "1001", status: "paid", total: 3200 },
      { id: "1002", status: "pending", total: 1800 },
    ])
  )
);

beforeAll(() => server.listen());
// テストごとの上書きを戻し、テスト間の独立性を保つ
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

```tsx Vitest + Testing Library theme={null}
import { render, screen } from "@testing-library/react";
import { http, HttpResponse } from "msw";
import { server } from "../vitest.setup";
import { OrderSearch } from "./OrderSearch";

// ❌ データ取得のフックを差し替えている
// （APIの応答の形が変わっても検出できない）
vi.mock("./useOrders", () => ({
  useOrders: () => ({ data: [], error: new Error("failed") }),
}));

// ✅ このテストだけエラー応答に上書きし、画面の反応を検証する
test("取得に失敗したらエラーを表示する", async () => {
  server.use(
    http.get("/api/orders", () =>
      HttpResponse.json({ message: "unavailable" }, { status: 500 })
    )
  );
  render(<OrderSearch />);

  expect(await screen.findByRole("alert")).toHaveTextContent(
    "注文を取得できませんでした"
  );
});
```

### モックの応答にはAPIを提供する側の型を付ける

mswで応答を差し替えている限り、実際のAPIの仕様が変わってもコンポーネントテストは通り続けます。ハンドラーを実際のAPIの仕様から乖離させないために、APIを提供する側から型情報を得て、ハンドラーの応答にその型を付けます。型の出所はOpenAPIドキュメントやGraphQLスキーマから生成した型、またはバックエンドと共有する型定義です。

型を付けておけば、APIの仕様変更はコンポーネントテストではなくStatic層の型チェックが検出します。コンポーネントテストは正しいと分かっているモックの上で動き続け、モックの正しさを型で担保することがこの層のテストの品質を支えます。原則で述べたStatic層との分担を、モックに適用したものです。

```typescript vitest.setup.ts theme={null}
// APIを提供する側から生成した型（OpenAPIやGraphQLスキーマなど）
import type { Order } from "./api/types";

// ❌ 応答の形を手で書いている（stateという誤りに気づけない）
// （APIの仕様が変わっても、モックもテストも通り続ける）
http.get("/api/orders", () =>
  HttpResponse.json([{ id: "1001", state: "paid", total: 3200 }])
);

// ✅ ハンドラーの第3の型引数で応答の型を付ける
// （フィールド名や型が変われば、テストを実行する前に型チェックが失敗する）
http.get<never, never, Order[]>("/api/orders", () =>
  HttpResponse.json([{ id: "1001", status: "paid", total: 3200 }])
);
```

## 関連ページ

以下のページで、コンポーネントテストを置く層の判断と、その上下の層の詳細を扱います。

> [card] [テスト戦略](https://lib.findy.co.jp/ja/frontend/testing-strategy.md)
>
> 検証をどの層に置くかの判断基準。コンポーネントテストがIntegration層で最も広い理由。

> [card] [テストコード](https://lib.findy.co.jp/ja/development/testing.md)
>
> 本ページの原則の土台。実行状態の検証、期待値の全体の検証、外部境界のモック。

> [card] [E2Eテスト](https://lib.findy.co.jp/ja/frontend/e2e-testing.md)
>
> モックでは検出できないバックエンドとの連携を、主要な動線に絞って守る方法。

> [card] [ビジュアルリグレッションテスト](https://lib.findy.co.jp/ja/frontend/visual-regression-testing.md)
>
> 同じ層の見た目の側。DOMのクエリには見えないものを、ストーリーとスナップショットで検証します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.