# テスト方針書

## 概要

本ドキュメントは、K-Shoot MANIA v1.xx（音楽ゲーム／譜面エディタ）のテスト方針を定義する。本プロジェクトはHot Soup Processor（HSP）3.51で開発されたWindowsネイティブアプリケーションであり、標準的なテストフレームワークが存在しないため、プロジェクト特性に合わせた実践的なテスト戦略を策定する。

### 対象システム

| 項目 | 内容 |
| --- | --- |
| プロジェクト名 | K-Shoot MANIA v1.xx |
| バージョン | 1.75b |
| 開発言語 | HSP 3.51（ANSI版、x86）+ C++（DLL） |
| 対応OS | Windows x86 |
| ソースコード規模 | 約19,945行（HSP）、34ファイル以上 |
| 主要コンポーネント | ゲーム本体（kshootmania.hsp）、譜面エディタ（kshooteditor.hsp） |

### テスト方針の前提条件

- HSPには標準的なユニットテストフレームワークが存在しない
- リアルタイム音声処理・グラフィックス描画を含むため、完全自動化は困難
- グローバル変数設計（`#module`～`#global`未使用）により、関数単位の分離テストが難しい
- DLL（ksmcore.dll、kson.dll、kshlib.dll）を介したC++コンポーネントとの連携がある
- CI/CDパイプラインは現時点で未導入

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | 個別の計算ロジック・データ変換処理の正確性を検証する | 開発者 |
| 結合テスト | シーン間遷移・モジュール間連携・DLL統合の動作を検証する | 開発者・QA |
| システムテスト | ゲーム全体としての動作・ユーザー体験を検証する | QA・テスター |
| 受入テスト | エンドユーザー視点で実際のプレイ体験・エディタ操作を検証する | テスター・ベータユーザー |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | 各機能（ノーツ判定、スコア計算、譜面読み込み等）の仕様適合性を確認する | 機能実装完了後 |
| 性能テスト | フレームレート維持（60fps）、メモリ使用量、大規模譜面での応答性を計測する | 結合テスト完了後 |
| セキュリティテスト | ファイルシステムアクセス、Win32 API呼び出しの安全性を検証する | リリース前 |
| 互換性テスト | 各Windowsバージョン、多言語環境、DirectX 9環境での動作を確認する | システムテスト時 |
| 回帰テスト | 変更による既存機能への影響がないことを確認する | 修正・変更のたびに実施 |
| ユーザビリティテスト | 操作性・UI表示・レスポンスの体感品質を検証する | システムテスト時 |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| 開発環境 | 単体テスト・デバッグ | Windows x86、HSP 3.51スクリプトエディタ、DirectX 9 SDK |
| テスト環境 | 結合テスト・システムテスト | Windows x86（物理マシンまたはVM）、DirectX 9対応GPU、オーディオデバイス |
| ステージング環境 | 受入テスト・最終検証 | 実際のユーザー環境に近い構成（複数Windows バージョン） |

### 必須ハードウェア要件

| 要件 | 詳細 |
| --- | --- |
| OS | Windows 7以降（x86/x64） |
| グラフィックス | Direct3D 9対応GPU |
| オーディオ | BASS Audio Library対応デバイス（ASIO/DirectSound/WASAPI） |
| 入力デバイス | キーボード、ゲームコントローラー（オプション） |
| HSPランタイム | HSP 3.51 ANSI版 |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| HSP 3.51 スクリプトエディタ | テストスクリプト実行・デバッグ | 3.51 |
| HSPデバッグウィンドウ | 変数値監視・ステップ実行 | HSP 3.51付属 |
| Windows Performance Analyzer | フレームレート・CPU使用率計測 | OS付属 |
| Process Monitor | ファイルI/O・レジストリアクセス監視 | Sysinternals |
| FRAPS / RivaTuner | フレームレートオーバーレイ計測 | 最新版 |
| テスト用HSPスクリプト | 計算ロジック・ファイル処理の自動検証 | カスタム作成 |

### テストスクリプト方針

HSPには標準テストフレームワークがないため、以下の方針でテストスクリプトを作成する。

