テスト仕様 (Test Specification)

方針 (Policy)

リファクタリング等，挙動を変えない変更で処理が変わっていないことを確認するためのテスト仕様．

テストの種類:

ビルドテスト: コンパイルエラーがないことを確認する
結合ロジックテスト: 偽カメラとヘッドレス Form1 で，撮影・保存の流れと失敗時の通知を NUnit で自動確認する（[Category("Integration")]．方針は .claude/rules/testing.md，移行計画は PLAN_05）
回帰テスト: リファクタリング前後の出力が一致することを確認する
セルフテスト: 実機なしで依存ロード・プレビュー経路・校正〜保存を自動確認する（手動テストの前段）
実機テスト: Claude が実機のカメラと光源を操作して，接続・プレビュー・露光/ゲイン・光源・閉じる処理・再接続と，実物の舌診チャートでの校正・撮影と保存・保存中/校正中に閉じる処理を自動確認する（ユーザーの合図があるときだけ．手動テストの前段）
手動テスト: 実機を使って動作を目視確認する

セルフテスト (Self Test)

依存更新やハードウェア結合層の変更後，手動テストの前に実施する（Debug|x64 のみ．手順は ENV_04 の「セルフテスト」，判定は .claude/verify-profile.md．/verify から自動実行できる）．

python scripts/verify/run_selftest.py（依存を変えた場合は --full）
合格条件: 終了コード 0（deps・preview・calib-save の 3 項目が PASS）
代替していない範囲（実カメラ SDK との結合・実プレビュー表示・実チャートの検出性能・画像の見た目・長時間のメモリ/GDI）は，下記の実機テストと手動テストで確認する

実機テスト (Hardware Test)

Claude が実機のカメラと光源を操作して，層④のうち数値で判定できる項目を自動で確認する（PLAN_06．Debug|x64 のみ．手順は ENV_04 の「実機テスト」，判定としきい値の詳細は .claude/verify-profile.md の「実機テスト」節）．ユーザーの合図があるときだけ実行する（撮影の本番中に機材を操作しないため）．

python scripts/verify/run_hwtest.py --camera <lucam|iscam>（対象は ImagingSource の --camera iscam だけ．Lumenera の実機テストは行わない．PLAN_06「対象機種」）
続けて python scripts/verify/run_hwtest.py --camera iscam --with-chart（チャートが必要な検査．カラーチャートをはめたまま実行する．--with-chart ではチャート不要の検査を行わないため，両方を実行する）
実行の前提: カメラ・光源のドライバが入っている（ENV_02），検査する機種のカメラと光源が接続されている，カメラの前の穴にカラーチャート（または白板）がはめてある，TIASshot が起動していない
合格条件: 両方の実行で終了コード 0（チャート不要は下表の 7 項目，--with-chart は connect・calibrate・shot・close-saving・close-calibrating・cleanup の 6 項目が PASS．結果は .verify/hwtest/run-<日時>/hwtest-result.txt）

チャート不要（--with-chart なし）:

項目	確認内容	合格条件
`connect`	指定した機種に接続でき，機種名・シリアル番号が取れる	`Connect()` が成功する
`preview`	プレビューが流れる	10 fps 以上で，本モニタに表示用 Bitmap がある
`exposure-gain`	露光・ゲインの設定がフレームに効く	基準（平均輝度 30〜220・飽和画素 1% 以下）から露光 1 段下げで比 0.8 以下・上げで比 1.25 以上（飽和した向きは確認しない），ゲインは差 3 以上（片側でよい）．元の値に戻る
`light`	光源が点灯・消灯し，閉じた後に開き直せる	点灯と消灯の平均輝度の差が 100 以上．ポートを開き直した後も点灯が効く
`close-preview`	プレビュー中に閉じる処理を呼んでもすぐ戻る	1000 ms 以内に戻り，例外がなく，閉じた後に届くフレームが 2 以下
`reconnect`	切断した後に再接続できる	2 回目の `Connect()` が成功し，5 フレーム以上届く
`cleanup`	後始末と書き込み禁止	露光・ゲインを戻す → カメラ切断 → 光源のポートを閉じる（消灯しない）が成功し，設定・デバイス状態ファイル・本番の保存先が変わっていない

チャートが必要（--with-chart．connect・cleanup は上表と同じ）:

