テスト要件

あらゆる動作変更には、その正当性を証明し、デバッグの容易性を維持するためのテストを含める必要があります。

基本的な期待値

ほとんどの機能開発において、以下の項目を網羅するテストを追加または更新してください。

• パイプラインのビルドにおける正確性（期待される断片／文字列の形式）。
• 動作の解析/検証（Capsネゴシエーションと検証の失敗）。
• ランタイム時の動作（該当する場合、run、プッシュ/プル、およびクリーンアップの処理）。
• 診断の品質（PipelineReport：障害発生時の状況における有用性）。

変更に応じて必要なテストの種類

新しいノードまたはノードグループ

• 決定的なフラグメント生成のためのユニットレベルのチェック。
• 上限値やリンクに関する前提条件の検証/解析範囲。
• ノードが実際のチェーンで正常に機能することを示す、少なくとも1つの統合パスが必要です。

ランタイム/パイプラインのオーケストレーションに関する変更点

• 期待される出力結果に対する正常な動作を検証するテスト。
• タイムアウト、プラグインの欠落、または無効なグラフ条件に対する、エラー発生時のテスト。
• 状態管理が変更された場合の、テスト終了時やライフサイクルにおける安全性の検証。

公開 API の署名変更

• 変更された公開ヘッダーや使用箇所をテストするコンパイル時のカバレッジを追加または更新します。
• 改行を許可しない拡張機能については、既存のコードが引き続きコンパイルできることを確認してください。
• 承認された破壊的な変更については、API の置き換えパスを検証するための移行に重点を置いたテスト/サンプルを含めてください。

Pythonバインディングの変更（python/、pyneat）

• python/tests の下で、pytest のテストカバレッジを追加/更新します。
• 相互運用に関する契約を網羅する（NumPy/PyTorch DLPack のパス、コピーとゼロコピーの動作）。
• インストールされたホイールまたは編集可能なインストールに対して、少なくとも1つのインポート/スモークテストを追加してください。

診断機能または監視機能の変更

• レポートのフィールドの追加/変更に関するテスト。
• ストリーミングスレッドからデータが更新される際の、並行処理における安全な動作。

回帰と決定論のポリシー

• バグの修正には、リグレッションテストを含める必要があります。
• 決定的な命名と安定したパイプライン生成を検証するテストを優先してください。
• 出力が意図的に非決定的な場合、その理由を明記し、アサーションを安定した不変条件に限定してください。

スループットテストにおける CPU コスト

async_yolov8_tput_test は、完了フレーム当たりのプロセス全体のユーザー、システム、合計 CPU 時間をマイクロ秒で報告し、average_busy_cores も報告します。後者は CPU 時間を実経過時間で割った値であり、ボード全体の割合やアクセラレーター使用率ではありません。複数の CPU スレッドが同時に動作する場合は 1 を超えることがあります。

cpu_window_fps は CPU カウンターと同じ区間、つまり最初の計測対象投入の直前から最後の出力の解放までを使用します。ウォームアップ、結果検証、報告、終了処理は除外します。既存の avg_fps 区間とスループットゲートは変わりません。output_extraction_included と output_validation はテストで実施した処理を示します。同じ設定同士で比較してください。未完了または数値検証に失敗した実行は、CPU/フレームの値を付けずに cpu_window_complete=0 を報告します。スループットゲートに失敗しても、それ以外は正常に完了したフレームの測定値は報告されます。

新しいベンチマークでは tests/perf/process_cpu_metrics.h を再利用し、実行ごとにプロセス全体のスナップショットを 2 回取得できます。CPU/フレームの計算だけのために、毎フレーム CPU カウンターをサンプリングしたり監視スレッドを追加したりしないでください。

スキップポリシー

• スキップパスは、通常の制御フローではなく、例外として扱う。
• 厳格なテスト（デフォルト設定）では、必要なランタイム、ツール、またはテスト用データが存在しないためにテストが実行できない場合、テストは失敗しなければなりません。
• 明示的に「long」とラベル付けされたテストのみが、スキップのセマンティクス（return 77）を使用でき、かつ、毎週実行されるテストに適用されます。
• 新しいテストの追加によって、厳密なパスに skip_test(...) が導入されるべきではありません。

実用的なコマンド

プロジェクトのビルドのエントリーポイントを使用してください。

./build.sh --all

ドキュメントに影響を与える変更の場合、以下のコマンドも実行してください。

./build.sh --doc

サポートされているすべてのビルド/テストモードについては、構築する を参照してください。

貢献者向けチェックリスト

プルリクエストを開いたり、マージする前に：

• 追加/更新されたテストは、変更された動作仕様に対応しています。
• 既存の関連テストはすべて正常に完了します。
• ユーザーが直接操作する際の動作に関するドキュメントが更新されました。
• API/アーキテクチャの変更は、アーキテクチャに反映されます。
• 公開 API の変更は、コーディング規約 に記載されている API 互換性ポリシーに準拠します。