1. **計算ロジック検証スクリプト**: スコア計算、コンボ計算、ジャッジ判定のロジックを抽出し、期待値との一致を `assert` マクロで検証する
2. **ファイル処理検証スクリプト**: KSH/KSON譜面ファイルのパース結果を検証するスクリプトを作成する
3. **設定値検証スクリプト**: 各種設定パラメータの範囲チェック・デフォルト値検証を行う

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 測定対象外（HSPにカバレッジ測定ツールなし） |
| 分岐カバレッジ | 測定対象外（HSPにカバレッジ測定ツールなし） |
| 機能カバレッジ | 100%（全機能のテストケース作成を目標とする） |
| シーンカバレッジ | 100%（全画面遷移パスの検証を目標とする） |

### カバレッジに関する補足

HSPはコンパイル言語であり、コードカバレッジ測定ツールが標準では存在しない。代替指標として以下を使用する。

- **機能カバレッジ**: 機能一覧に対するテストケースの網羅率
- **画面カバレッジ**: 全画面遷移パターンに対するテスト実施率
- **入力パターンカバレッジ**: 各入力パターン（キーボード、コントローラー、アナログ入力）に対するテスト網羅率

## テストデータ

### テストデータ準備方針

テストデータは以下のカテゴリに分類し、それぞれ準備する。

#### 譜面データ

| データ種別 | 内容 | 準備方法 |
| --- | --- | --- |
| 正常系譜面 | 標準的なKSH形式譜面ファイル | デフォルト同梱楽曲（`songs/K-Shoot MANIA/`）を使用 |
| 異常系譜面 | 不正フォーマット・欠損データの譜面 | テスト用に手動作成 |
| 境界値譜面 | BPM極端値、大量ノーツ、長時間譜面 | テスト用に手動作成 |
| KSON形式譜面 | KSON仕様に準拠した譜面 | テスト用に手動作成 |
| マルチバイト譜面 | 日本語・韓国語・中国語を含む譜面メタデータ | テスト用に手動作成 |

#### 設定データ

| データ種別 | 内容 | 準備方法 |
| --- | --- | --- |
| デフォルト設定 | 初回起動時の設定値 | アプリ初期化処理の値を使用 |
| カスタム設定 | HI-SPEED、エフェクト設定等のバリエーション | テスト用パターンを網羅的に準備 |
| 言語設定 | 各言語ファイル（日/英/韓/簡中/繁中） | `lang/`ディレクトリの既存ファイルを使用 |

#### リソースデータ

| データ種別 | 内容 | 準備方法 |
| --- | --- | --- |
| 画像リソース | UI画像、背景画像、ジャケット画像 | `imgs/`ディレクトリの既存ファイルを使用 |
| 音声リソース | BGM、効果音、ノート音 | `se/`ディレクトリの既存ファイルを使用 |
| 欠損リソース | 必須ファイルが存在しないケース | テスト用に一時的にリネーム・削除 |

## 不具合管理

### 不具合管理方法

| 項目 | 内容 |
| --- | --- |
| 管理ツール | GitHub Issues（推奨）またはスプレッドシート |
| 重要度分類 | Critical / Major / Minor / Trivial |
| 優先度分類 | High / Medium / Low |
| ワークフロー | 起票 → 担当割り当て → 調査 → 修正 → 検証 → クローズ |

### 重要度定義

| 重要度 | 定義 | 例 |
| --- | --- | --- |
| Critical | ゲームが起動しない・クラッシュする | DLL読み込み失敗、メモリ不足 |
| Major | 主要機能が正常に動作しない | ノーツ判定ミス、スコア計算エラー、譜面読み込み失敗 |
| Minor | 動作に支障はないが正しくない挙動 | 表示崩れ、設定保存漏れ、軽微な計算誤差 |
| Trivial | 体験への影響が極めて小さい | 文言の誤字、アイコン不整合 |

## CI/CD連携

### 現状

CI/CDパイプラインは現時点で未導入である。HSP 3.51のビルドプロセスはHSPスクリプトエディタを使用した手動ビルドのみ対応している。

### 推奨CI/CD構成

将来的に自動化を導入する場合の推奨構成を以下に示す。

| フェーズ | 内容 | ツール |
| --- | --- | --- |
| ビルド | HSPコマンドラインコンパイル | hspcmp（HSPコマンドラインコンパイラ） |
| 静的解析 | HSPスクリプトの構文チェック | カスタムスクリプト |
| 単体テスト | 計算ロジック・ファイル処理テスト | テスト用HSPスクリプト |
| パッケージング | リリースパッケージ作成 | バッチスクリプト / PowerShell |
| 配布 | リリースアーティファクトのアップロード | GitHub Releases |