項目	確認内容	合格条件
`calibrate`	実物の舌診チャートで自動校正が完了し，校正後のフレームを変換した色票が参照値に近い	60 秒以内に校正が完了し，撮影ボタンが有効になる．校正後のフレームを変換した 24 色票と参照値（`tcc_srgb`）の差（8bit・チャネルごとの差の絶対値）が平均 5 以下，白色票（13 番）を除いた最大 10 以下，白色票の最大 40 以下（暫定．PLAN_06「17 次元の変換のノイズ」）
`shot`	単発・連続撮影で保存される	単発 1 枚・連続 3 枚（間隔 1000 ms）で撮影画像・sRGB 変換画像・Info.csv がそろい，撮影ログの行数が撮影枚数と一致する．保存が 90 秒以内に終わって撮影ボタンが再有効化され，撮影時刻の間隔と設定値の差が 100 ms 以下，エラー通知がない
`close-saving`	保存中に閉じようとすると取り消され，保存後は閉じられる	保存中の閉じる処理が取り消され（表示「保存中です．保存完了後に閉じてください」・後始末が走らない），保存の完了後の閉じる処理が 1000 ms 以内・後始末の順序が closing → timer → camera → light・閉じた後に届くフレームが 2 以下
`close-calibrating`	校正中に閉じてもすぐ戻る	再接続して校正中になり（60 秒以内），閉じる処理が 1000 ms 以内に戻り，例外がなく，閉じた後に届くフレームが 2 以下

2026-10-08 に ImagingSource（DFK 33UX178 の 2 個体）で 7/7 合格した．Lumenera の実機テストは行わない（解像度が相対的に低く今後あまり使わない見込みのため）
2026-10-08 に ImagingSource（DFK 33UX178．シリアル 10620446）で --with-chart を 2 回実行し，いずれも 6/6 合格した
変換画像の見た目（白色票や白い台紙の点状のノイズ・白飛び等）は数値で判定しきれないため，下記の手動テストで確認する

結合ロジックテスト (Integration Logic Tests)

NUnit の全件実行に含まれる（ENV_04 の「テスト」．カテゴリで絞る場合は TestCategory=Integration）．現在のケース:

テスト	確認内容
`CameraBaseSaveIntegrationTests`（単発・保存成功）	撮影画像・sRGB 変換画像・Info.csv が保存され，「全ての画像保存完了」が表示され，撮影ボタンが再び有効になる
`CameraBaseSaveIntegrationTests`（単発・撮影画像の保存失敗）	保存失敗が通知され，「全ての画像保存完了」が表示されず，撮影ボタンが再び有効になる
`CameraBaseSaveIntegrationTests`（連続 3 枚・2 枚目の保存失敗）	同上
`CameraBaseCalibrationIntegrationTests`（校正）	校正完了で撮影ボタンが無効から有効になり，校正保存ファイル（SPEC_01）が作られる．チャートが映らないと完了せずボタンは無効のまま．途中で例外が起きても再検出して完了し，旧チャートマスクは解放される
`CameraBaseCalibrationIntegrationTests`（切断）	校正後・校正中の切断で例外にならず，チャートマスクが解放される
`CameraBaseShotIntegrationTests`（撮影ループ）	連続撮影で枚数分のファイルと撮影ログ（間隔どおりの時刻）．枚数 0 で例外にならずボタンが戻る．フレーム取得の失敗で中止・通知され，Info.csv の中止行は理由にカンマ・改行・引用符を含んでも 3 列に収まる
`CameraBaseShotIntegrationTests`（保存キュー・切断）	保存失敗時に撮影した全フレームが解放される．前回のキューに残った画像が解放される．保存中の切断で例外にならず保存が完了する
`Form1UiIntegrationTests`	データ名・連続撮影の枚数・間隔をワーカースレッドから読んでも UI の入力どおりの値が返る（数値でない入力を含む）．ShowMessage・EnableShots が UI に反映され，ワーカーからの呼び出しは UI スレッドを待たずに戻る．閉じ始めた後・ハンドル未生成では何もしない
`CameraBaseCalibrationIntegrationTests`（校正の失敗）	校正中の例外はカメラのコールバックへ伝わらず，失敗の通知はちょうど 1 回．失敗後は検出中の表示に上書きされず失敗の表示が続き，再校正が完了すると「自動校正完了」になる．校正画像の保存に失敗しても校正済みのまま警告を表示する
`CameraBaseShotIntegrationTests`（撮影中の保存）	連続撮影の途中でも保存が進む（4 枚目の取得時点で 2 枚目が保存済み）
`Form1CloseIntegrationTests`	保存中に閉じると取り消されて「保存中」と表示される．保存後は閉じ始め → タイマー → カメラ → 光源の順に後始末される．プレビュー中に閉じてもすぐ戻り例外にならない

合格条件: 全件緑．新しいケースを追加したときは，取り込む前に 3 回連続で緑になることを確認する

ビルドテスト (Build Test)

全フェーズで実施する．

手順

