Fork: 0
hasegawa / TIASShot
Transfer to URL with SHA Find file
Newer
Older
TIASShot / docs / 02_ENV / ENV_04_開発コマンド.md
@rintoHasegawa rintoHasegawa 5 days ago 14 KB [update] チャートが必要な実機テストの完了と 17 次元の変換のノイズの調査結果を計画・検証プロファイル・テスト方針・進捗に反映
Raw Blame History

開発コマンド (Development Commands)

日常の開発で使うビルド・テスト・実行コマンドをまとめる．人間とエージェント（tester・coder，/auto-refactor・/auto-audit）がコマンドを推測せずに済むための唯一の参照先とする．コマンドが増減・変更されたら本ファイルを更新する．

前提 (Prerequisites)

  • ビルドは x64 のみ（TIASshot.sln は Debug|x64 / Release|x64 のみ定義）．OpenCvSharp 等がネイティブ DLL に依存するため AnyCPU は使わない．
  • レガシー形式（packages.config）のため dotnet build / dotnet test は使えない．MSBuild と vstest.console.exe を使う．
  • コマンドは PowerShell で実行する．VS のエディション差（Community / Professional / Enterprise）と Build Tools のみの環境を吸収するため，vswhere で MSBuild・vstest の場所を解決する．

ツールパスの解決 (Locating Build Tools)

$vs = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -products * -property installationPath
$msbuild = Join-Path $vs "MSBuild\Current\Bin\MSBuild.exe"
$vstest  = Join-Path $vs "Common7\IDE\CommonExtensions\Microsoft\TestWindow\vstest.console.exe"

※ -products * は必須．これが無いと vswhere は通常の VS 製品しか列挙せず，VS Build Tools のみの環境では何も返さない（$vs が空になり Join-Path が失敗する）．

以降のコマンドは $msbuild / $vstest を解決済みとして記載する．

NuGet 復元 (Restore)

nuget restore TIASshot.sln

nuget.exe が PATH に無い場合はリポジトリルートの nuget.exe を使う（setup.ps1 が未取得時に自動ダウンロードする）．

ビルド (Build)

# 開発・検証（WHITEBOARD / MEMMONITOR 有効）
& $msbuild TIASshot.sln /t:Build /p:Configuration=Debug /p:Platform=x64

# 配布版（診断機能なし）
& $msbuild TIASshot.sln /t:Build /p:Configuration=Release /p:Platform=x64

# クリーンビルド
& $msbuild TIASshot.sln /t:Rebuild /p:Configuration=Debug /p:Platform=x64

構成ごとのビルドフラグの意味は ENV_06_ビルド構成とビルドフラグ を参照する．

テスト (Test)

自動テストの方針・対象範囲は .claude/rules/testing.md を参照する（本ファイルはコマンドのみ）．

# テストプロジェクトをビルドしてから x64 で実行する
& $msbuild TIASshot.sln /t:Build /p:Configuration=Debug /p:Platform=x64
& $vstest "TIASshot.Tests\bin\x64\Debug\TIASshot.Tests.dll" /Platform:x64
  • ネイティブ DLL を x64 でロードするため /Platform:x64 は必須．
  • Visual Studio 上ではテストエクスプローラーから実行できる（プラットフォームを x64 にすること）．

カテゴリで絞り込んで実行する（開発中の確認用．判定には全件実行を使う）．

# 層②（結合ロジック）のテストだけ実行する
& $vstest "TIASshot.Tests\bin\x64\Debug\TIASshot.Tests.dll" /Platform:x64 "/TestCaseFilter:TestCategory=Integration"
# メモリ量で判定するテストを除いて実行する（環境による不安定さを切り分けるとき）
& $vstest "TIASshot.Tests\bin\x64\Debug\TIASshot.Tests.dll" /Platform:x64 "/TestCaseFilter:TestCategory!=Memory"
  • 層②のテストは SELFTEST フラグに依存するため，Debug 構成でのみコンパイル・実行される．

クリーン環境での検証 (Clean Verification)

ベースライン計測・マージ前検証・「テストが通ることの確認」は，必ず bin / obj を削除してから行う．

bin に前回のビルド成果物が残っていると，過去のビルドでコピーされた DLL が残存してアセンブリ解決が偶然成立し，依存の記述漏れを隠してしまう（Issue #39: テストプロジェクトに OpenCvSharp の推移的依存が無いにもかかわらず，汚れた bin では全緑に見えていた）．同じマシンで作業し続ける限り気づけないため，計測・検証の前に毎回消す．

# bin / obj を削除してからビルド・テストする
Get-ChildItem -Path TIASshot, TIASshot.Tests -Include bin, obj -Directory -Recurse | Remove-Item -Recurse -Force
& $msbuild TIASshot.sln /t:Build /p:Configuration=Debug /p:Platform=x64
& $vstest "TIASshot.Tests\bin\x64\Debug\TIASshot.Tests.dll" /Platform:x64

