バグ報告書の書き方と、ワンランク上のテクニック

バグ報告書は、開発チームが問題を迅速に理解し、正確に修正を進めるための重要なコミュニケーションツールです。

品質の高いバグ報告書を作成することは、チーム全体の生産性向上に貢献し、結果としてリリースをスムーズに進めることにも繋がります。

そこで今回はバグ報告書の基本的な書き方と、ワンランク上のテクニックについて解説していきます！

▼テスト効率化の方法についてはこちら▼

まず押さえるのは3つポイント

ここでは、開発チームとの不要なやり取りを減らし、信頼される「品質の番人」として評価されるために、特に意識すべき3つの基本情報について解説します。

ひとつのバグ報告書につき、1つのバグを含める

バグ報告書を作成する際、もっとも基本的な原則の一つが「ひとつの報告書には、ひとつのバグのみを記述する」ということです。

複数の異なるバグや不具合を一つの報告書に詰め込んでしまうと、開発チームはそれぞれの問題の切り分けに手間取り、修正作業の優先順位付けが困難になります。

結果として、修正対応が遅れたり、最悪の場合、一部のバグが見落とされてしまったりする可能性も出てきます。

例えば、ある機能の表示崩れと、別の機能でのデータ更新エラーが同時に見つかった場合でも、これらは別々の報告書として作成すべきです。

それぞれのバグに固有のIDを割り当てることで、開発チームは個別の問題として追跡しやすくなり、効率的に修正を進めることができます。

また、これにより、過去に修正した不具合が再び発生する「デグレード」を防ぐための詳細な管理も容易になります。

一つの報告書に一つのバグというルールを徹底することで、開発チームとのスムーズな連携が実現し、報告書作成にかかる無駄な工数を削減することにも繋がるでしょう。

具体的に事実を伝える

バグ報告書においては、推測や感情的な表現を避け、客観的な事実を具体的に伝えることが不可欠です。

あいまいな表現や主観的な感想が含まれると、開発者はバグの再現や原因特定に時間を要し、修正作業が滞る原因となります。

例えば、「何か表示がおかしい」といった記述では、開発者は何が問題なのかを把握できません。

代わりに、「〇〇画面で××ボタンをクリックすると、レイアウトが崩れ、テキストの一部が画面外にはみ出す」のように、具体的な操作手順、発生した現象、そしてその現象が確認された環境（例：特定のブラウザやOSのバージョン）を明確に記述することが重要です。

第三者が報告書を読んだ際に、予備知識がなくてもバグの状況を完全に理解し、再現できるレベルを目指しましょう。

バグと要望を切り分けて伝える

バグ報告書は、システムが仕様通りに動作しない「バグ」を報告するためのものであり、システムに対する「要望」や「改善提案」とは明確に区別して伝える必要があります。

テスト中に、「こうなったらもっと良いのに」と感じる点や、既存の機能に対する改善案が浮かぶことは少なくありません。

しかし、これらをバグ報告書に混同して記述してしまうと、開発者は何が本当の不具合で、何が将来的な機能追加や改修の提案なのかを区別するのに時間を要してしまいます。

例えば、あるボタンの配置が使いにくいと感じたとしても、それが現在の仕様通りであれば、それはバグではなく「UI改善の要望」として別の形で伝えるべきです。

バグ報告書には、現状のシステム動作と、本来あるべき（期待される）システム動作との乖離を、客観的な事実に基づいて記述します。

期待される動作が明確でない場合は、その根拠となる仕様書や要件定義書を参照し、具体的な情報を記載することが重要です。

もし、仕様が存在しない、あるいは不明確な場合は、「ユーザーとしてはこうあるべきだと考える」といったように、それが提案であることを明確にした上で記載するようにしましょう。

バグと要望を明確に切り分けることで、開発者は修正すべき問題に集中でき、効率的な開発サイクルを維持することができます。

バグ報告の書き方

ここでは、開発リーダーから指摘を受けないような、一度で伝わるバグ報告書を作成するための具体的な項目と、その記載例について解説します。

タイトル

バグ報告書のタイトルは、そのバグの概要を短く、かつ正確に伝える重要な役割を担います。

開発者はまずタイトルで報告書の内容を判断するため、一目で何が問題なのかが理解できるような記述を心がけましょう。

タイトルを見ただけで、どの機能で、どのような種類の問題が発生しているのかが分かるようにすると、開発チームは適切な担当者へ速やかに共有できます。

抽象的な表現や、複数のバグを示唆するような内容は避け、具体的な事象を端的に表現することが重要です。これにより、開発者は他のタスクとの優先順位付けも行いやすくなります。

このように、影響範囲や発生箇所、問題の種類を明確に盛り込むことで、開発者は報告書を開く前からバグの全体像を把握しやすくなります。

発生した事象

発生した事象の項目には、実際にシステム上で何が起こったのかを客観的に、そして具体的に記述します。

ここでの記述が曖昧だと、開発者は現象を正確に把握できず、再現手順を追う前に不明点を問い合わせる必要が出てくるかもしれません。

これは、修正までのタイムロスに繋がり、リリースの遅延にも影響する可能性があります。

