running-apex-tests

running-apex-tests：Salesforce のテスト実行とカバレッジ分析

Apex のテスト実行と失敗分析（テストの実行、カバレッジの確認、失敗の解釈、カバレッジの改善、Salesforce コードの規律あるテスト・修正ループの管理）が必要な場合に、このスキルを使用します。

このスキルが担当するタスク

次の作業には running-apex-tests を使用します。

• sf apex run test のワークフロー
• Apex の単体テストの失敗
• コードカバレッジの分析
• 未カバーの行と不足しているテストシナリオの特定
• Apex コードのための、体系的なテスト・修正ループ

次の場合は、ほかのスキルに委任します。

• 本番環境向け Apex の作成またはリファクタリング → generating-apex スキル
• Agentforce エージェントのテスト → testing-agentforce スキル
• Jest を使用した LWC のテスト → generating-lwc-components

---

まず確認する必要があるコンテキスト

以下について確認するか、推測します。

• 対象の組織エイリアス
• 希望するテスト範囲：単一クラス、特定のメソッド、スイート、またはローカルテスト
• カバレッジのしきい値
• ユーザーが求めているのは診断のみか、テスト・修正ループか
• 関連するテストデータファクトリーがすでに存在するか

---

推奨ワークフロー

1. テスト範囲を確認する

次を特定します。

• 既存のテストクラス
• 対象の本番クラス
• テストデータファクトリー／セットアップヘルパー

2. まず有用な範囲で最小限のテストを実行する

失敗をデバッグするときは対象を絞って開始し、修正が安定してから範囲を広げます。

3. 結果を分析する

次の点に注目します。

• 失敗したメソッド
• 例外の種類とスタックトレース
• 未カバーの行／カバレッジが不十分な領域
• 失敗の原因が、不適切なテストデータ、脆弱なアサーション、または本番ロジックの不具合のいずれか

4. 規律ある修正ループを実行する

問題がコードまたはテストの品質にある場合：

• 必要に応じて、コードの修正を generating-apex スキルに委任します
• テストを追加または改善します
• より広範な回帰テストの前に、対象を絞ったテストを再実行します

5. 意図的にカバレッジを改善する

次をカバーします。

• 正常系
• 異常系／例外経路
• バルク処理（該当する場合は 251 件以上のレコード）
• 関連する場合は、コールアウトまたは非同期処理の経路

---

重要なルール

ルール	理由
デフォルトで SeeAllData=false を使用する	テストを分離し、組織固有のデータへの依存を防ぎます
すべてのテストで意味のある結果をアサートする	アサーションのないテストは何も証明せず、誤った安心感を与えます
251 件以上のレコードでバルク処理をテストする	トリガーは 200 件単位で処理するため、251 件で境界をまたぎます
明瞭さが向上する場合は、ファクトリー／@TestSetup を使用する	データ作成を一元化して一貫性を保てます。テストメソッド間でロールバックされます
非同期処理では Test.startTest() と Test.stopTest() を組み合わせる	非同期処理（キュー可能処理、future）がアサーション前に完了するようにします
不安定な組織依存をテスト内に隠さない	組織の状態に左右される断続的な失敗を防ぎます

---

注意点

問題	解決方法
ローカルではテストが成功するが、CI 組織では失敗する	SeeAllData=true の使用、または組織固有のレコードへの未宣言の依存を確認します
リファクタリング後にカバレッジが予期せず低下する	まずクラス単位のテストを実行し、その後 RunLocalTests に範囲を広げて確認します
コールアウトテストで「未コミットの作業が保留中」というエラーが発生する	Test.startTest() で囲まない限り、同じテストコンテキスト内で DML と HTTP コールアウトを混在させることはできません
テストでモックが反映されない	コールアウトを行うコードの実行前に Test.setMock() が呼び出されていることを確認します
テストメソッドで @TestSetup のデータが見つからない	@TestSetup のデータはテストメソッドごとにコミットされます。再クエリしてください。static 変数に保存しないでください

---

出力形式

完了時は、次の順番で報告します。

1. 実行したテスト
2. 成功／失敗の概要
3. カバレッジ結果
4. 根本原因の調査結果
5. 修正内容または次回実行の推奨事項

推奨形式：

Test run: <scope>
Org: <alias>
Result: <passed / partial / failed>
Coverage: <percent / key classes>
Issues: <highest-signal failures>
Next step: <fix class, add test, rerun scope, or widen regression>

---

スキル間の連携

必要な作業	委任先	理由
本番コードを修正する、またはテストクラスを作成する	generating-apex スキル	コードの生成と修正
大量データやエッジケース用のテストデータを作成する	handling-sf-data	現実的なテストデータセット
更新したテストを組織にデプロイする	deploying-metadata	デプロイのワークフロー
詳細な実行時ログを調査する	debugging-apex-logs	より詳細な失敗分析

---

参考ファイル一覧

ファイル	読むタイミング
references/cli-commands.md	sf apex run test コマンドのすべてのフラグ、出力形式、非同期実行、カバレッジコマンド
references/test-patterns.md	テストクラスのテンプレート — 基本、大量データ（251 件以上）、モックコールアウト、データファクトリのパターン
references/testing-best-practices.md	テストの基本原則 — AAA パターン、命名規則、大量データ、ネガティブテスト、モックの戦略
references/test-fix-loop.md	エージェント型のテスト修正ループの実装と、失敗分析の判断ツリー
references/mocking-patterns.md	HttpCalloutMock、DML モック、StubProvider、セレクターモックのパターン
references/performance-optimization.md	テストの実行時間を短縮する手法 — DML モック、SOQL モック、ループの最適化
assets/basic-test.cls	テンプレート：@TestSetup を使用した標準的なテストクラス。正常系／異常系／大量データ／エッジケースのメソッドを含む
assets/bulk-test.cls	テンプレート：200 レコードのトリガーバッチ境界を超える、251 件以上のレコードを使った大量データテスト
assets/mock-callout-test.cls	テンプレート：HttpCalloutMock を使った HTTP コールアウトのモック
assets/test-data-factory.cls	テンプレート：作成および挿入ヘルパーを備えた再利用可能な TestDataFactory
assets/dml-mock.cls	テンプレート：データベースを使わない単体テスト用の IDML インターフェースと DMLMock の実装
assets/stub-provider-example.cls	テンプレート：StubProvider を使った依存性注入用スタブ
hooks/scripts/parse-test-results.py	ツール実行後のフック — sf apex run test の JSON 出力を解析し、自動修正ループ用に失敗を整形します

---

スコアガイド

スコア	意味
108+	本番環境に適用できる、信頼性の高いテスト
96–107	軽微な不足はあるものの、良好なテストスイート
84–95	許容範囲ですが、カバレッジ／アサーションの強化が必要です
< 84	基準未満のため、信頼して利用する前に修正してください