依存パッケージを追加・変更した PR の検証では，これに加えて packages も退避して nuget restore からやり直し，新しいマシンでの git clone 直後と同じ状態を再現する．

# clone 相当の完全クリーン検証（packages も退避する）
Get-ChildItem -Path TIASshot, TIASshot.Tests -Include bin, obj -Directory -Recurse | Remove-Item -Recurse -Force
Rename-Item packages packages.bak      # 復元に失敗したときのために削除せず退避する
nuget restore TIASshot.sln
& $msbuild TIASshot.sln /t:Build /p:Configuration=Debug /p:Platform=x64
& $vstest "TIASshot.Tests\bin\x64\Debug\TIASshot.Tests.dll" /Platform:x64
  • 合格条件: テストが全件成功し，ビルド警告が増えていないこと．
  • packages の復元にはネットワークと時間がかかるため，通常の開発サイクルでは bin / obj の削除までで運用し，完全クリーン検証は依存変更時とマージ前に行う．
  • 検証が終わったら退避した packages.bak は削除してよい（nuget restore で再取得できるため）．

テストランナー (Test Runner)

上記「テスト」のビルド〜vstest 実行を 1 コマンドにまとめたランナー．tester・refactorer エージェントはこれを使う（エージェントの環境からは MSBuild・vstest を直接呼べないため．実行権限は .claude/agents/ の tools で許可している）．人間が使ってもよい．

# 全件（Debug 出力を削除 → ビルド → テスト．判定にはこれを使う）
python scripts/verify/run_tests.py
# 絞り込み（vstest の /TestCaseFilter の式をそのまま渡す）
python scripts/verify/run_tests.py --filter "TestCategory=Integration"
# 安定性の確認（ビルドは 1 回，テストを 3 回続けて実行する）
python scripts/verify/run_tests.py --filter "TestCategory=Integration" --repeat 3
# 開発中の素早い再確認（Debug 出力を消さない．判定には使わない）
python scripts/verify/run_tests.py --filter "FullyQualifiedName~ConfigTests" --no-clean
  • 出力先: .verify/tests/run-<日時>/（build.log・test-<n>.log・result-<n>.trx・summary.json）．画面には件数と，失敗したテストの名前・メッセージが出る
  • 終了コード: 0=全て合格，1=不合格あり（ビルド失敗・テスト失敗・絞り込みで該当 0 件），2=前提条件を満たさない（Visual Studio / Build Tools 未導入等）
  • 既定で Debug 出力を削除してからビルドする．修正を一時的に戻して赤を確かめるときなどに，更新日時の古いファイルが再コンパイルされず古い結果を見てしまうのを防ぐため
  • セルフテスト（TIASshot.exe --selftest）は実行しない．それは下記「セルフテスト」の run_selftest.py で行う

実行 (Run)

ビルド後，構成に対応した実行ファイルを起動する．実行時参照ファイル（config.xml・カメラ設定 XML・TCC の CSV）が同ディレクトリに配置済みであること（ENV_02_環境構築手順）．

# 開発・検証版
& "TIASshot\bin\x64\Debug\TIASshot.exe"

# 配布版
& "TIASshot\bin\x64\Release\TIASshot.exe"

実機カメラ・光源に接続して動作する UI アプリのため，完全な動作確認には機材が必要．

セルフテスト (Self Test)

実機なしで確認できる範囲（依存アセンブリのロード・プレビュー経路・校正〜保存）を，フォームを表示せずに検査する（Debug|x64 のみ．ENV_06 の SELFTEST）．

# クリーンビルド → 既存テスト → セルフテストをまとめて実行する（結果は .verify/selftest/run-<日時>/）
python scripts/verify/run_selftest.py
# 依存パッケージを変更したとき（packages を退避して nuget restore からやり直す）
python scripts/verify/run_selftest.py --full

# セルフテスト単体（WinExe のため Start-Process -Wait で終了コードを受け取る）
$p = Start-Process "TIASshot\bin\x64\Debug\TIASshot.exe" -ArgumentList "--selftest","--selftest-out","$env:TEMP\tias-selftest.txt" -Wait -PassThru
$p.ExitCode                                     # 0=全項目合格，1=不合格あり，2=セルフテスト自体の異常，3=タイムアウト
Get-Content "$env:TEMP\tias-selftest.txt"      # 各項目の PASS/FAIL と理由（UTF-8 BOM 付き）
  • ランナーがクリーンするのは Debug 出力（TIASshot/ と TIASshot.Tests/ の bin/x64/Debug・obj/x64/Debug）のみ．bin/x64/Release 等ほかの構成の出力は消さない．--no-clean・--skip-tests は開発時の短縮用で，検証の判定には使わない．
  • --selftest-keep を付けると，合格時も作業フォルダ（%TEMP%\TIASshot-selftest\work-*．校正データ・保存画像）を残す（不合格時は常に残る）．
  • verifier（/verify）による自動検証の手順・判定の読み方は .claude/verify-profile.md を参照する．