### 自動化の優先順位

| 優先度 | 対象 | 理由 |
| --- | --- | --- |
| 高 | ビルド検証（コンパイル成功確認） | 最小限のコストで回帰防止効果が得られる |
| 高 | 計算ロジックテスト | 分離可能でテストスクリプト化しやすい |
| 中 | ファイル処理テスト（譜面パース） | 入出力が明確で自動化しやすい |
| 低 | UIテスト | HSPのUI操作は自動化困難 |
| 低 | オーディオ・グラフィックステスト | ハードウェア依存で自動化困難 |

## テスト対象・対象外

### テスト対象

| カテゴリ | 対象 | 主なテスト観点 |
| --- | --- | --- |
| ゲーム本体 | kshootmania.hsp（2,516行） | 全シーン動作、ゲームプレイ、スコア計算 |
| 譜面エディタ | kshooteditor.hsp（17,429行） | 譜面作成・編集操作、ファイル入出力 |
| シーン処理 | src/scene/（18ファイル、約14,500行） | 画面遷移、各画面の機能動作 |
| オーディオ処理 | src/audio/（3ファイル） | エフェクト適用、キー音再生、スラム音 |
| ユーティリティ | src/（winapi.as、filesystem_utils.as等） | ファイル操作、API呼び出し |
| DLL連携 | ksmcore.dll、kson.dll、kshlib.dll | DLL呼び出しの正常動作 |
| 多言語対応 | lang/（5言語） | 各言語での表示・動作 |

### テスト対象外

| カテゴリ | 理由 |
| --- | --- |
| サードパーティライブラリ（third_party/） | 外部提供のライブラリであり、本プロジェクトの責任範囲外 |
| VSTプラグイン（lib/） | 外部ベンダー提供のプラグインであり、統合テストでの動作確認のみ行う |
| BASS Audio Library（bass.dll等） | 外部ライブラリであり、API呼び出し層での検証のみ行う |
| 削除済み機能（INPUT GATE、Twitter連携、IR） | 既にコードから無効化されている機能 |
| HSPランタイム自体の動作 | HSP処理系の不具合は本プロジェクトの責任範囲外 |

## リスクと対策

| リスク | 影響度 | 対策 |
| --- | --- | --- |
| HSPにテストフレームワークがない | 高 | テスト用HSPスクリプトをカスタム作成する |
| グローバル変数設計によりテスト分離が困難 | 高 | 検証対象ロジックを切り出したテスト専用スクリプトで検証する |
| リアルタイム処理の自動テストが困難 | 中 | 手動テスト手順書を整備し、重要パスは手動で繰り返し検証する |
| ハードウェア依存（DirectX 9、BASS Audio） | 中 | 複数環境でのテスト実施と互換性チェックリストを作成する |
| テスト工数の増大（手動テスト主体） | 中 | テスト優先順位を明確化し、リスクベースでテスト範囲を決定する |

## 備考

### プロジェクト固有の考慮事項

1. **コード品質**: README.mdにて「ひどいソースコード」と明記されており、プログラミング経験不足の時期に書かれた基盤コードである。共通処理のコピペ改変やマジックナンバーが多いため、テスト時にはロジックの意図を慎重に確認する必要がある

2. **パフォーマンス最適化**: HSPではコンパイル時最適化が行われないため、マジックナンバー（計算済みの値）がハードコードされている。テストケース作成時には、これらの値の根拠を設計ドキュメントから確認する

3. **既存設計ドキュメント**: 機能設計書（266個）、画面設計書（21個）、帳票設計書（13個）等の自動生成ドキュメントが整備されている。テストケース作成時にはこれらのドキュメントを参照する

4. **主要テスト観点（ゲーム固有）**:
   - 60fps維持のフレームレート安定性
   - ノーツ判定の正確性（CRITICAL/NEAR/ERROR判定）
   - オーディオ同期（音声と映像のずれ）
   - BPM変化・速度変化時の表示正確性
   - HI-SPEED設定によるスクロール速度の適切な反映
   - コースモードでの連続プレイ安定性