推測や感情は一切交えず、事実のみを淡々と記述することが肝心です。

エラーメッセージの全文や、画面の表示崩れであれば具体的な場所、予期せぬ挙動であればその詳細などを記しましょう。

スクリーンショットや動画を添付することで、視覚的に事象を伝えることができ、開発者の理解をより深めることが可能です。

再現方法

再現方法は、開発者がバグを特定し修正するために最も重要な項目の一つです。

この項目では、発生した事象を開発者が自身の環境で再現できるよう、具体的で順序立てた手順を詳細に記述します。

あいまいな手順や、一部の手順が欠けている場合、開発者はバグを再現できず、修正作業に取り掛かることができません。

再現手順が不明瞭だと、何度も質問のやり取りが発生し、無駄な工数が発生してしまいます。

可能な限り簡潔に、かつ漏れなく手順を記述することで、開発者はスムーズにバグを再現し、原因の特定に進むことができます。

誰が試しても同じ結果になるように、具体的なクリック箇所や入力値を明確に伝えましょう。

期待する結果

期待する結果の項目では、バグが発生しなかった場合に、システムがどのように動作するべきだったのかを明確に記述します。

この項目は、発生した事象と対比させることで、何が「異常」であるのかを開発者に理解させる上で非常に重要です。

システムのあるべき姿を具体的に示すことで、開発者は修正のゴールを明確に認識し、手戻りのない効果的な対応が可能になります。

もし、期待する結果が仕様書に明記されている場合は、その該当箇所への参照を追記すると、さらに信頼性の高い報告書になります。

このように、期待されるシステムの状態や画面遷移を具体的に記述することで、開発者はバグを修正した後の動作検証もスムーズに行えるでしょう。

実行環境

実行環境の項目は、バグがどの環境で発生したのかを特定するために不可欠な情報です。

バグは特定のOS、ブラウザ、デバイス、ネットワーク環境などでしか発生しない「環境依存」のケースが多いため、この情報が欠けていると開発者はバグを再現できず、原因究明に多大な時間を費やすことになります。

詳細な実行環境を記述することで、開発者は再現環境を構築しやすくなり、効率的なデバッグ作業が可能になります。

その他、モバイルアプリの場合はデバイス名やOSのバージョン（例：iPhone 15 Pro, iOS 17.5.1）、特定のネットワーク環境でのみ発生する場合はその詳細なども含めると良いでしょう。

このように詳細な環境情報を伝えることで、開発者はピンポイントで問題の再現と解決に臨むことができ、結果としてバグ修正のリードタイム短縮に貢献します。

ワンランク上のテクニック！

ここでは、基本事項に加え、さらに一歩進んだ「ワンランク上のテクニック」を紹介します。

画面キャプチャーを添付する

バグ報告書に画面キャプチャー（スクリーンショットや動画）を添付することは、テキストだけでは伝わりにくい視覚的な情報を補完し、開発者の理解を深める上で非常に有効な手段です。

特に、レイアウトの崩れ、特定の操作後の表示異常、アニメーションの不具合など、見た目の問題は言葉で説明するよりも、実際の画面を見せる方がはるかに正確に伝わります。

動画であれば、バグが発生するまでの操作手順や、特定の条件下でのみ発生する現象を、時間軸に沿って具体的に示すことが可能です。

単なるスクリーンショットだけでなく、問題箇所を赤枠で囲んだり、矢印で示したりする簡単な加工を施すことで、開発者は瞬時に問題点を把握できます。

これにより、開発者からの「詳細な状況が知りたい」といった問い合わせを減らし、無駄なやり取りを削減できます。

視覚情報による補足は、バグの再現性を高め、開発チームが迅速に原因を特定し、修正に取り掛かるための強力な手助けとなるでしょう。

エラーログを添付する

エラーログは、バグが発生した際にシステムが内部で記録している詳細な情報であり、開発者が問題の原因を特定する上で非常に重要な手がかりとなります。

特に、アプリケーションの予期せぬ終了、データ処理の失敗、サーバーとの通信エラーなど、目に見えないバックエンドの問題を報告する際には、エラーログの添付が不可欠です。

ログには、エラーの種類、発生時刻、関連するファイルや関数、スタックトレースといった情報が含まれており、開発者はこれらの情報を分析することで、コードのどの部分に問題があるのかを迅速に特定できます。

単に「エラーが発生しました」と報告するだけでは、開発者は問題解決のための手がかりを得られず、原因究明に多大な時間を費やすことになります。

しかし、具体的なエラーメッセージやスタックトレースを添付することで、開発者は問題の根源に直接アプローチできるようになります。

ログを添付する際は、個人情報や機密情報が含まれていないかを確認し、必要に応じてマスキングするなどの配慮も重要です。

エラーログの適切な提供は、開発チームが効率的にバグを修正し、リリースの遅延を防ぐ上で極めて有効なテクニックと言えます。

HARファイル

HAR（HTTP Archive）ファイルは、ウェブブラウザとサーバー間のすべての通信記録を保存したファイルであり、ウェブアプリケーションのバグ報告において非常に役立つ情報源です。

