Testing Guide

本ガイドは、プロジェクトにおけるテストの分類、配置規則、および汎用検証チェックリスト（チェックリスト・テスト仕様書）の作成規約とテンプレートを定義するものです。

1. テストの分類と配置規則

テストの種類、対象、および配置場所は以下のとおりです。

テスト種別	対象・説明	配置場所
単体テスト	個別の関数・クラス・モジュール単位の検証	ソフトウェアコンポーネントのソースコード
コンポーネントテスト (統合テスト)	コンポーネントが別のコンポーネントを使用する結合・統合検証	`<test:appid>` (`<root>/tests/<BaseDir>/`)
パフォーマンス・負荷テスト	性能要件、高負荷時の応答性・耐久性の検証	`<root>/tests/performance/`
セキュリティ・脆弱性テスト	脆弱性、認証・認可、攻撃耐性の検証	`<root>/tests/security/`
汎用検証チェックリスト	パフォーマンス・セキュリティ以外の汎用的な検証チェックリスト	`<root>/tests/checklists/`

単体テスト: ソフトウェアコンポーネントのソースコード内（ソースコードと同一ディレクトリまたはコンポーネント内）に配置します。
コンポーネントテスト (統合テスト): あるコンポーネントが別のコンポーネントを利用するテストは、<test:appid>（<root>/tests/<BaseDir>/）に配置します。
パフォーマンス・負荷テスト: システムの負荷やパフォーマンスに関するテストは、<root>/tests/performance/ 配下に配置します。
セキュリティ・脆弱性テスト: セキュリティ検証や脆弱性テストは、<root>/tests/security/ 配下に配置します。
汎用検証チェックリスト: パフォーマンス・負荷テストおよびセキュリティ・脆弱性テスト以外の汎用的な検証チェックリストは、<root>/tests/checklists/ 配下に配置します。

単方向参照の原則 (`tests/` ➔ `docs/`)

テスト（<root>/tests/）は、設計・仕様（<root>/docs/）およびステータスを管理するバックログ（backlog/）とは明確に分離された独立領域です。

単方向参照: <root>/tests/ のテストコードやテスト仕様書は、検証対象として <root>/docs/ 配下のユースケース（docs/usecases/USECASE-XXX.md）や機能仕様書（docs/[<group>/]<component>/specs/SPEC-XXX.md）を参照します。
逆方向参照の禁止: <root>/docs/ および backlog/ からは原則として <root>/tests/ を参照せず、ドキュメント・バックログ側にテストへの逆方向依存を持ち込みません。

2. 汎用検証チェックリストの構成

汎用検証チェックリスト（<root>/tests/checklists/）は、「チェックリスト（テスト仕様台帳）」と「テスト仕様書」で構成します。

フロントマターの記述規則

チェックリストおよびテスト仕様書のすべての Markdown ファイルには、docs/AGENTS.md と同様に以下のフロントマター項目を必ず記述します。

name（ファイル名）、description（1行概要）、timestamp（YYYY-MM-DD 形式）、ai（作成区分: none [人間のみ]、ai-assisted [人間執筆・AI校正]、ai-coauthored [人間設計・AI執筆]、ai-generated [AI生成]）。

チェックリスト (テスト仕様台帳)

チェックリストは、配下のテスト仕様書を一覧管理する台帳ファイルです。

配置場所: <root>/tests/checklists/checklist-<name>.md
役割: テスト対象機能群やサブシステム（<name>）に対応するテスト仕様の台帳として機能します。
台帳フォーマット:
```
| ID | 概要 | 状態 | Timestamp |
| :--- | :--- | :--- | :--- |
| [`TESTSPEC-001`](<name>/TESTSPEC-001.md) | テスト仕様の概要 | 不適合 | 2026-08-31 |
```
- ID: テスト仕様（<TESTSPEC-ID>）への相対リンクを記述します。
- 概要: テスト仕様の簡潔な説明を記述します。
- 状態: 適合 または 不適合 を記述します（初期値は 不適合）。
- Timestamp: 最終更新日（YYYY-MM-DD 形式）を記述します。

テスト仕様書 (`<TESTSPEC-ID>.md`)

テスト仕様書は、個別の検証シナリオやテスト項目を管理する仕様書です。

