Amazon CodeCatalyst は新規のお客様には提供されなくなりました。既存のお客様は、通常どおりサービスを引き続き使用できます。詳細については、「[CodeCatalyst から移行する方法](migration.md)」を参照してください。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# ワークフローを使用したテスト
CodeCatalyst では、ビルドやテストなど、さまざまなワークフローアクションの一環としてテストを実行できます。これらのすべてのワークフローアクションでは、品質レポートを生成できます。*テストアクション*は、テスト、コードカバレッジ、ソフトウェア構成分析、静的分析の各レポートを生成するワークフローアクションです。これらのレポートは CodeCatalyst コンソールに表示されます。
**Topics**
+ [品質レポートのタイプ](#test-reporting)
+ [テストアクションの追加](test-add-action.md)
+ [テストアクションの結果の表示](test-view-results.md)
+ [アクション内で失敗したテストのスキップ](test.error-handling.md)
+ [universal-test-runner との統合](test.universal-test-runner.md)
+ [アクションにおける品質レポートの設定](test-config-action.md)
+ [テストのベストプラクティス](test-best-practices.md)
+ [サポートされている SARIF プロパティ](test.sarif.md)
## 品質レポートのタイプ
Amazon CodeCatalyst テストアクションでは、次のタイプの品質レポートがサポートされています。これらのレポートを YAML 形式で設定する方法の例については、「[品質レポートの YAML 例](test-config-action.md#test.success-criteria-example)」を参照してください。
**Topics**
+ [テストレポート](#test-reports)
+ [コードカバレッジレポート](#test-code-coverage-reports)
+ [ソフトウェア構成分析レポート](#test-sca-reports)
+ [静的分析レポート](#test-static-analysis-reports)
### テストレポート
CodeCatalyst では、ユニットテスト、統合テスト、システムテストを設定し、ビルド中に実行できます。その後、CodeCatalyst でそのテストの結果を含むレポートを作成できます。
テストレポートは、テストに関する問題のトラブルシューティングに役立ちます。複数のビルドで生成されたテストレポートが多数ある場合、テストレポートを使用して失敗率を確認し、ビルドを最適化できます。
以下のテストレポートファイル形式を使用できます。
+ Cucumber JSON (.json)
+ JUnit XML (.xml)
+ NUnit XML (.xml)
+ NUnit3 XML (.xml)
+ TestNG XML (.xml)
+ Visual Studio TRX (.trx、.xml)
### コードカバレッジレポート
CodeCatalyst で、テストのコードカバレッジレポートを生成できます。CodeCatalyst では、次のコードカバレッジメトリクスが提供されます。
[ラインカバレッジ]
テストでカバーされるステートメントの数を測定します。ステートメントは、コメントを含まない単一の命令です。
`line coverage = (total lines covered)/(total number of lines)`
[ブランチカバレッジ]
コントロール構造のすべてのブランチのうち、テストでカバーされるブランチの数を測定します (`if` または `case` ステートメントなど)。
`branch coverage = (total branches covered)/(total number of branches)`
以下のコードカバレッジレポートファイル形式がサポートされています。
+ JaCoCo XML (.xml)
+ SimpleCov JSON ([simplecov](https://github.com/simplecov-ruby/simplecov) によって生成された .json であり、[simplecov-json](https://github.com/vicentllongo/simplecov-json) ではありません)
+ Clover XML (バージョン 3、.xml)
+ Cobertura XML (.xml)
+ LCOV (.info)
### ソフトウェア構成分析レポート
CodeCatalyst では、ソフトウェア構成分析 (SCA) ツールを使用してアプリケーションのコンポーネントを分析し、既知のセキュリティ脆弱性を確認できます。重要度や修正方法がさまざまに異なる脆弱性を詳細に説明する SARIF レポートを検出して解析できます。有効な重要度の値は、重要度が高い順に、`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL` です。
以下の SCA レポートファイル形式がサポートされています。
+ SARIF (.sarif、.json)
### 静的分析レポート
静的分析 (SA) レポートを使用して、ソースレベルのコード欠陥を特定できます。CodeCatalyst では、SA レポートを生成して、デプロイする前にコードの問題を解決できます。これらの問題には、バグ、セキュリティの脆弱性、品質の問題、およびその他の脆弱性が含まれます。有効な重要度の値は、重要度が高い順に、`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL` です。
CodeCatalyst では、次の SA メトリクスが提供されます。
バグ
ソースコードで検出される可能性のあるバグの数を識別します。これらのバグには、メモリの安全性に関する問題が含まれることがあります。バグの例を次に示します。
```
// The while loop will inadvertently index into array x out-of-bounds
int x[64];
while (int n = 0; n <= 64; n++) {
x[n] = 0;
}
```
セキュリティの脆弱性
ソースコードで検出される可能性のあるセキュリティ脆弱性を特定します。これらのセキュリティ脆弱性には、シークレットトークンをプレーンテキストで保存するなどの問題が含まれることがあります。
品質に関する問題
ソースコードで検出される可能性のある品質問題を特定します。これらの品質問題には、スタイルの規則に関する問題が含まれることがあります。品質問題の例を次に示します。
```
// The function name doesn't adhere to the style convention of camelCase
int SUBTRACT(int x, int y) {
return x-y
}
```
その他の脆弱性
ソースコードで検出される可能性のあるその他の脆弱性を特定します。
CodeCatalyst では、以下の SA レポートファイル形式がサポートされています。
+ PyLint (.py)
+ ESLint (.js、.jsx、.ts、.tsx)
+ SARIF (.sarif、.json)
# テストアクションの追加
CodeCatalyst ワークフローにテストアクションを追加するには、次の手順に従います。
------
#### [ Visual ]
**ビジュアルエディタを使用してテストアクションを追加するには**
1. [https://codecatalyst.aws/](https://codecatalyst.aws/) で CodeCatalyst コンソールを開きます。
1. ナビゲーションペインで **[CI/CD]**、**[ワークフロー]** の順に選択します。
1. ワークフローの名前を選択します。ワークフローが定義されているソースリポジトリまたはブランチ名でフィルタリングすることも、ワークフロー名またはステータスでフィルタリングすることもできます。
1. **[編集]** を選択します。
1. **[ビジュアル]** を選択します。
1. **[アクション]** を選択します。
1. **[アクション]** で **[テスト]** を選択します。
1. **[入力]** タブと **[設定]** タブで、必要に応じてフィールドに入力します。各フィールドの説明については、「[ビルドおよびテストアクション YAML](build-action-ref.md)」を参照してください。このリファレンスでは、YAML エディタとビジュアルエディタの両方に表示される各フィールド (および対応する YAML プロパティ値) に関する詳細情報を提供しています。
1. (オプション) **[検証]** を選択して、ワークフローの YAML コードをコミットする前に検証します。
1. **[コミット]** を選択し、コミットメッセージを入力し、再度 **[コミット]** を選択します。
------
#### [ YAML ]
**YAML エディタを使用してビルドアクションを追加するには**
1. [https://codecatalyst.aws/](https://codecatalyst.aws/) で CodeCatalyst コンソールを開きます。
1. ナビゲーションペインで **[CI/CD]**、**[ワークフロー]** の順に選択します。
1. ワークフローの名前を選択します。ワークフローが定義されているソースリポジトリまたはブランチ名でフィルタリングすることも、ワークフロー名またはステータスでフィルタリングすることもできます。
1. **[編集]** を選択します。
1. **[YAML]** を選択します。
1. **[アクション]** を選択します。
1. **[アクション]** で **[テスト]** を選択します。
1. 必要に応じて、YAML コードのプロパティを変更します。使用可能な各プロパティの説明は、「[ビルドおよびテストアクション YAML](build-action-ref.md)」に記載されています。
1. (オプション) **[検証]** を選択して、コミットする前にワークフローの YAML コードを検証します。
1. **[コミット]** を選択し、コミットメッセージを入力し、再度 **[コミット]** を選択します。
------
## テストアクションの定義
テストアクションは、ワークフロー定義ファイル内の一連の YAML プロパティとして定義されます。これらのプロパティの詳細については、「[ワークフロー YAML 定義](workflow-reference.md)」の「[ビルドおよびテストアクション YAML](build-action-ref.md)」を参照してください。
# テストアクションの結果の表示
生成されたログ、レポート、変数など、テストアクションの結果を表示するには、以下の手順に従います。
**テストアクションの結果を表示するには**
1. ナビゲーションペインで **[CI/CD]**、**[ワークフロー]** の順に選択します。
1. ワークフローの名前を選択します。ワークフローが定義されているソースリポジトリまたはブランチ名でフィルタリングすることも、ワークフロー名またはステータスでフィルタリングすることもできます。
1. ワークフロー図で、テストアクションの名前を選択します。例えば、**[テスト]** です。
1. アクションによって生成されたログを表示するには、**[ログ]** を選択します。さまざまなアクションフェーズのログが表示されます。必要に応じてログを展開または折りたたむことができます。
1. テストアクションによって生成されたテストレポートを表示するには、**[レポート]** を選択するか、ナビゲーションペインで **[レポート]** を選択します。詳細については、「[品質レポートのタイプ](test-workflow-actions.md#test-reporting)」を参照してください。
1. テストアクションに使用する設定を表示するには、**[設定]** タブを選択します。詳細については、「[テストアクションの追加](test-add-action.md)」を参照してください。
1. テストアクションで使用される変数を表示するには、**[変数]** を選択します。詳細については、「[ワークフローでの変数の使用](workflows-working-with-variables.md)」を参照してください。
# アクション内で失敗したテストのスキップ
アクションに複数のテストコマンドがある場合、前のコマンドが失敗しても後続のテストコマンドを実行可能にする必要が生じることがあります。例えば、以下のコマンドでは、`test1` が失敗した場合でも、常に `test2` を実行可能にすることが望ましいです。
```
Steps:
- Run: npm install
- Run: npm run test1
- Run: npm run test2
```
通常、あるステップがエラーを返すと、Amazon CodeCatalyst はワークフローアクションを停止し、失敗としてマークします。エラー出力を `null` にリダイレクトすることで、アクションステップの実行を継続できます。これは、コマンドに `2>/dev/null` を追加することで実行できます。前の例にこの変更を加えると、次のようになります。
```
Steps:
- Run: npm install
- Run: npm run test1 2>/dev/null
- Run: npm run test2
```
2 番目のコードスニペットでは、`npm install` コマンドのステータスが適用され、`npm run test1` コマンドで返されるエラーは無視されます。その結果、`npm run test2` コマンドが実行されます。これにより、エラーが発生したかどうかにかかわらず、両方のレポートを一度に表示できるようになります。
# universal-test-runner との統合
テストアクションは、オープンソースのコマンドラインツール `universal-test-runner` と統合されます。`universal-test-runner` は[テスト実行プロトコル](https://github.com/aws/universal-test-runner/blob/main/protocol/README.md)を使用して、特定のフレームワーク内の任意の言語のテストを実行します。`universal-test-runner` は、次のフレームワークをサポートしています。
+ [Gradle](https://gradle.org/)
+ [Jest](https://jestjs.io/)
+ [Maven](https://maven.apache.org/)
+ [pytest](https://pytest.org)
+ [.NET](https://learn.microsoft.com/en-us/dotnet/core/tools/)
`universal-test-runner` は、テストアクション用にキュレートされたイメージにのみインストールされます。カスタムの Docker Hub または Amazon ECR を使用するようにテストアクションを設定する場合、`universal-test-runner` を手動でインストールして高度なテスト機能を有効にする必要があります。これを行うには、Node.js (14 以降) をイメージにインストールし、シェルコマンド `- Run: npm install -g @aws/universal-test-runner` を使用して `npm` で `universal-test-runner` をインストールします。シェルコマンドを使用してコンテナに Node.js をインストールする方法の詳細については、[Node Version Manager のインストールと更新](https://github.com/nvm-sh/nvm#install--update-script)に関する記事を参照してください。
`universal-test-runner` の詳細については、「[What is universal-test-runner?](https://github.com/aws/universal-test-runner#-what-is-universal-test-runner)」を参照してください。
------
#### [ Visual ]
**ビジュアルエディタで universal-test-runner を使用するには**
1. [https://codecatalyst.aws/](https://codecatalyst.aws/) で CodeCatalyst コンソールを開きます。
1. ナビゲーションペインで **[CI/CD]**、**[ワークフロー]** の順に選択します。
1. ワークフローの名前を選択します。
1. **[編集]** を選択します。
1. **[ビジュアル]** を選択します。
1. **[アクション]** を選択します。
1. **[アクション]** で **[テスト]** を選択します。
1. **[設定]** タブで、サポートされているフレームワークを選択してサンプルコードを更新し、**[シェルコマンド]** フィールドを完成させます。例えば、サポートされているフレームワークを使用するには、次のような `Run` コマンドを使用します。
```
- Run: run-tests
```
必要なフレームワークがサポートされていない場合は、カスタムアダプターまたはカスタムランナーを作成して提供することを検討してください。**[シェルコマンド]** フィールドの説明については、「[Steps](build-action-ref.md#build.configuration.steps)」を参照してください。
1. (オプション) **[検証]** を選択して、ワークフローの YAML コードをコミットする前に検証します。
1. **[コミット]** を選択し、コミットメッセージを入力し、再度 **[コミット]** を選択します。
------
#### [ YAML ]
**YAML エディタで universal-test-runner を使用するには**
1. [https://codecatalyst.aws/](https://codecatalyst.aws/) で CodeCatalyst コンソールを開きます。
1. ナビゲーションペインで **[CI/CD]**、**[ワークフロー]** の順に選択します。
1. ワークフローの名前を選択します。
1. **[編集]** を選択します。
1. **[YAML]** を選択します。
1. **[アクション]** を選択します。
1. **[アクション]** で **[テスト]** を選択します。
1. 必要に応じて YAML コードを変更します。例えば、サポートされているフレームワークを使用するには、次のような `Run` コマンドを使用します。
```
Configuration:
Steps:
- Run: run-tests
```
必要なフレームワークがサポートされていない場合は、カスタムアダプターまたはカスタムランナーを作成して提供することを検討してください。**Steps** プロパティの説明については、「[Steps](build-action-ref.md#build.configuration.steps)」を参照してください。
1. (オプション) **[検証]** を選択して、ワークフローの YAML コードをコミットする前に検証します。
1. **[コミット]** を選択し、コミットメッセージを入力し、再度 **[コミット]** を選択します。
------
# アクションにおける品質レポートの設定
このセクションでは、 アクションで品質レポートを設定する方法について説明します。
**Topics**
+ [自動検出によるレポートと手動設定によるレポート](#test.auto-discovery)
+ [レポートの成功基準の設定](#test.success-criteria)
+ [品質レポートの YAML 例](#test.success-criteria-example)
## 自動検出によるレポートと手動設定によるレポート
自動検出を有効にすると、CodeCatalyst では、アクションに渡されたすべての入力と、アクション自体によって生成されたすべてのファイルが検索され、テストレポート、コードカバレッジレポート、ソフトウェア構成分析 (SCA) レポート、静的分析 (SA) レポートが検出されます。これらのレポートを CodeCatalyst で個別に表示して操作できます。
どのレポートを生成するかを手動で設定することもできます。生成するレポートのタイプとファイル形式を指定できます。詳細については、「[品質レポートのタイプ](test-workflow-actions.md#test-reporting)」を参照してください。
## レポートの成功基準の設定
テストレポート、コードカバレッジレポート、ソフトウェア構成分析 (SCA) レポート、または静的分析 (SA) レポートの成功基準を決定する値を設定できます。
成功基準は、レポートが合格か不合格かを決定するしきい値です。CodeCatalyst では、テスト、コードカバレッジ、SCA、または SA のいずれかのレポートが最初に生成され、その後、生成されたレポートに成功基準が適用されます。次に、成功基準が満たされたか、およびどの程度満たされたかが示されます。指定した成功基準がレポートで満たされていない場合、その成功基準が指定された CodeCatalyst アクションは失敗します。
例えば、SCA レポートの成功基準を設定する場合、有効な脆弱性値は、重要度が高い順に、`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL` です。重要度が `HIGH` である脆弱性をスキャンするように基準を設定すると、重要度が `HIGH` である脆弱性が 1 つ以上存在する場合、または重要度が `HIGH` である脆弱性は存在しないものの、より重要度の高い脆弱性が 1 つ以上存在する場合 (例えば、重要度が `CRITICAL` である脆弱性が 1 つ存在するなど)、レポートが失敗します。
成功基準を指定しない場合は、次のようになります。
+ 未加工のレポートに基づいて生成された CodeCatalyst レポートには、成功基準は表示されません。
+ 関連するワークフローアクションが合格または不合格かを決定するために成功基準が使用されることはありません。
------
#### [ Visual ]
**成功基準を設定するには**
1. ナビゲーションペインで **[CI/CD]**、**[ワークフロー]** の順に選択します。
1. レポートを生成するアクションを含むワークフローを選択します。このレポートに成功基準を適用します。ワークフローが定義されているソースリポジトリまたはブランチ名でフィルタリングすることも、ワークフロー名またはステータスでフィルタリングすることもできます。
1. **[編集]** を選択します。
1. **[ビジュアル]** を選択します。
1. ワークフロー図で、CodeCatalyst レポートを生成するように設定したアクションを選択します。
1. **[出力]** タブを選択します。
1. **[オートディスカバリーレポート]** または **[レポートを手動で設定]**で、**[成功基準]** を選択します。
成功基準が表示されます。前の選択に基づいて、以下のオプションの一部またはすべてが表示されます。
**[パスレート]**
関連する CodeCatalyst レポートが合格としてマークされるために、テストレポート内のテストに求められる合格の割合を指定します。有効な値には 10 進数が含まれます。例: `50`、`60.5`。パスレートの基準は、テストレポートにのみ適用されます。テストレポートの詳細については、「[テストレポート](test-workflow-actions.md#test-reports)」を参照してください。
**[ラインカバレッジ]**
関連する CodeCatalyst レポートが合格としてマークされるために、コードカバレッジレポート内でカバーする必要がある行の割合を指定します。有効な値には 10 進数が含まれます。例: `50`、`60.5`。ラインカバレッジ基準は、コードカバレッジレポートにのみ適用されます。コードカバレッジレポートの詳細については、「[コードカバレッジレポート](test-workflow-actions.md#test-code-coverage-reports)」を参照してください。
**[ブランチカバレッジ]**
関連する CodeCatalyst レポートが合格としてマークされるために、コードカバレッジレポート内のブランチに求められるカバレッジの割合を指定します。有効な値には 10 進数が含まれます。例: `50`、`60.5`。ブランチカバレッジ基準は、コードカバレッジレポートにのみ適用されます。コードカバレッジレポートの詳細については、「[コードカバレッジレポート](test-workflow-actions.md#test-code-coverage-reports)」を参照してください。
**[脆弱性 (SCA)]**
関連する CodeCatalyst レポートが合格としてマークされるように、SCA レポート内で許容される脆弱性の最大数と重要度を指定します。脆弱性を指定するには、以下を指定する必要があります。
+ カウントに含める脆弱性の最小重要度。有効な値は、重要度が高い順に `CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL` です。
例えば、`HIGH` を選択すると、`HIGH` と `CRITICAL` の脆弱性が集計されます。
+ 指定された重要度の脆弱性の最大許容数。この数を超えると、CodeCatalyst レポートは不合格としてマークされます。有効な値は整数です。
脆弱性の基準は SCA レポートにのみ適用されます。SCA レポートの詳細については、「[ソフトウェア構成分析レポート](test-workflow-actions.md#test-sca-reports)」を参照してください。
**[バグ]**
関連する CodeCatalyst レポートが合格としてマークされるように、SA レポート内で許容されるバグの最大数と重要度を指定します。バグを指定するには、以下を指定する必要があります。
+ カウントするバグの最小重要度。有効な値は、重要度が高い順に、`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL` です。
例えば、`HIGH` を選択すると、`HIGH` と `CRITICAL` のバグが集計されます。
+ 指定された重要度のバグの最大許容数。この数を超えると、CodeCatalyst レポートは失敗としてマークされます。有効な値は整数です。
バグ基準は、PyLint SA レポートおよび ESLint SA レポートにのみ適用されます。SA レポートの詳細については、「[静的分析レポート](test-workflow-actions.md#test-static-analysis-reports)」を参照してください。
**[セキュリティの脆弱性]**
関連する CodeCatalyst レポートが合格としてマークされるように、SA レポート内で許容されるセキュリティ脆弱性の最大数と重要度を指定します。セキュリティの脆弱性を指定するには、以下を指定する必要があります。
+ カウントするセキュリティ脆弱性の最小重要度。有効な値は、重要度が高い順に、`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL` です。
例えば、`HIGH` を選択すると、`HIGH` と `CRITICAL` のセキュリティ脆弱性が集計されます。
+ 指定された重要度のセキュリティ脆弱性の最大許容数。この数を超えると、CodeCatalyst レポートは失敗としてマークされます。有効な値は整数です。
セキュリティ脆弱性の基準は、PyLint SA レポートおよび ESLint SA レポートにのみ適用されます。SA レポートの詳細については、「[静的分析レポート](test-workflow-actions.md#test-static-analysis-reports)」を参照してください。
**[品質に関する問題]**
関連する CodeCatalyst レポートが合格としてマークされるように、SA レポート内で許容される品質問題の最大数と重要度を指定します。品質問題を指定するには、以下を指定する必要があります。
+ カウントに含める品質問題の最小重要度。有効な値は、重要度が高い順に、`CRITICAL`、`HIGH`、`MEDIUM`、`LOW`、`INFORMATIONAL` です。
例えば、`HIGH` を選択すると、`HIGH` と `CRITICAL` の品質問題が集計されます。
+ 指定された重要度の品質問題の最大許容数。この数を超えると、CodeCatalyst レポートは失敗としてマークされます。有効な値は整数です。
品質問題の基準は、PyLint SA レポートおよび ESLint SA レポートにのみ適用されます。SA レポートの詳細については、「[静的分析レポート](test-workflow-actions.md#test-static-analysis-reports)」を参照してください。
1. **[コミット]** を選択します。
1. ワークフローを実行して CodeCatalyst で未加工のレポートに成功基準を適用し、成功基準情報を含む関連する CodeCatalyst レポートを再生成します。詳細については、「[手動でのワークフロー実行の開始](workflows-manually-start.md)」を参照してください。
------
#### [ YAML ]
**成功基準を設定するには**
1. ナビゲーションペインで **[CI/CD]**、**[ワークフロー]** の順に選択します。
1. レポートを生成するアクションを含むワークフローを選択します。このレポートに成功基準を適用します。ワークフローが定義されているソースリポジトリまたはブランチ名でフィルタリングすることも、ワークフロー名またはステータスでフィルタリングすることもできます。
1. **[編集]** を選択します。
1. **[YAML]** を選択します。
1. ワークフロー図で、CodeCatalyst レポートを生成するように設定したアクションを選択します。
1. [詳細] ペインで、**[出力]** タブを選択します。
1. アクション内の `AutoDiscoverReports` セクションまたは `Reports` セクションに、**SuccessCriteria** プロパティを追加し、`PassRate`、`LineCoverage`、`BranchCoverage`、`Vulnerabilities`、`StaticAnalysisBug`、`StaticAnalysisSecurity`、`StaticAnalysisQuality` の各プロパティを設定します。
これらの各プロパティの説明については、「[ビルドおよびテストアクション YAML](build-action-ref.md)」を参照してください。
1. **[コミット]** を選択します。
1. ワークフローを実行して CodeCatalyst で未加工のレポートに成功基準を適用し、成功基準情報を含む関連する CodeCatalyst レポートを再生成します。ワークフローの開始に関する詳細については、「[手動でのワークフロー実行の開始](workflows-manually-start.md)」を参照してください。
------
## 品質レポートの YAML 例
次の例は、テストレポート、コードカバレッジレポート、ソフトウェア構成分析レポート、静的分析レポートの 4 つのレポートを手動で設定する方法を示しています。
```
Reports:
MyTestReport:
Format: JUNITXML
IncludePaths:
- "*.xml"
ExcludePaths:
- report1.xml
SuccessCriteria:
PassRate: 90
MyCoverageReport:
Format: CLOVERXML
IncludePaths:
- output/coverage/jest/clover.xml
SuccessCriteria:
LineCoverage: 75
BranchCoverage: 75
MySCAReport:
Format: SARIFSCA
IncludePaths:
- output/sca/reports.xml
SuccessCriteria:
Vulnerabilities:
Number: 5
Severity: HIGH
MySAReport:
Format: ESLINTJSON
IncludePaths:
- output/static/eslint.xml
SuccessCriteria:
StaticAnalysisBug:
Number: 10
Severity: MEDIUM
StaticAnalysisSecurity:
Number: 5
Severity: CRITICAL
StaticAnalysisQuality:
Number: 0
Severity: INFORMATIONAL
```
# テストのベストプラクティス
CodeCatalyst で提供されるテスト機能を使用する際は、以下のベストプラクティスに従うことをお勧めします。
**Topics**
+ [自動検出](#test.best-auto-discovery)
+ [成功基準](#test.best-success-criteria)
+ [パスの包含/除外](#test.best-include-exclude)
## 自動検出
CodeCatalyst でアクションを設定する際に、自動検出を使用すると、JUnit テストレポートなどのさまざまなツールの出力が自動的に検出され、その出力を元に関連する CodeCatalyst レポートが生成されます。自動検出を活用した場合、検出された出力の名前やパスが変更されても、レポートが引き続き生成されます。新しいファイルを追加すると、CodeCatalyst で自動的に検出され、関連するレポートが生成されます。ただし、自動検出を使用する場合は、この機能に関して以下の点を考慮することが重要です。
+ アクション内で自動検出を有効にすると、同じタイプのすべての自動検出レポートで同じ成功基準が共有されます。例えば、最小のパスレートなどの共通の基準は、自動検出されるすべてのテストレポートに適用されます。同じタイプのレポートに異なる基準が必要な場合は、それらのレポートごとに明示的に設定する必要があります。
+ 自動検出では、依存関係によって生成されたレポートも検出されます。成功基準が設定されている場合、それらのレポートに関するアクションが失敗する可能性があります。この問題は、エクスクルードパスの設定を更新することで解決できます。
+ 自動検出では、実行時にアクションがスキャンされるため、毎回同じレポートのリストが生成されるとは限りません。常に特定のレポートが生成されるようにするには、レポートを明示的に設定する必要があります。例えば、ビルドの過程でテストの実行が停止した場合、テストフレームワークで出力は生成されず、その結果、テストレポートも生成されないため、アクションは成功する可能性があります。アクションの成功をその特定のテストに依存させる場合は、そのレポートを明示的に設定する必要があります。
**ヒント**
新規または既存のプロジェクトを開始する際は、プロジェクトディレクトリ全体 (`**/*` を含む) に対して自動検出を使用します。これにより、サブディレクトリ内のファイルを含め、プロジェクト内のすべてのファイルに対してレポート生成処理が呼び出されます。
詳細については、「[アクションにおける品質レポートの設定](test-config-action.md)」を参照してください。
## 成功基準
成功基準を設定することで、レポートに品質しきい値を適用できます。例えば、2 つのコードカバレッジレポートが自動検出され、1 つは 80% のラインカバレッジで、もう 1 つは 60% のラインカバレッジである場合、次のオプションがあります。
+ ラインカバレッジの自動検出の成功基準を 80% に設定します。これにより、1 つ目のレポートは合格し、2 つ目のレポートは失敗し、アクション全体としては失敗します。ワークフローのブロックを解除するには、2 つ目のレポートのラインカバレッジが 80% を超えるまで、プロジェクトに新しいテストを追加します。
+ ラインカバレッジの自動検出の成功基準を 60% に設定します。これにより、両方のレポートが合格し、アクションは成功します。その後、2 つ目のレポートのコードカバレッジを向上させることができます。ただし、このアプローチでは、1 つ目のレポートのカバレッジが 80% 未満に低下しないことを保証できません。
+ ビジュアルエディタを使用するか、レポートごとに明示的な YAML セクションとパスを追加することで、レポートの一方または両方を明示的に設定します。これにより、レポートごとに個別の成功基準とカスタム名を設定できます。ただし、このアプローチでは、レポートパスが変更されると、アクションが失敗する可能性があります。
詳細については、「[レポートの成功基準の設定](test-config-action.md#test.success-criteria)」を参照してください。
## パスの包含/除外
アクション結果を確認する際は、`IncludePaths` と `ExcludePaths` を設定することで CodeCatalyst で生成されるレポートのリストを調整できます。
+ `IncludePaths` を使用して、CodeCatalyst でレポートの検索時に含めるファイルとファイルパスを指定します。例えば、`"/test/report/*"` を指定すると、CodeCatalyst では `/test/report/` ディレクトリを検索するアクションで使用されるビルドイメージ全体が検索されます。そのディレクトリが見つかると、CodeCatalyst でそのディレクトリ内のレポートが検索されます。
**注記**
手動で設定するレポートの場合、`IncludePaths` は単一のファイルに一致する glob パターンである必要があります。
+ `ExcludePaths` を使用して、CodeCatalyst でレポートの検索時に除外されるファイルとファイルパスを指定します。例えば、`"/test/reports/**/*"` を指定すると、CodeCatalyst で `/test/reports/` ディレクトリ内のファイルは検索されません。ディレクトリ内のすべてのファイルを無視するには、`**/*` glob パターンを使用します。
考えられる glob パターンとしては、以下のようなものがあります。
| パターン | 説明 |
| --- | --- |
| `*.*` | 現在のディレクトリ内のドットを含むオブジェクト名すべてと一致する |
| `*.xml` | 現在のディレクトリ内の `.xml` で終わるオブジェクト名すべてと一致する |
| `*.{xml,txt}` | 現在のディレクトリ内の `.xml` または `.txt` で終わるオブジェクト名すべてと一致する |
| `**/*.xml` | すべてのディレクトリ内の `.xml` で終わるオブジェクト名と一致する |
| `testFolder` | `testFolder` というオブジェクトと一致し、ファイルとして扱う |
| `testFolder/*` | `testFolder` の 1 階層下のサブフォルダ (`testFolder/file.xml` など) 内のオブジェクトと一致する |
| `testFolder/*/*` | `testFolder` の 2 階層下のサブフォルダ (`testFolder/reportsFolder/file.xml` など) 内のオブジェクトと一致する |
| `testFolder/**` | `testFolder` 内のサブフォルダ、および `testFolder` 以下にあるファイルと一致する (`testFolder/file.xml` や `testFolder/otherFolder/file.xml` など) |
CodeCatalyst では、glob パターンを次のように解釈します。
+ スラッシュ (`/`) 文字は、ファイルパス内のディレクトリを区切ります。
+ アスタリスク (`*`) 記号は、フォルダの境界を超えない、0 文字以上の名前の要素と一致します。
+ 二重アスタリスク (`**`) は、すべてのディレクトリをまたいで、0 文字以上の名前の要素と一致します。
**注記**
`ExcludePaths` は `IncludePaths` よりも優先されます。`IncludePaths` と `ExcludePaths` の両方に同じフォルダが含まれている場合、そのフォルダはレポート生成のためにスキャンされません。
# サポートされている SARIF プロパティ
Static Analysis Results Interchange Format (SARIF) は、Amazon CodeCatalyst のソフトウェア構成分析 (SCA) レポートおよび静的分析レポートで使用可能な出力ファイル形式です。次の例は、静的分析レポートで SARIF を手動で設定する方法を示しています。
```
Reports:
MySAReport:
Format: SARIFSA
IncludePaths:
- output/sa_report.json
SuccessCriteria:
StaticAnalysisFinding:
Number: 25
Severity: HIGH
```
CodeCatalyst では、次の SARIF プロパティがサポートされています。これらのプロパティを使用して、レポートにおける分析結果の表示を最適化できます。
**Topics**
+ [`sarifLog` オブジェクト](#test.sarif.sarifLog)
+ [`run` オブジェクト](#test.sarif.run)
+ [`toolComponent` オブジェクト](#test.sarif.toolComponent)
+ [`reportingDescriptor` オブジェクト](#test.sarif.reportingDescriptor)
+ [`result` オブジェクト](#test.sarif.result)
+ [`location` オブジェクト](#test.sarif.location)
+ [`physicalLocation` オブジェクト](#test.sarif.physicalLocation)
+ [`logicalLocation` オブジェクト](#test.sarif.logicalLocation)
+ [`fix` オブジェクト](#test.sarif.fix)
## `sarifLog` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `$schema` | はい | バージョン [2.1.0](https://json.schemastore.org/sarif-2.1.0.json) の SARIF JSON スキーマの URI です。 |
| `version` | はい | CodeCatalyst は、SARIF バージョン 2.1.0 のみをサポートしています。 |
| `runs[]` | はい | SARIF ファイルには 1 つまたは複数の実行で構成された配列が含まれており、それぞれが分析ツールの単一の実行を表します。 |
## `run` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `tool.driver` | はい | 分析ツールを説明する `toolComponent` オブジェクトです。 |
| `tool.name` | いいえ | 分析の実行に使用されるツールの名前を示すプロパティです。 |
| `results[]` | はい | CodeCatalyst に表示される分析ツールの結果です。 |
## `toolComponent` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `name` | はい | 分析ツールの名前です。 |
| `properties.artifactScanned` | いいえ | 分析ツールで分析されたアーティファクトの合計数です。 |
| `rules[]` | はい | ルールを表す `reportingDescriptor` オブジェクトの配列です。分析ツールでは、これらのルールに基づいて、分析されたコードの問題を検出します。 |
## `reportingDescriptor` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `id` | はい | 検出結果の参照に使用される、ルールの一意の識別子です。 最大長: 1,024 文字 |
| `name` | いいえ | ルールの表示名です。 最大長: 1,024 文字 |
| `shortDescription.text` | いいえ | ルールの短い説明です。 最大長: 3,000 文字 |
| `fullDescription.text` | いいえ | ルールの完全な説明です。 最大長: 3,000 文字 |
| `helpUri` | いいえ | ルールのプライマリドキュメントの絶対 URI を含むようにローカライズできる文字列です。 最大長: 3,000 文字 |
| `properties.unscore` | いいえ | スキャンの検出結果がスコアリングされているかを示すフラグです。 |
| `properties.score.severity` | いいえ | 検出結果の重要度レベルを指定する固定された文字列セットです。 最大長: 1,024 文字 |
| `properties.cvssv3_baseSeverity` | いいえ | [Common Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3.1/specification-document) に基づく重要度の定性評価です。 |
| `properties.cvssv3_baseScore` | いいえ | CVSS v3 ベーススコアの範囲は [0.0～10.0](https://nvd.nist.gov/vuln-metrics/cvss) です。 |
| `properties.cvssv2_severity` | いいえ | CVSS v3 値が存在しない場合、CodeCatalyst は CVSS v2 値を検索します。 |
| `properties.cvssv2_score` | いいえ | CVSS v2 ベーススコアの範囲は [0.0～10.0](https://nvd.nist.gov/vuln-metrics/cvss) です。 |
| `properties.severity` | いいえ | 検出結果の重要度レベルを指定する固定された文字列セットです。 最大長: 1,024 文字 |
| `defaultConfiguration.level` | いいえ | ルールのデフォルトの重要度です。 |
## `result` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `ruleId` | はい | 検出結果の参照に使用される、ルールの一意の識別子です。 最大長: 1,024 文字 |
| `ruleIndex` | はい | ツールコンポーネント `rules[]` 内で関連付けられたルールのインデックスです。 |
| `message.text` | はい | 結果を説明するメッセージです。各検出結果に対してメッセージを表示します。 最大長: 3,000 文字 |
| `rank` | いいえ | 結果の優先度、すなわち重要度を 0.0～100.0 の範囲で表す値です。このスケール値では、0.0 が最低優先度、100.0 が最高優先度を示します。 |
| `level` | いいえ | 結果の重要度です。 最大長: 1,024 文字 |
| `properties.unscore` | いいえ | スキャンの検出結果がスコアリングされているかを示すフラグです。 |
| `properties.score.severity` | いいえ | 検出結果の重要度レベルを指定する固定された文字列セットです。 最大長: 1,024 文字 |
| `properties.cvssv3_baseSeverity` | いいえ | [Common Vulnerability Scoring System v3.1](https://www.first.org/cvss/v3.1/specification-document) に基づく重要度の定性評価です。 |
| `properties.cvssv3_baseScore` | いいえ | CVSS v3 ベーススコアの範囲は [0.0～10.0](https://nvd.nist.gov/vuln-metrics/cvss) です。 |
| `properties.cvssv2_severity` | いいえ | CVSS v3 値が存在しない場合、CodeCatalyst は CVSS v2 値を検索します。 |
| `properties.cvssv2_score` | いいえ | CVSS v2 ベーススコアの範囲は [0.0～10.0](https://nvd.nist.gov/vuln-metrics/cvss) です。 |
| `properties.severity` | いいえ | 検出結果の重要度レベルを指定する固定された文字列セットです。 最大長: 1,024 文字 |
| `locations[]` | はい | 結果が検出された場所のセットです。問題を修正するためにすべての指定された場所で変更が必要な場合を除き、1 つの場所のみを含めます。CodeCatalyst は、location 配列内の最初の値を使用して結果に注釈を付けます。 `location` オブジェクトの最大数: 10 |
| `relatedLocations[]` | いいえ | 検出結果に関連する他の場所の参照リストです。 `location` オブジェクトの最大数: 50 |
| `fixes[]` | いいえ | スキャンツールで提供される修正推奨を示す `fix` オブジェクトの配列です。CodeCatalyst は、`fixes` 配列内の最初の修正推奨を使用します。 |
## `location` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `physicalLocation` | はい | アーティファクトとリージョンを識別します。 |
| `logicalLocations[]` | いいえ | アーティファクトを参照せずに名前で示される場所のセットです。 |
## `physicalLocation` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `artifactLocation.uri` | はい | アーティファクトの場所を示す URI です。通常は、リポジトリ内に存在するファイルまたはビルド中に生成されるファイルを指します。 |
| `fileLocation.uri` | いいえ | ファイルの場所を示すフォールバック URI です。これは、`artifactLocation.uri` が空を返す場合に使用されます。 |
| `region.startLine` | はい | そのリージョン内で最初に文字が存在する行番号です。 |
| `region.startColumn` | はい | そのリージョン内で最初に文字が存在する列番号です。 |
| `region.endLine` | はい | そのリージョン内で最後に文字が存在する行番号です。 |
| `region.endColumn` | はい | そのリージョン内で最後に文字が存在する列番号です。 |
## `logicalLocation` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `fullyQualifiedName` | いいえ | 結果の場所を示す追加情報です。 最大長: 1,024 文字 |
## `fix` オブジェクト
| 名前 | 必要 | 説明 |
| --- | --- | --- |
| `description.text` | いいえ | 各検出結果に対する修正推奨を表示するメッセージです。 最大長: 3,000 文字 |
| `artifactChanges.[0].artifactLocation.uri` | いいえ | 更新する必要があるアーティファクトの場所を示す URI です。 |