test-research-code

研究コードのテスト

研究用のコード成果物を、成果物評価委員会（ACM AE、USENIX/OSDI/SOSP、SIGMOD ARI、ETAPS、NeurIPS コードリリース）が期待する状態にします。つまり、実行できること、許容誤差の範囲で再現できる程度に決定性があること、環境が記録されていること、そして第三者が README に従って論文の主な結果を再現できることです。これは、PDF 向けの preflight-check に相当するコード側の取り組みです。

これは汎用的なソフトウェアの TDD ではありません。目標は、網羅的な単体テストではなく、信頼できるエンドツーエンドの「実行でき、おおむね再現できる」経路を 1 つ用意することです。実際のパイプラインを小さな入力で実行する、的を絞ったスモークテストのほうが、モックを使った単体テスト 100 件より価値があります。

使用する場面

• コードが**「自分のマシンでは動く」**状態で、第三者も実行できるようにする必要がある場合 — 環境のバージョン固定がなく、シードもなく、明確なエントリーポイントや健全性テストもありません。
• 著者が、パッケージ化や引き継ぎの前にスモークテスト／健全性テストを追加する、シードを固定して決定性を確保する、または環境を記録／固定するよう依頼した場合。
• 成果物評価の締め切りが迫っているのに、コードがまだテスト可能な状態でない場合 — まずこのエンジニアリング作業を行い、その後、下記の関連スキルに引き継ぎます。

対象範囲（重複を避けるために）。 このスキルは、テスト、シード、環境の記録を扱うエンジニアリングの段階です。以下は対象外です。

• パッケージ化、バッジの分類、アーカイブ DOI、匿名化 → prepare-artifacts。
• 生成された数値が論文の表と実際に一致するかどうか → verify-results。
• 一般的なコードの整理／リファクタリング → refactor-research-code。 依頼が「成果物トラック向けにコードを整えてほしい」というものであれば、まずここで実行可能性の不足を解消してから引き継ぎます。作業を重複して行わないでください。

入力

• 研究コードのディレクトリへのパス（リポジトリ、または学習／評価スクリプトなどを含むサブフォルダー）。
• 任意で、レビューがダブルブラインドかどうか（記録した環境や追加したテストから著者の身元が漏れないようにするため）。
• 任意で、位置づけを確認するための .paper-memory/profile.yml（system／dataset の貢献では再利用可能で十分にテストされた成果物をより重視し、empirical の貢献では決定的な再実行をより重視します）。

プロセス

1. まずメモリを読みます。 .paper-memory/lessons.md（および存在する場合は profile.yml）を読み、著者がすでに修正した点を再度指摘しないようにし、著者のrecurring な習慣を先に取り上げます。詳細は paper-memory-convention.md を参照してください。

2. 対象範囲を確認します。 レビューがダブルブラインドかどうか、明示されていない場合は尋ねます。追加するもの（記録した環境、テスト用フィクスチャ、ノートブックなど）から身元が漏れないようにするためです。著者が特定の成果物トラックを目指している場合は、バッジの内容と、別途設定される成果物の締め切りは会場の最新の Call for Artifacts を確認して再検証する必要があることに留意してください。これらは会場や年によって変わるためです。ただし、その確認は prepare-artifacts の担当です。ここでは、コードをテスト可能にすることだけを行い、バッジの分類を再説明しないでください。背景情報（バッジの系統、2020 年以降の Reproduced／Replicated の入れ替わり）は、現在の規則を断言するためではなく参考情報として、references/artifact-standards.md に記載されています。

3. リポジトリを監査します（決定的に）。 同梱スクリプトを実行してください。手作業で grep してはいけません。

   python3 scripts/repro_check.py <code-dir>          # text report
   python3 scripts/repro_check.py <code-dir> --json   # machine-readable
   

   このスクリプトは、必須項目 6 つ — README、ENV（依存関係、バージョン固定の有無）、SEED、ENTRYPOINT、DATA、RESULTS_CMD — を OK／WARN／MISSING で報告し、テストが存在するかどうかも示します。これは、以降の作業の根拠となる外部から測定可能な指標です。「再現できそうに見える」という独自の判断で代用してはいけません。終了コード：0 は問題なし、1 は必須項目不足、2 は使用方法の誤りです。

4. 次の順序で不足を解消します（それぞれ、スクリプトの検出結果とreferences/repro-essentials.mdに対応します）。

   • ENV — 依存関係マニフェストを作成または修正し、正確なバージョンを固定します。pip freeze > requirements.txt、environment.yml、またはベースイメージのバージョンを固定したDockerfileを用意します。依存関係のバージョンが固定されていないことは、評価担当者が再構築できない最もよくある原因です。結果を生成したときのOS、CUDA、ハードウェアを記録します。
   • SEED — 使用するすべての乱数生成器（random、numpy、フレームワークではtorch.manual_seedとtorch.use_deterministic_algorithms(True)、PYTHONHASHSEED）のシードを設定し、記録します。GPUのアトミック操作やデータローダーのワーカーなど、残る非決定性については隠さず、正直に記載します。
   • ENTRYPOINT — パイプラインを最初から最後まで実行する、わかりやすいコマンドを1つ用意します（make reproduce、run.sh、python -m pkg、__main__ガードなど）。
   • SMOKE/SANITY TEST — 実際のパイプラインを小さな入力または合成入力で実行し、完了して妥当な形状や値を出力することを確認する、最小限のテストを追加します。テンプレートはreferences/smoke-tests.mdを参照してください。ここでは、広範な単体テストより、エンドツーエンドのスモークテスト1つのほうが有効です。
   • DATA — 入力データの入手方法を正確に示します（ダウンロードスクリプト、または「外部データなし」）。可能であれば、入手元とチェックサムも記載します。
   • RESULTS_CMD — READMEに、報告した結果と、それぞれを生成する正確なコマンドを記した短い表を掲載します（ML Code Completenessの項目）。想定実行時間と、数値はビット単位で完全一致するのではなく、許容誤差の範囲内で一致すればよいことも記載します。