実機テスト (Hardware Test)

実機のカメラと光源を操作して，接続・プレビュー・露光/ゲイン・光源・閉じる処理・再接続と，--with-chart では実物の舌診チャートでの校正・撮影と保存・保存中/校正中に閉じる処理を検査する（Debug|x64 のみ．ENV_06 の HWTEST．計画は PLAN_06）．実際の Form1 が表示される．

ユーザーの合図があるときだけ実行する（撮影の本番中に機材を操作しないため．Claude は合図なしに実行しない）．

前提:

  • カメラ・光源のドライバが入っている（ENV_02 の「カメラ・光源のドライバ」）
  • 検査する機種のカメラと光源が開発 PC に接続されている
  • カメラの前の穴にカラーチャート（または白板）がはめてある（チャート不要の検査の間は自動校正を止める）
  • TIASshot が起動していない（起動中ならランナーは実行せずに終了コード 2 を返す）
  • 実行中は TIASshot のウィンドウを操作しない（閉じると検査が戻らずタイムアウトしうる）．重いアプリが動いていると校正・保存が遅くなる（保存の待ちの上限は 180 秒）
# ビルド（Debug|x64）→ 実機テスト（結果は .verify/hwtest/run-<日時>/）．対象は ImagingSource だけ
python scripts/verify/run_hwtest.py --camera iscam
# 続けてチャートが必要な検査（カラーチャートをはめたまま．チャート不要の検査は行わないため上の行と両方実行する）
python scripts/verify/run_hwtest.py --camera iscam --with-chart
# 合格時も作業フォルダを残し，--with-chart では証拠の画像（evidence\*.png）も保存する
python scripts/verify/run_hwtest.py --camera iscam --with-chart --keep
# Lumenera（通常は行わない．PLAN_06「対象機種」）
python scripts/verify/run_hwtest.py --camera lucam
# 開発中の素早い再確認（Debug 出力を消さない．判定には使わない）
python scripts/verify/run_hwtest.py --camera iscam --no-clean

# 実機テスト単体（WinExe のため Start-Process -Wait で終了コードを受け取る．実行ファイルのフォルダで実行する）
$p = Start-Process "TIASshot\bin\x64\Debug\TIASshot.exe" -WorkingDirectory "TIASshot\bin\x64\Debug" -ArgumentList "--hwtest","--camera","iscam","--hwtest-out","$env:TEMP\tias-hwtest.txt" -Wait -PassThru
$p.ExitCode                                     # 0=全項目合格，1=不合格あり，2=実機テスト自体の異常，3=タイムアウト
Get-Content "$env:TEMP\tias-hwtest.txt"        # 各項目の PASS/FAIL と測定値（UTF-8 BOM 付き）
  • 書式: python scripts/verify/run_hwtest.py --camera <lucam|iscam> [--with-chart] [--keep] [--no-clean]．--with-chart（チャートが必要な検査．PLAN_06 フェーズ 2）は calibrate・shot・close-saving・close-calibrating を行い（校正は止めない），チャート不要の検査（preview〜reconnect）は行わない（connect・cleanup は両方で行う）．--keep は単体の --hwtest-keep を付けて実行する．
  • 単体の書式: TIASshot.exe --hwtest --camera <lucam|iscam> [--hwtest-out <結果ファイル>] [--with-chart] [--hwtest-keep]．--hwtest-keep を付けると合格時も作業フォルダ（%TEMP%\TIASshot-hwtest\work-*）を残し（不合格・タイムアウト時は常に残る），--with-chart では校正後のフレームとその変換画像（evidence\calibrated-frame-raw.png・evidence\calibrated-frame-srgbNN.png）も保存する．--with-chart の撮影データ・校正データは作業フォルダの data\ に保存される（本番の保存先には書かない）．
  • 所要時間（ビルドを除いた検査の部分）: チャート不要の検査 約 30〜40 秒，--with-chart 約 50〜55 秒．
  • 出力先: .verify/hwtest/run-<日時>/（build.log・hwtest-result.txt・summary.json）．
  • ランナーの終了コード: 0=全項目合格，1=不合格あり（ビルド失敗・検査の不合格・タイムアウト），2=前提条件を満たさない（ツール未導入・TIASshot 起動中・指定機種が見つからない・引数不正）．
  • 実機テスト単体の終了コード（summary.json の hwtest_exit_code）: 0=全項目合格，1=不合格あり，2=実機テスト自体の異常（引数不正・指定機種が見つからない），3=タイムアウト（各項目の上限または全体（チャート不要 600 秒・--with-chart 1200 秒）．ランナーでは 1 になる），null=ランナーが打ち切った（チャート不要 720 秒・--with-chart 1320 秒）．
  • NUnit テスト・セルフテストは実行しない（それぞれ run_tests.py・run_selftest.py）．
  • 検査項目・しきい値・判定の読み方は .claude/verify-profile.md の「実機テスト」節と TEST_01 を参照する．