テスト作成ガイド

意図

新しいテストを docs/TESTING.md の方針に従って作成する。 テストは仕様の表現であり、「このテストが通れば仕様を満たしている」という信頼性を構築する。

作成手順

1. 対象の理解

引数で指定されたモジュール・機能を確認する。

• •対象の ソースコード を読む
• •対象パッケージの README.md を読み、公開仕様を把握する
• •既存テスト があれば読み、現在のカバレッジを理解する

2. TESTING.md の方針を読む

docs/TESTING.md を読み、現在の方針を確認する。

3. テスト設計

TDD vs Spike → Test の判断

テスト対象の優先度

リスクベースで優先度をつける:

1. •公開 API の契約 — 必ずテスト
2. •エッジケース・境界値 — バグの温床を先に潰す
3. •cleanup / dispose — リソースリークは致命的
4. •エラーハンドリング — 必要に応じて
5. •内部ヘルパー — 公開 API 経由でカバーできるなら不要

テスト対象の優先度をユーザーに提案し、合意を得てからテストを書く。

4. テスト実装

ファイル配置

packages/<name>/src/__tests__/<module>.test.ts

テンプレート

import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
// 対象モジュールの import

describe("<対象名>", () => {
  // 必要に応じてセットアップ
  // let container: HTMLElement;
  // beforeEach(() => { ... });
  // afterEach(() => { ... });

  it("<動詞で始まる振る舞いの説明>", () => {
    // Arrange
    // Act
    // Assert
  });
});

実装ルール

• •AAA パターン を守る（Arrange-Act-Assert）
• •命名: describe = 対象名、it = 動詞で始める、should は使わない
• •振る舞いをテスト する。実装の内部状態に依存しない
• •1 テスト 1 概念: 1 つの it で 1 つの振る舞いを検証
• •独立性: テスト間の順序依存を作らない
• •モックは最小限: 外部依存（DOM API, タイマー）の置き換えに限定

DOM テストのセットアップ

mount() を使うテストでは:

let container: HTMLElement;

beforeEach(() => {
  container = document.createElement("div");
  document.body.appendChild(container);
});

afterEach(() => {
  container.remove();
});

グローバル状態のリセット

グローバル状態を持つパッケージでは:

import { __resetForTesting__ } from "../state";

beforeEach(() => {
  __resetForTesting__();
});

5. テストの実行と確認

テストを書いたら実行して確認:

pnpm test:run --filter <package-name>

• •Red（失敗）→ Green（成功）の流れを確認（TDD の場合）
• •全テストが独立して通ることを確認

現時点の方針

• •テスト作成前に対象の仕様を把握し、何をテストすべきかをユーザーと合意する
• •「このテストは何のリスクを軽減しているか」を常に問う
• •カバレッジ向上が目的のテストは書かない

今後の検討事項

• •Property-based testing の導入可能性（特に parser 系の関数）
• •テストヘルパーの共通化（DOM セットアップ、mount ラッパーなど）
• •Snapshot テストの採否（コンポーネント出力の回帰テスト）