特に、API通信の失敗、読み込み速度の低下、特定のコンテンツが正しく表示されないなど、ネットワーク関連のバグを報告する際にその真価を発揮します。

HARファイルには、各リクエストとレスポンスのヘッダー、ボディ、ステータスコード、タイミング情報などが含まれており、開発者はこのファイルを確認することで、どのリクエストで問題が発生しているのか、サーバーからの応答はどうなっているのかといった詳細なネットワーク状況を把握できます。

通常のスクリーンショットやエラーログだけでは捕捉しきれない、ネットワークレベルでの問題を分析するために不可欠な情報を提供します。

例えば、特定のリソースがロードされていない、あるいはAPIからのレスポンスが期待と異なる場合に、HARファイルを見ればその原因を特定しやすくなります。

HARファイルの取得方法はブラウザの開発者ツールから簡単に行えるため、ウェブアプリケーションのテストを行う際には、ぜひ習得しておきたいスキルです。

これを添付することで、開発チームはバグの再現手順を追うことなく、直接的な原因究明に進むことができ、修正の迅速化に貢献します。

5W1Hで漏れがないかセルフレビュー

バグ報告書を作成した後、送信する前に「5W1H（When, Where, Who, What, Why, How）」のフレームワークを用いてセルフレビューを行うことは、報告書の品質を飛躍的に向上させる効果的なテクニックです。

このフレームワークに沿って各項目を再確認することで、情報の抜け漏れやあいまいな表現がないかを確認し、開発者がバグを迅速に理解し、再現するための十分な情報が提供されているかをチェックできます。

具体的には、以下の点を確認します。

このセルフレビューを行うことで、開発者からの質問を未然に防ぎ、一度の報告で修正作業に移行できる質の高いバグ報告書を作成できるようになります。

報告書作成にかかる時間を短縮し、ワークライフバランスの改善にも貢献するでしょう。

緊急度・影響度タグ付けで優先度を明確化

バグ報告書に緊急度（Severity）と影響度（Priority）のタグ付けを行うことは、開発チームが限られたリソースの中で、どのバグから優先的に修正すべきかを判断する上で非常に重要な情報となります。

緊急度は「バグがシステムに与える技術的な影響の大きさ」を示し、影響度は「バグがビジネスやユーザーに与える影響の大きさ、および修正の優先順位」を示します。

これらの情報を明確にすることで、開発者は効率的に修正計画を立てることができ、リリースの遅延リスクを最小限に抑えることが可能です。

例えば、システムが完全に停止するような致命的なバグであれば緊急度・影響度ともに「高」と判断されますが、些細な表示崩れであれば緊急度・影響度ともに「低」と判断されるでしょう。

これらのタグ付けは、客観的な基準に基づいて行う必要があり、感情や主観が入り込まないように注意が必要です。

チーム内で事前に緊急度と影響度の定義を共有し、一貫した基準で評価できるようにしておくことが望ましいです。

これにより、開発チームとの認識の齟齬を防ぎ、スムーズな連携を実現します。

適切なタグ付けは、あなたの報告書が開発チームから信頼され、修正が迅速に進むための重要な要素となるでしょう。

まとめ

今回は開発チームとのスムーズな連携と迅速なバグ修正を実現するためのバグ報告書の書き方について解説しました。

まず、「ひとつのバグ報告書につき1つのバグを含める」、「具体的に事実を伝える」、「バグと要望を切り分けて伝える」という3つの基本を押さえることが重要です。

これに加え、タイトル、発生した事象、再現方法、期待する結果、実行環境といった各項目を具体例を交えて説明し、一度で伝わる報告書作成のポイントを紹介しました。

さらに、画面キャプチャやエラーログ、HARファイルの添付といった、より高度な情報を提供することで、開発者の理解を深め、問題解決を加速させる「ワンランク上のテクニック」もご紹介しました。

そして、送信前の5W1Hによるセルフレビューや、緊急度・影響度のタグ付けは、報告書の品質を向上させ、開発チームの優先順位付けを明確にする上で非常に有効です。

これらのポイントを実践することで、バグ報告が一度で受け入れられ、修正がより迅速に進むようになるでしょう。

また、質の高いバグ報告書は、開発者から信頼される「品質の番人」として評価され、結果としてキャリアアップにも貢献するはずです。

ぜひ今回の内容を参考に、日々の業務で活かしてみてください！

QA業務効率化ならPractiTest

テスト管理の効率化についてお悩みではありませんか？そんなときはテスト資産の一元管理をすることで工数を20%削減できる総合テスト管理ツール「PractiTest」がおすすめです！

この記事の監修

Dr.T。テストエンジニア。
PractiTestエバンジェリスト。
大学卒業後、外車純正Navi開発のテストエンジニアとしてキャリアをスタート。DTVチューナ開発会社、第三者検証会社等、数々のプロダクトの検証業務に従事。
2017年株式会社モンテカンポへ入社し、マネージメント業務の傍ら、自らもテストエンジニアとしテストコンサルやPractiTestの導入サポートなどを担当している。

記事制作：川上サトシ