Visual Studio で「ビルド」→「ソリューションのビルド」を実行する
エラーが0件であることを確認する
警告が増加していないことを確認する（リファクタリング前の警告数を記録しておく）

合格条件

ビルドエラーが0件

回帰テスト: 色補正処理（フェーズ2）

リファクタリング前に基準データを作成し，リファクタリング後の出力と比較する．

基準データの作成（リファクタリング前に実施）

実機でキャリブレーションを実行する
保存された以下のファイルを「基準データ」として別フォルダに保管する
- TCC_RGB.csv ← チャート24色票のRGB値
- Conv_RGB-sRGB{CN}.csv ← RGB→sRGB 変換行列
- Conv_RGB-XYZ{CN}.csv ← RGB→XYZ 変換行列
- Conv_sRGB-XYZ{CN}.csv ← sRGB→XYZ 変換行列
- TCC_sRGB{CN}.csv ← チャートのsRGB変換値
- sRGB{CN}_0001.jpg ← 撮影した sRGB 変換画像1枚

比較（リファクタリング後に実施）

同一のキャリブレーション画像・撮影条件で再度実行する
- ※ 実機でのキャリブレーション再現が困難な場合は，TCC_RGB.csv を直接入力として行列計算のみ比較する
基準データと出力ファイルを比較する

合格条件

CSV の数値が全行・全列で一致する（または浮動小数点誤差 ±1e-6 以内）
画像のピクセル値が全ピクセルで一致する

※ 2026-08-29 に自動テスト ChartDetectorTests を追加した（合成した AR マーカー画像を入力し，早期 return・上下逆判定・固定判定・24 枚のマスク生成を検証する）．本節の実機による目視比較を置き換えるものではない．自動テストが担保するのは検出ロジックの分岐と幾何であり，実写のノイズ・照明ムラ・レンズ歪み・実際のマーカー印刷品質に対する検出性能は実機でしか確認できない．OpenCvSharp のネイティブ側更新（例: 4.10 → 4.13）を行ったときは，自動テストが緑でも本節の実機比較を必ず実施すること．

基準データの作成（リファクタリング前に実施）

キャリブレーション時に保存される TCC_ROIs.jpg を基準データとして保管する
- ※ TCC_ROIs.jpg はチャートの ROI マスク位置を緑色で重ねた確認画像

比較（リファクタリング後に実施）

同一条件でキャリブレーションを実行する
出力された TCC_ROIs.jpg を基準データと目視比較する
- ※ 緑色のマスク位置が完全に一致していることを確認する

合格条件

マスクの位置・形状が基準データと目視で一致する

手動テスト（全フェーズ）

実機を使った動作確認．フェーズごとに実施する．

接続・プレビュー・露光/ゲイン・光源・校正・撮影と保存・プレビュー中/保存中/校正中に閉じる，は実機テスト（上記「実機テスト」．ImagingSource の --camera iscam と --camera iscam --with-chart）で自動確認する（2026-10-09 に縮小．PLAN_06 フェーズ 3）．手動テストでは，実機テストで確かめられない次の項目だけを確認する．実機テストを先に回して合格していることが前提．

確認項目

通常起動（エクスプローラーから TIASshot.exe をダブルクリック）で，カメラが自動で選ばれて接続され，プレビューが表示される
- ※ 実機テストは --camera で機種を指定して接続するため，通常起動で機種を自動で選ぶ流れ（Lumenera を優先して探す）は確かめていない
プレビューの映り方が自然である（本モニタ・副ディスプレイのプレビューモニタとも．目視）
- ※ 実機テストが確かめるのは，フレームが届くことと表示用の画像があることまで
撮影ボタン・連続撮影ボタン・光源ボタン・データフォルダを開くボタンをマウスで押して操作でき，表示（メッセージ・ボタンの有効/無効）が自然に変わる
- ※ 実機テストはボタンの処理を直接呼ぶため，実際のクリックの操作感は確かめていない
撮影した sRGB 変換画像の色が目視で妥当である（舌・明るい部分の見た目．17 次元の変換の点状のノイズの出方も見る．PLAN_06「17 次元の変換のノイズ」）
撮影中（連続撮影の撮影の途中）にウィンドウを閉じても固まらず，保存中の場合は「保存中です．保存完了後に閉じてください」と表示される
- ※ 保存中・校正中・プレビュー中に閉じる場合は実機テストで確かめているが，撮影の途中で閉じる場合は未確認
閉じた後も光源が点いたまま残る（仕様）
Lumenera を使う場合のみ: Lumenera のカメラで起動・校正・撮影ができる（Lumenera は実機テストの対象外．PLAN_06「対象機種」）

合格条件

上記の全項目でエラー・クラッシュ・固まりが発生しない