ID形式: <TESTSPEC-ID>（例: TESTSPEC-001）
ファイル名: <TESTSPEC-ID>.md
配置場所: <root>/tests/checklists/<name>/<TESTSPEC-ID>.md
構成セクション:
1. 概要: テストの目的や対象機能の概要を記述します。また、単方向参照の原則に基づき、検証対象となるユースケース（docs/usecases/USECASE-XXX.md）または機能仕様書（docs/[<group>/]<component>/specs/SPEC-XXX.md）への参照リンクを記述します。
2. 手順: テストを実行する前提条件や実施手順を記述します。
3. テスト項目表: 個別の検証項目を一覧表形式で記述します。
テスト項目表フォーマット:
```
| ID | 検証内容 | 事前条件 | 適合条件 | 状態 | Timestamp | 備考 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| TEST-001 | 検証内容の説明 | テスト実行前の前提状態 | パスと判定する期待結果 | 不適合 | 2026-08-31 | - |
```
- ID: ID形式 <TEST-ID>（例: TEST-001）を採番します。
- 検証内容: 具体的に検証する振る舞いやシナリオを記述します。
- 事前条件: テスト実施時に必要な前提条件・初期データを記述します。
- 適合条件: 検証が成功したとみなす期待結果を記述します。
- 状態: 適合 または 不適合 を記述します（初期値は 不適合）。
- Timestamp: 検証・更新を行った日付（YYYY-MM-DD 形式）を記述します。
- 備考: 補足事項を記述します。テスト項目の詳細を記述する場合は 詳細:<TESTSPEC-ID> と記載します。

テスト項目の詳細セクション (任意)

テスト項目表の後に、必要に応じて 詳細:<TESTSPEC-ID> 章を設けて詳細な手順や確認ログを記述できます。

任意記述: 本セクションの記述は任意であり、必須ではありません。
備考との対応: 本セクションで詳細を記述したテスト項目は、テスト項目表の「備考」列に 詳細:<TESTSPEC-ID> を記述します。

3. 状態管理と連動ルール

チェックリスト（テスト仕様台帳）およびテスト仕様書内のテスト項目は、以下のルールに従って状態を管理します。

状態の種類: 状態（ステータス）は 適合 または 不適合 のいずれかをとります。
初期状態: テスト仕様台帳およびテスト項目の初期状態はすべて 不適合 です。
状態連動: テスト仕様書内のすべてのテスト項目が 適合 になったとき、チェックリスト（テスト仕様台帳）の対応するテスト仕様の状態が 適合 に更新されます。1つでも 不適合 の項目がある場合、テスト仕様台帳の状態は 不適合 のままとなります。

4. テンプレート

チェックリスト (テスト仕様台帳) テンプレート (`checklist-<name>.md`)

---
name: checklist-<name>.md
description: <機能・サブシステムの検証チェックリスト>
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# Checklist: <name>

## テスト仕様台帳

| ID | 概要 | 状態 | Timestamp |
| :--- | :--- | :--- | :--- |
| [`TESTSPEC-001`](<name>/TESTSPEC-001.md) | <テスト仕様1の概要> | 不適合 | YYYY-MM-DD |
| [`TESTSPEC-002`](<name>/TESTSPEC-002.md) | <テスト仕様2の概要> | 不適合 | YYYY-MM-DD |

テスト仕様書テンプレート (`<TESTSPEC-ID>.md`)

---
name: TESTSPEC-001.md
description: <テスト仕様の概要>
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# TESTSPEC-001: <テスト仕様名>

## 概要

<テスト仕様全体の概要および検証対象の機能を記述します。>

-   **対象仕様**: [`USECASE-001`](docs/usecases/USECASE-001.md) または [`SPEC-001`](docs/<group>/<component>/specs/SPEC-001.md)

## 手順

1.  <テスト実施の準備・環境セットアップ手順を記述します。>
2.  <テスト実行の手順を順序立てて記述します。>

## テスト項目表

| ID | 検証内容 | 事前条件 | 適合条件 | 状態 | Timestamp | 備考 |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| TEST-001 | <検証内容1> | <前提条件1> | <期待結果1> | 不適合 | YYYY-MM-DD | - |
| TEST-002 | <検証内容2> | <前提条件2> | <期待結果2> | 不適合 | YYYY-MM-DD | 詳細:TESTSPEC-001 |

## 詳細:TESTSPEC-001

### TEST-002 の詳細

<TEST-002 に関する詳細な検証手順、確認コマンド、期待される出力ログなどを記述します。>

Keyboard shortcuts