必須カバレッジと機能プロファイル

標準 CTest レーンは実行前に正確な選択対象を記録し、新しい JUnit 結果と照合します。選択が空、結果の欠落や重複、スキップ、無効化されたテスト、実行失敗は、必須カバレッジの失敗になります。テスト選択条件、引数、期限を決めるのは集計ツールではなく各レーンです。

long でない登録は、SKIP_RETURN_CODE、スキップ用正規表現、long 専用環境を使って検査を回避できません。必須レーンが、標準の戻り値 77 登録を持つ既存の long テストを選択することはできますが、実際のスキップはやはり失敗です。Fast は long ラベル付きストレステストを保持し、暗黙に選択から除外しません。ソース内のスキップ参照数は参考値であり、実際にスキップしたテスト数ではありません。

cmake/NeatGuardedTests.cmake は、SIMANEAT_GUARDED_HARDWARE_TESTS=ON の場合に、既存のハードウェアスーパーバイザー経由でテストとチュートリアルを登録します。これによってハードウェアの実行許可が得られるわけではありません。保護付き検証は明示的に選択するモードであり、標準 CI はスーパーバイザーソケットなしで直接実行します。保護付きネイティブレーンの実行前に、設定対象のデバイス所有権と実行許可を取得してください。結果バリデーターは登録ポリシーを確認しますが、スーパーバイザーを代替したりハードウェア実行を許可したりしません。

Python レーンは、選択した node ID と明示的に除外した node ID を記録します。必須のセットアップ、呼び出し、終了処理の結果はすべて合格する必要があります。任意のカバレッジは選択前に設定してください。

プロファイル	設定	要件
Python ランタイム	NEAT_CI_PYTHON_PROFILE=runtime（既定）	準備済み ResNet フィクスチャで Graph Phase 3 を有効化し、Torch は明示的に除外します。
Torch 統合	NEAT_CI_PYTHON_PROFILE=torch	レビュー済みの正確な NEAT_CI_TORCH_VERSION を設定し、インストール/インポートを成功させる必要があります。
MIPI カメラ	SIMA_NEAT_TEST_MIPI_CAMERA=1	カメラハードウェア、SIMA_NEAT_TUTORIAL_MODEL_MIPI、SIMA_NEAT_TUTORIAL_MIPI_DECODE を用意します。
週次 HTTP ストリーム	NEAT_CI_STREAM_PROFILE=http（既定）	HTTP MJPEG URL と正の FPS を用意します。両方の HTTP ケースと同期スモークチェックは必須です。
週次 HTTP + RTSP ストリーム	NEAT_CI_STREAM_PROFILE=all	さらに H264、H265、MJPEG の RTSP URL と正の MJPEG FPS を用意します。

ハードウェア不要のカメラ API テストは常にランタイムプロファイルに含まれます。カメラや Torch の除外はカバレッジの欠落であり、合格ではありません。ストリームプロファイルが対象とするのは codec_stream ケースの登録であり、除外された他の RTSP レーンまで検証するものではありません。各ストリームケースにはスモークと反復契約の別々の結果があるため、HTTP ストリームが利用できても、未実行の RTSP ケースを集計 PASS に隠すことはできません。

週次モデルの準備では、SIMA_CI_MNIST_MODEL、SIMA_CI_SSD300_MODEL、SIMA_CI_MNIST_IMAGES、SIMA_CI_MNIST_LABELS それぞれについて、ローカルパスまたは HTTPS の場所と、レビュー済み SHA-256 を設定します。チェックサムには対応する _SHA256 変数を使用します。データセット入力は圧縮された MNIST IDX テストファイルです。準備処理は正確なバイト列を検証し、既存テストのキャッシュ/変数をステージングします。入力の欠落や不一致は準備失敗です。無関係な既存キャッシュを変更することはありません。モデル準備は RTSP の利用可否には依存しません。

選択対象、結果、プロファイル除外レポートをレーン結果と一緒に保持してください。選択したプロファイルの合格は、任意のハードウェア/統合プロファイルがすべて合格したという主張ではありません。

ローカルでの週次準備

CI と同様に、ローカル実行でも tools/ci/prepare_weekly_fixtures.py を使用します。既定では準備に mnist と ssd300 の両方が必要です。MNIST だけを検証する場合は --fixture-group mnist を明示してください。レポートは SSD300 を未検証として示します。この選択は CTest の選択を変更したり、スキップされた必須ケースを合格にしたりしません。完全な週次検証には引き続き両グループが必要です。

