---
name: shared-testing-conventions
description: >-
  複数リポジトリで共有するテストの規約。テスト名を日本語の「◯◯こと」形にする命名規則、
  何をテストするかの選び方、テストファイルの配置、スナップショットの扱い、実行コマンドの調べ方。
  テストファイル（*.test.ts / *.test.tsx / tests/ 配下など）を追加・変更するとき、
  スナップショットを更新するとき、既存テストの失敗を直すときに使う。
paths: '**/*.test.ts,**/*.test.tsx,**/*.test.js,**/*.test.jsx,**/*.spec.ts,**/*.spec.tsx,tests/**,test/**,__tests__/**'
---

# テストのガイドライン

## 命名

`it` / `test` は日本語で、期待値が読み取れる「◯◯こと」の形。「◯◯する」だと動作の説明になり、何が保証されるのか分からない。

`describe` には関数名・コンポーネント名などの識別子を書かない。リネームしただけでテスト名が実態と合わなくなり負債になるため、プロダクトのどの振る舞いを守っているのかを日本語で書く。

```ts
// ❌ BAD
describe('renderMarkdown', () => {
  it('escapes HTML embedded in post content', () => {});
  it.each(posts)('%s の HTML を維持する', () => {});
});

// ✅ GOOD
describe('実績記事の本文表示', () => {
  it('本文に埋め込まれた HTML がエスケープされること', () => {});
  it.each(posts)('%s の HTML が変わらないこと', () => {});
});
```

変数名・関数名・コメント内の識別子は英語のままでよい。訳さない。

## 何をテストするか

- プロダクトの入出力を通す。入力は架空データを使い、実在の固有名や本番の実データ（実際のユーザー投稿文、実在の商品名・作品名など）は持ち込まない
- フィクスチャの置き場は適用先の既存の配置に従う。既に専用ディレクトリ（`tests/fixtures/` など）があればそこに置き、無ければ既存テストの慣例に合わせる
- ただしフィールドの形や本文の構造は本番相当にする（seed / マイグレーション / 実データが持つ構造とデータの幅に合わせる）
- ライブラリの仕様や API カタログをなぞるテストは書かない。壊れたときにユーザー影響が出る境界だけを対象にする
- 出力が HTML など大きなテキストならスナップショットで固定する。差分が製品影響として読めることを優先する

## 配置と書き方

- 実装の隣に `*.test.ts(x)` を置く
- フレームワークがディレクトリ構成をルーティングなどに使う場合だけ、その配下を避けて別のテストディレクトリに置く（例: Next.js Pages Router では `pages/` 配下が Next のルートとして扱われるため、ページのテストは `tests/` に置く）
- DOM が必要なファイルは、適用先が使っているテスト環境の指定方法に従う（Vitest + React なら先頭に `// @vitest-environment jsdom` を書き、`@testing-library/react` で描画・操作する）
- 適用先にタイムゾーンを固定する設定があるか確認する（`vitest.config.ts` / `jest.config.*` の環境変数指定、CI の `TZ` など）。あれば日付の期待値をローカル環境に合わせて書き換えない

## 実行

適用先の `package.json` の scripts を読み、テスト実行とスナップショット更新に用意されているコマンドを使う（パッケージマネージャは lockfile から判断する）。テストランナーを直接叩かず、リポジトリが定義したコマンド経由で実行する。

テスト名を変えるとスナップショットのキーも変わるので、スナップショット更新用のコマンドで更新する。