allure-configure-reporting

Allure レポートの設定

概要

既存のプロジェクトで Allure レポートを機能させることが主な目的の場合に、このスキルを使用します。Allure の結果を出力し、Allure レポートを生成または表示し、CI アーティファクトを保持または公開するか、要求されたエビデンス連携を追加するための、慣用的で最小限の変更をプロジェクトに加え、明確な検証結果の要約を提示します。

レポート設定後の AI／コーディングエージェントのワークフローに関するガイダンスが目的の場合は、allure-configure-agent-workflow を使用してください。Allure エージェントモードを通じたテストの作成、レビュー、デバッグ、拡充が目的の場合は、allure-agent-mode を使用してください。

作業スタイル

チェックリストは厳格な手順ではなく、参考となる指針として使用してください。

• 一般的な例より、プロジェクト内の根拠を優先してください。
• パッケージ名、設定 API、CI 構文、インストール済み CLI の動作が変更されている可能性がある場合は、プロジェクト内を追加で調査するか、公式ドキュメントを確認してください。
• パッケージ名、アクションのバージョン、CLI フラグ、設定キー、環境変数は、出典を確認すべき情報として扱ってください。新たに導入する前に、プロジェクト内のファイル、インストール済みコマンドのヘルプ、Allure／テストランナーの公式ドキュメント、またはパッケージの README／ソースで確認してください。
• ユーザーから依頼された場合、検証に必要な場合、またはプロジェクトがすでに必要としている場合を除き、任意の機能は対象外にしてください。
• 検証済みの Allure 結果が出力されていない場合は、未検証の内容を明確に示さずに、セットアップが機能すると断言しないでください。

連携の対象領域

対象領域ごとに考えてください。ユーザーの目的に合った領域から始めますが、レポートがまだ機能していない場合は、上位レベルのレポートや CI の作業より先に、テストフレームワークからの結果出力を優先してください。

1. テストフレームワークとの連携：テスト実行時に Allure の結果を出力するようにします。
2. Allure ツールのインストール：プロジェクトで承認されたツールを使って、レポートの生成、表示、CLI のラップを可能にします。
3. ビルドシステムのスクリプトとコマンド：既存のプロジェクトの慣習に合う場合に限り、安定したローカルコマンドを追加します。
4. 追加の連携：対象範囲内で有用な場合、マッチャー、HTTP キャプチャ、スクリーンショット、トレース、画像差分、ログ、ラベル、添付ファイル向けの公式またはプロジェクト提供の連携を設定します。
5. CI 連携：テスト失敗を隠さずに、Allure の結果を保持し、シャードを集約し、Allure レポートを生成または公開します。

参考チェックリスト

状況を把握する

• 使用中の言語、パッケージマネージャー、ビルドシステム、テストランナー、テストコマンドを特定します。
• 既存の Allure 依存関係、プラグイン、レポーター、Allure の結果保存先、レポート用スクリプト、CI アーティファクト、ドキュメントを確認します。
• この依頼の対象となる連携領域を判断します。
• 利用可能なテストランナーやビルドシステムが複数ある場合は、依頼されたテスト範囲で実際に使われているものを特定します。

計画する

• 変更が小さくない場合は、編集前に対象の領域、設定先、結果ディレクトリ、検証コマンド、成功の判断基準を示します。
• プロジェクトに適した、追加範囲を最小限に抑えた変更を優先します。
• 実用上可能な限り、既存のテストラッパー、レポーター、パッケージスクリプト、ビルドタスク、CI の動作を維持します。
• プロジェクト内の根拠が不十分な場合や古い可能性がある場合は、Allure とテストランナーの最新の公式ドキュメントを使用します。
• 設定する Allure の結果保存先には allure-results という名前を使用してください。多くのアダプターは任意のパスに書き込めますが、このスキルでは、最終ディレクトリ名を安定して allure-results にするようプロジェクトを導きます。親ディレクトリは、言語、ビルドシステム、ランナー、またはプロジェクトの出力規約に基づいて選択します。この安定したベース名により、allure-results を対象とする glob を使う Allure コマンド（allure results pack など）や、位置引数として受け取るコマンド（allure generate／allure open）からも、結果を見つけやすくなります。

設定

• ユーザーが別の対象を明示的に求めていない限り、レポート生成を追加する前に、フレームワークアダプターの設定を追加または更新します。
• 結果のパスは明示し、名前を allure-results（親ディレクトリは異なっても、ベース名は固定）にします。環境変数よりも、コミット対象のランナー設定ファイルやビルド設定ファイルを優先し、環境変数は主に実行ごとの上書き、シークレット、CI との連携に使います。
• 命名パターンから環境変数を推測して作成しないでください。ALLURE_RESULTS_DIR のように妥当そうな名前も含みます。変数をローカルの根拠やドキュメントで確認するか、不明として扱ってください。詳しいルールについては、references/concepts.md の Result Directory Policy を参照してください。
• 既存の設定で必要な場合を除き、無関係なレポーターや CI の手順を置き換えないでください。
• Allure の設定中は、大規模なリファクタリング、広範囲のフォーマット変更、新たなプロジェクト構成の追加を避けてください。

検証