5. repro_check.pyを再実行し、すべての必須項目がOK（または意図的にWARN）になるまで確認します。際限なく磨き続けるのではなく、すべての必須項目がMISSINGではないこと、または修正を最大約3回までとするなど、明確な終了条件を設定します。

6. ホスティングと匿名化（助言のみ。実作業はしません）。

   • **アーカイブホスティング（Zenodo/SWHID、バージョンDOIとコンセプトDOI、USENIXのGitHub単独公開禁止ルール）**はprepare-artifactsの担当です。ここでは対応しないでください。コードがテスト可能になったら、「次のステップ：prepare-artifactsでパッケージ化して登録」と明記し、そこで終了します。
   • ダブルブラインド：リポジトリがブラインド査読の対象であれば、追加するもの（環境ファイル、フィクスチャ、ノートブックなど）によって身元が再び特定されないようにします。匿名化そのものはanonymize-paper / prepare-artifactsに引き継ぎます。ここで中途半端に対応せず、その必要性を記載してください。

7. レポートとチェックリストをpaper-workspace/submission/artifact-repro-checklist.mdに作成し、paper-workspace/INDEX.mdに追記します。まず完了事項を示し、続いて優先順位を付けた不足項目を列挙します。それぞれ、repro_check.pyの検出結果と具体的な修正内容を関連付けます。

出力

レビュー可能なpaper-workspace/submission/artifact-repro-checklist.mdを作成します。内容には、監査表（6つの必須項目をOK/WARN/MISSINGで示す）、追加または推奨したスモークテスト、実行した環境情報の取得コマンド、固定したシード、データと再現方法の説明を含めます。また、著者のリポジトリに実際に追加したファイル（tests/test_smoke.py、バージョン固定済みのrequirements.txt、Makefile / run.shなど）も記載します。不足項目はすべて、該当するスクリプトの検出結果を明記します。チェックリストの最後には、prepare-artifacts（パッケージ化／バッジ／DOI）とverify-results（数値の一致確認）への引き継ぎを1行で記載し、両者の作業を重複して行わないでください。

分野に合わせた調整

この手順は、CS分野のアーティファクトトラック（ACM/USENIX/SIGMOD/ML）を対象としています。他分野では、環境情報の取得方法を各分野のロックファイル（Rならrenv.lock、JuliaならManifest.toml、バイオインフォマティクスならconda）に置き換え、シードやテストの作法も各フレームワークに合わせてください。バッジと投稿先の対応付けはprepare-artifactsの担当であり、このスキルの担当ではありません。「テスト可能、決定的、環境情報を記録済み」という要件は、どの分野にも共通です。

ガードレール

• 破壊的な操作は決して実行せず、作者の許可なく、動作を「証明」するために信頼できない実験コードを実行しないでください。 repro_check.py は設計上、静的かつ読み取り専用です（実行もネットワーク接続もしません）。成果物をエンドツーエンドで実行するかどうかは作者の判断であり、サンドボックスや GPU が必要になる場合があります。
• チェックリストに合格することは必要条件ですが、十分条件ではありません。 成果物が「バッジを獲得できる」または「再現可能である」と作者に伝えないでください。それらは、実際の CFA に照らした委員会の判断です。また、どこであっても「再現」は、ビット単位で完全一致することではなく、論文の主張を変えない範囲の許容誤差内でという意味です。必要条件ではあるが十分条件ではない、という表現を使ってください。
• 結果やコマンドを捏造しないでください。 再現コマンドは、リポジトリに実際に存在するものにしてください。実行できない場合は、その旨を伝えてください。
• 匿名化に配慮してください：ダブルブラインド査読では、リポジトリ、コミット履歴、ノートブックのメタデータを通じて作者の身元を決して明かさないでください。
• チェック、ひな形の作成、説明は行いますが、成果物を提出したり、作者に代わって DOI を発行したりはしません。
• references/ 内のファイルは1階層の深さにとどめ、このファイルは500行未満にしてください。

メモリー

共有の .paper-memory/ 規約を使用します（完全な仕様は paper-memory-convention.md を参照）。

• 開始時： lessons.md を読んで、すでに修正済みの問題を避け、繰り返し見られる習慣から確認を始めてください（例：「依存関係のバージョンを固定せずにリリースする傾向があるため、まずそこを確認します」）。貢献の種類を確認するために profile.yml を読み、適切なバッジの目標を設定してください。
• 終了時： 繰り返し見られた問題ごとに、標準形式で日付入りの記録を1件追記してください。reflect-and-improve の reflect_log.py を使用します：

  python3 ../reflect-and-improve/scripts/reflect_log.py append \
      --memory .paper-memory --skill test-research-code --scope recurring \
      --issue "experiment scripts ship without seed setting" \
      --rec "set random/numpy/framework seeds + PYTHONHASHSEED every artifact"
  

• 必要に応じて .paper-memory/ を作成し、.gitignore への追加を提案してください。ローカル専用とし、アップロードしないでください。