ローカルランチャーには --environment-json <file>、GitHub Actions には --github-env <file>、またはその両方を使用します。両出力には同じ環境マッピングが含まれます。ローカルランチャーは選択の記録やハードウェアプロセスの実行許可の前に、JSON マッピングをテストプロセス環境へ統合する必要があります。この JSON はシェルスクリプトでもテスト結果でもなく、作成するだけでは変数をエクスポートしません。

ヘルパーは、選択したモデルと MNIST gzip/IDX ファイルの検証後にのみ SIMA_RUN_MNIST_PREPROC_CHANNELS1=1 をエクスポートします。gzip CRC、IDX 形状、長さ、画像/ラベル数、ラベル範囲を確認し、矛盾する圧縮済み/未圧縮キャッシュエントリーを拒否します。準備試行ごとに新しい出力ディレクトリを使用してください。失敗したステージング済みバイト列は診断用に保持されます。

インストール済みパッケージと非公開プレフィックス統合の違い

次の検証範囲を区別してください。

• 非公開プレフィックス統合は、グローバルなパッケージデータベースを変更せずに、選択したヘッダー、ライブラリ、プラグインを確認します。Debian インストールの検証にはなりません。
• インストール済みパッケージの検証は、実際の DevKit ルートファイルシステム、dpkg 記録、ペイロードのバイト列、シンボリックリンク、ファイル所有権を、選択された検証済みアーカイブと照合します。非公開プレフィックスではこのチェックを満たせません。

ディストリビューション構成は、引き続き scripts/ci/verify_core_dist.sh で検証します。ローカルビルドでは、独立して選択した --expected-manifest、--expected-receipt、--expected-deb-dir 入力も指定します。5 種類のメタデータを含む、生成元の完全なディストリビューションを使用してください。リモート sima-cli インストールは選択されたリソースをステージングしますが、メタデータファイルは保持しません。CI ワークフローはこの実行の完全な neat-core-dist アーティファクトを別途ダウンロードし、実際に CLI でインストールしたパッケージをその独立した入力と比較します。インストール済みマシンから生成元メタデータを再生成しないでください。

必須パッケージプロファイルを明示的に選択します。

プロファイル	必須の役割
core	Core ランタイム/開発、Kernels 開発、Runner、Scheduler、ランタイム互換パッケージ
core-codecs	core と Codecs ランタイム/開発の組
core-codecs-llima	core-codecs と LLiMa ランタイム/CLI の組

使用された任意のバックエンドプロバイダーは、選択済み生成元記録に基づき必須のままです。欠けているアーカイブからプロファイルを推測しません。LLiMa と廃止済みメモリ実装は、Core のみのテストに無条件に必要な依存関係ではありません。

DevKit では、既存インストーラーを使用する前に、tools/ci/verify_core_dist.py の --capture-platform-baseline <file> で状態を取得します。インストール後、--package-profile <profile>、--verify-installed、--platform-baseline <file>、--write-package-inventory <file> を指定してディストリビューション検証ツールを実行します。ベースラインは追跡対象のネイティブパッケージの存在/不在を記録し、その状態、無関係なネイティブパッケージのバージョン、OTA コマンドの利用可否を維持します。OTA コマンドがある場合、その正規パス、所有権、バイト列は変更してはいけません。過去のパッケージ名や OTA コマンドはすべてのイメージに存在する必要はありませんが、Palette は必須です。検証済みディストリビューションに明示的に含まれるプロバイダーは更新可能で、その場合は選択されたアーカイブと照合します。

インベントリーの絶対パスを SIMA_TEST_PACKAGE_INVENTORY、インストール前ベースラインのパスを SIMA_TEST_PLATFORM_BASELINE として、既存の devkit-package-inventory CTest レーンに渡します。インストール後にベースラインを取得し直さないでください。選択済みインベントリーは期待するアーカイブデータを含むもので、インストール PASS ではありません。ネイティブテストは、実際のパッケージのバージョン/アーキテクチャ、読み込まれた Core/ライブラリのパスと所有権、未選択ネイティブパッケージの存在/不在が不変であること、廃止済みパッケージの不在、OTA の利用可否と識別情報を独立に確認します。インストール済みヘッダーのサンプルは引き続き別途コンパイルしてください。パッケージの存在は、コンシューマーがコンパイルできることやバックエンドが正しく実行されたことの証明にはなりません。

ネイティブビルドツールの前提条件

Ubuntu では、.github/workflows/vulcan-ci.yml のビルドツール用 pytest 選択対象を実行する前に、build-essential、file、nlohmann-json3-dev、python3-venv をインストールします。プラットフォームベースラインのプローブは、実際の共有 C++ 契約を -Werror でコンパイルします。コンパイラー/ヘッダーの欠落はテスト準備失敗であり、スキップではありません。失敗時にはコンパイラーの stdout/stderr が表示され、実行前に file がネイティブ実行ファイルを確認します。