• ローカルで実行可能な、最小限かつ意味のあるチェックを実行します。
• 想定したディレクトリに Allure の結果が作成または更新されたことを確認します。
• 出力されたデータを十分に調べ、利用可能な場合は、実際のテスト識別情報、ステータス、タイミング、ラベル、ステップ、パラメーター、添付ファイルを確認します。
• テストが失敗しても Allure ファイルが出力されている場合は、製品またはテストの失敗と、レポート連携の成功を区別します。
• 検証を実行できない場合は、その妨げとなっている要因と、未検証の項目を説明します。

引き継ぎ

• 設定した対象、変更したファイル、検証コマンド、Allure の結果パス、残る不明点をまとめます。
• Allure の結果出力、Allure レポート生成、CI アーティファクトの処理、エビデンスの拡充のうち、どれを検証したかを明記します。
• プロジェクトに docs/allure-agent-mode.md がある場合は、レポート設定の変更がローカルラッパー、テストコマンド、Allure の結果パス、連携、CI アーティファクト、実行プロファイル、エビデンスの規約に影響するなら、そのファイルを更新します。
• プロジェクトにエージェントのワークフローに関するガイダンスがない場合は、レポートが機能するようになった後、または不足しているレポート機能が明確に文書化された後に限り、allure-configure-agent-workflow を提案します。

中断して確認する場合

次の場合は、先に進む前に確認してください。

• 複数のテストランナーが有効で、依頼された対象が曖昧な場合
• 依存関係のインストールにネットワークアクセスが必要な場合、またはユーザーの承認を得ていない変更が必要な場合
• ランナーのコマンドを直接実行すると、カスタムラッパー、環境設定、サービスの起動を迂回してしまう場合
• Allure がすでに設定されているものの、意図的に無効化または置き換えられているように見える場合
• 検証に外部サービス、認証情報、ブラウザー、コンテナー、有料サービス、または長時間実行されるスイートが必要な場合
• CI での公開に、新たなリポジトリ権限、トークン、ブランチポリシー、Pages の設定、またはアーティファクト保持に関する判断が必要な場合

参照先の選択

現在の対象に必要な参照ファイルのみを読み込みます。

• コアモデルと結果／レポートの用語：references/concepts.md
• テストフレームワークアダプターの選択と結果の出力：references/test-frameworks.md
• Allure CLI、パッケージ、プラグイン、スタンドアロンツールの選択：references/tool-installation.md
• パッケージスクリプト、ビルドタスク、Make ターゲット、ラッパーコマンド：references/build-system-commands.md
• マッチャー、HTTP キャプチャ、スクリーンショット、トレース、画像差分、ラベル、添付ファイル、および関連ヘルパーの公式連携／プロジェクト連携：references/additional-integrations.md
• GitHub Actions、GitLab CI、CircleCI、Jenkins、TeamCity、Azure Pipelines、Buildkite、およびアーティファクト／レポートの公開：references/ci-integrations.md
• 応用可能なベストプラクティスの例：references/examples.md

調査のガイダンス

まずローカルファイルを確認してください。次の場合は、Allure の公式ドキュメント、テストランナーの公式ドキュメント、パッケージの README ファイル、既存プロジェクトの例を検索してください。

• アダプターパッケージ、設定 API、CLI オプションが変更されている可能性がある
• 提案する環境変数、設定キー、アクション入力、パッケージ名が、プロジェクト内またはインストール済みのヘルプに見つからない
• CI 構文やアクション／プラグインのバージョンがプロバイダー固有である
• リポジトリに Allure のカスタム設定が一部すでにある
• 検証が失敗し、ガイダンスが古い可能性が示唆される
• ユーザーが最新または推奨のセットアップを求めている

Allure の公式ドキュメントは、URL を推測せずに検索してください。

1. https://allurereport.org/docs/、その Markdown インデックス https://allurereport.org/docs.md、またはサイト内蔵の検索を開きます。
2. Frameworks ナビゲーションに表示されるラベル、またはドキュメント検索結果の正確なタイトルからインテグレーションを見つけ、Getting started、Configuration、Reference の各ページへの実際のリンクをたどります。
3. ページが 404 を返した場合は、その URL の使用をやめ、ドキュメントのインデックスまたは検索に戻ります。フレームワーク名からもっともらしいパスを推測して試し続けないでください。
4. ドキュメントのページに記載された情報を使用する前に、ページのタイトルと本文が選択したランナー／インテグレーションに対応していること、また必要なパッケージ名、レポーター／プラグイン／リスナー名、設定キー、CLI フラグ、環境変数が明記されていることを確認します。
5. 公式ドキュメントが利用できなくても、ローカルファイル、インストール済みのヘルプ、パッケージのメタデータ、スキルのリファレンスで、最小限の変更を確実に行える場合は、作業を進め、ドキュメントを確認できなかった旨を記録します。それらの情報が不十分な場合は、推測せず、不足している情報を示して作業を止めます。

汎用的なスニペットをそのまま貼り付けず、リポジトリのパッケージマネージャー、ラッパー、Allure の結果保存先、CI モデルに合わせて調整してください。

最終レポートの形式

報告する際は、次の形式を優先してください。

• 設定済み：対象となる箇所と変更したファイル。
• 検証済み：実行したコマンドと確認した結果ディレクトリ。
• 根拠：確認できた Allure の結果や添付ファイル。
• エージェントのワークフローに関するガイダンス：更新済み、変更なし、提案済み、該当なし。
• 一部未完了またはブロック：検証できなかった内容とその理由。
• 次の有用なステップ：任意のフォローアップ対象（CI での公開やエージェントのワークフローに関するガイダンスなど）。