Mac で不具合を手順ごとのスクリーンショットで報告する方法

第三者が質問せずに不具合を再現できる報告は有用です。手順ごとのスクリーンショットを使うと、開発者は報告者が見た各画面を順番どおりに確認できるため、推測の余地がほとんど残りません。

この記事では、再現可能な報告に必要な要素と、Mac で Temposhot Action Capture を使って手順を記録する方法を説明します。

以下の例は、1つの事例を最初から最後まで追います。Web アプリにはプロジェクト一覧があり、プロジェクト名を変更しても、ページを再読み込みするまで一覧が更新されません。この事例はテストアカウントを使用し、再現に必要な操作は7件で、5回中3回失敗します。

環境を最初に記録する

多くの不具合は、特定のバージョン、特定のブラウザ、特定のアカウント種別でのみ発生します。再現する前に、設定を覚えているうちに環境を書き留めます。

項目	例
アプリまたはサイトのバージョン	About ウィンドウまたはフッターに表示されるビルド番号
macOS のバージョン	「About This Mac」から確認
Mac のモデルとチップ	「About This Mac」から確認
ブラウザとバージョン	Web アプリの場合、ブラウザの About ページから確認
アカウント種別または役割	Free、Paid、admin、viewer
言語と地域	不具合が文字、日付、通貨に関係する場合
日時	タイムゾーンを含める。ログと照合できる

値はテキストとしてコピーします。About ウィンドウのスクリーンショットも有効な証拠ですが、開発者は画像を検索できません。

結果を変える値を集める

すべての詳細がすべての不具合に関係するわけではありません。記録する価値があるのは、値が異なると結果が変わる可能性がある項目です。名前変更の不具合では、ブラウザのバージョンとアカウントの役割が関係します。一覧表示のキャッシュは、viewer と editor で異なる動作をするためです。

簡単な確認で、どの詳細が重要かを判断できます。ブラウザなどの値を1つ変えて、再度試します。不具合が再現しなくなった場合は、その結果を「デスクトップブラウザでは再現し、モバイルアプリでは再現しない」のように記録します。

環境情報を最初のページに置く

環境のブロックは、手順より前の、レポートの先頭に置きます。開発者は課題管理ツールで、添付ファイルを開くかどうかを決める前にタイトルと冒頭の数行を読みます。環境情報が PDF の6ページ目に埋もれていると、開発者は別のブラウザで試し、「再現できない」と報告するおそれがあります。

ログとコンソール出力をテキストで添付する

Web アプリの場合、ブラウザのコンソールには失敗した時点のエラーが表示されることがよくあります。エラー行をテキストとしてコピーし、環境のブロックの下に貼り付けます。コンソールのスクリーンショットは補足として有用ですが、開発者がコードベースでメッセージを検索するにはテキストが必要です。

失敗の近くにある行だけを残します。400行のコンソール出力に関連するエラーが1行だけ含まれていると、読者がそれを探す必要があります。エラーの発生時刻を記録し、試行ログと照合できるようにします。

Mac アプリの場合は、クラッシュレポートまたはエラーダイアログが相当します。ダイアログの文言をエラーコードを含めてそのままコピーし、実行中に手動ショートカットでダイアログを撮影します。

期待結果と実際の結果を書く

報告全体の枠組みは、次の2つの短い文で示します。

• 期待される結果: Save を選択すると、一覧に新しい名前が表示されます。
• 実際の結果: Save を選択すると、一覧には古い名前が表示されたままです。ページを再読み込みすると、新しい名前が表示されます。

原因だと思うことではなく、観察した事実を書きます。「一覧が更新されない」は観察結果です。「キャッシュが壊れている」は推測です。

診断ではなく観察を書く

不具合報告に原因の診断を書くと、開発者が誤った箇所を調べることになります。実際の原因がキャッシュではなくイベントの欠落である場合、「キャッシュが壊れている」という記載は調査時間を無駄にします。観察結果は、誰でも画面で確認できる内容です。

回避策は事実として記載し、重大度の判断は含めません。重大度は、報告を振り分けるチームが決定します。

既知の開始地点から再現する

セッションの途中から再現した場合、「アプリを開く」から始まる報告では実際の前提条件が分かりません。誰でも到達できる状態から始めます。例えば、新規サインイン、新しいプロジェクト、特定の URL です。

記録の前に、不具合を少なくとも2回再現します。時々しか発生しない場合は、「5回中3回」のように発生頻度を記録します。

開始状態を作る

名前変更の不具合の開始状態は、サインイン画面を表示した、サインアウト済みのブラウザウィンドウです。先にサインアウトすると以前のセッションが消去されるため、開発者は報告者と同じ状態から始められます。

各試行を記録する

断続的に発生する不具合には、短い試行ログが必要です。各試行の時刻と失敗の有無を記録し、開発者がサーバーログと照合できるようにします。発生頻度を示すには、通常5回の試行で十分です。

手順を最小限に減らす

不具合が最初に現れた手順が最短であることはほとんどありません。記録の前に、操作を1つずつ取り除き、不具合が再現するかを確認します。この例では、名前変更の前にプロジェクトの詳細を開く操作が不要だと分かり、手順を9件から7件に減らしました。

手順が短いと、次の2つの利点があります。開発者は各再現にかかる時間が減ります。また、操作が少ないほど、読者が別の操作をする箇所も減ります。残りの操作を1つ取り除くと不具合が再現しなくなった時点で、削減を止めます。

記録した実行中に不具合が現れなかった場合も、記録は保存します。直前の数回の操作を繰り返し、失敗が現れたら手動ショートカットを押します。成功した実行の記録も、正確な手順を示せるため有用です。

必要な操作ごとにスクリーンショットを1枚撮る

1. Action Capture を開く

   Command+3 を押し、Start Action Capture を選択します。1つのアプリを記録する場合は Specific Window を、操作が複数のアプリにまたがる場合は Active Window を選択します。

2. 操作を実行する

   Temposhot が受け付けた各クリックは、クリックの直前のウィンドウを保存します。そのため、各ページには操作前にそのコントロールが表示されます。

3. 失敗を撮影する

   誤った結果が表示されたら、Shift+Command+2 を押すか、フローティングツールバーの Capture now を選択します。失敗画面は、クリックをしなくても表示されることがよくあります。

4. 撮影を終了する

   Finish capture を選択します。Document がエディタで開き、手順ごとに1ページずつ表示されます。

Parse clicked elements をオンにすると、ページタイトルは Click "[[element-name]]" の形式で始まります。Visual Annotations の Show cursor on click captures と Mark clicked area をオンにすると、各ページでクリックした位置が分かります。不具合が Temposhot 自体にある場合は、Include toolbar in captures をオンにして、手順にフローティングツールバーを表示します。

実行設定を一度行う

Configure Action Capture の設定は Mac に保存され、以降の実行で再利用されます。不具合報告用に行った設定は、次の報告でもそのまま使われます。

1つのブラウザウィンドウ内の不具合では Specific Window を選択します。この設定では、別のウィンドウでのクリックは無視されます。ただし Capture outside clicks がオンの場合は除きます。再現の途中でアプリが切り替わる場合（例: メールのリンクからブラウザへ移動する場合）は Active Window を選択します。

実行を手順数の上限に合わせる

無料プランでは、Action Capture の1回の実行につき手順数の上限が5件です。名前変更の不具合には、必要な操作7件と失敗画面が必要なため、無料プランの実行は5件目の手順の後で一時停止します。それまでに保存された手順は、実行内に残ります。

この問題に対処する方法は2つあります。サインイン後など、自然な区切りで再現を2回の実行に分け、2回目の実行を同じ Document に追加します。または、Temposhot Pro を有効化します。Pro では上限がなくなるため、1回の実行ですべての手順を記録できます。

実行中にキーボードを使う

再現中はキーボードから手を離さないことで、余分なクリックによる不要なページを避けられます。以下のショートカットは、実行とその後の編集に使用します。

Temposhot は、連続しすぎたクリックを無視します。一覧項目のダブルクリックは、2つではなく1つの手順になります。

クリックが記録されない場合

想定より保存された手順が少ない場合、原因は限られています。再度記録する前に、次の順番で確認します。

• フローティングツールバーに Paused と表示されている場合は、Resume capture を選択します。一時停止中のクリックは保存されません。
• 対象が Specific Window で、クリックが別のウィンドウに入った場合は、対象の内部をクリックするか、Capture outside clicks をオンにします。
• Mouse click capture が、押し続けるキーを必須にするか無視するモードに設定されています。不具合報告では、Capture every mouse click に戻します。
• アクセシビリティ権限がありません。Permissions Required で、Screen Recording と Accessibility の両方が Granted と表示されている必要があります。

解析されたタイトルがすべて Click here になる場合、対象アプリはコントロールのアクセシビリティデータをほとんど公開していません。手順は保存されています。タイトルのみを手動で書き直す必要があります。

状態の変化を説明するテキストを追加する

スクリーンショットは画面を示します。ただし、画面間で何が変わったかは必ずしも示しません。その説明には Page description を使います。例: 「ここではカウンターが 4 と表示されるべきです。実際には 3 と表示されています。」

失敗ページでは、Rectangle (R) で誤った値を囲み、Text (T) で期待される値のラベルを追加します。誤ったクリックによるページは削除し、手順が必要な操作のみになるようにします。タイトルは、「Save を選択」のように平易な手順に書き換えます。すべてのツールとショートカットは エディタガイド に記載されています。

事例のページを整理する

記録した名前変更の実行では9ページが生成されました。1ページは一覧の空の部分をクリックしたもの、もう1ページはブラウザのアドレスバーをクリックしたものです。この2ページを削除し、手動ショートカットで撮影した失敗ページは残しました。その結果、操作ページ7枚と失敗ページ1枚になりました。

解析されたタイトルは出発点にすぎません。Click "Rename" は「プロジェクトメニューで Rename を選択」に書き換えます。この形式であれば、コントロールの位置も読者に伝わります。パーサーが名前を取得できなかったページは Click here と表示され、必ず書き直しが必要です。

状態の変化を説明する記述のパターン

不具合報告のページ説明の大半は、3つの短いパターンで書けます。「この手順の前に、一覧には12件のプロジェクトが表示されている」は開始時の値を記録します。「入力後2秒待つ」はスクリーンショットでは示せないタイミングを記録します。「ここでは一覧に Q3 Budget が表示されるべきである」は、不具合が発生するページで期待される状態を記録します。

各説明は1文から2文にまとめます。説明が長いと、PDF でスクリーンショットが下に押し下げられます。説明を Before image に設定すると、読者は先に文章を読みます。

失敗ページに注釈を付ける

失敗ページには最も多くの情報が含まれるため、最も多くの注釈を付けます。通常は、古い名前を囲む Rectangle 1つと、期待される名前を示すテキストラベル1つで十分です。1ページの注釈が3件を超えると、誤った値を見つけにくくなります。

大きなウィンドウで一覧が小さく表示される場合は、失敗ページで Framing を Close（レベル4）などのレベルに設定します。元の画像は変更されません。開発者が全体の文脈を必要とする場合は、Show full image を選択すると、全体の画像を表示できます。

非公開情報を保護する

不具合報告は、課題管理ツール、チャットスレッド、ベンダーのチケットにコピーされます。すべてのスクリーンショットは、組織内で公開される前提で扱います。

• 可能な場合は、テストアカウントとサンプルデータを使って再現します。
• サイドバー、ブラウザのタブ、通知は、Framing (F) と Custom で切り抜きます。
• 名前、メールアドレス、トークン、ID は、Blur (B、Pro) でぼかします。
• 貼り付ける URL やログのテキストから、セッショントークンと API キーを削除します。

書き出しサイズで全ページを確認する

キャンバスを50%に縮小した状態で値を隠しているぼかしが、等倍では読めてしまうことがあります。Object Inspector の Blur strength を、文字が読めない値に設定します。既定値は、2から80の範囲で12です。送信する前に、書き出しプレビューのすべてのページを確認します。

ブラウザのアドレスバーの URL は、情報が漏れやすい箇所です。共有リンクやパスワードリセットトークンがアドレスバーにあると、ブラウザで再現した場合はすべてのページに表示されます。そのため、各ページでアドレスバーを Framing で切り抜くか、ぼかしを入れます。

不具合報告の構成を使う

1. Title: 何が、どこで失敗するか。「名前を変更した項目が一覧表示で更新されない」
2. Environment: 上記の表の値。
3. Steps to reproduce: 既知の開始状態から始まる、番号付きの手順。
4. 期待結果と実際の結果。
5. Frequency: 常に発生するか、発生頻度。
6. Evidence: 書き出したスクリーンショットガイドと、ログやコンソールエラーのテキスト。
7. Workaround: 存在する場合の回避策。

添付ファイル1件として出力する場合は、Document から Export PDF を選択します。課題管理ツールでインライン表示される PNG ページとして出力する場合は、More export formats を選択します。画像のファイル名はページタイトルに従います。すべての形式は 書き出しガイド に記載されています。

課題管理ツールに合った書き出し形式を選ぶ

課題管理ツールによって、添付ファイルの表示方法は異なります。ツールが課題本文内で画像をプレビュー表示する場合は、インラインの PNG ページが適しています。開発者はファイルを開かずに手順を読めます。ツールが添付ファイルを一覧表示するだけの場合や、報告を外部のベンダーに送る場合は、1つの PDF が適しています。

ZIP package 形式は、描画された PNG ページと document.json ファイルを1つのアーカイブにまとめます。ファイルを1つだけ受け付け、画像とページのテキストの両方が必要なベンダーのチケットに適しています。

記入例

名前変更の報告は、課題管理ツールでは次のように記載されます。タイトルは「名前を変更したプロジェクトが、再読み込みまで Projects 一覧で古い名前のまま表示される」です。環境のブロックには、ビルド番号、macOS のバージョン、ブラウザのバージョン、役割 editor、14:02から14:20までの試行時刻を記載します。

手順は、「qa-editor としてサインインする」から「名前変更ダイアログを閉じる」までの番号付き7行です。期待結果と実際の結果は、前述の2文を使用します。発生頻度は「5回中3回」です。証拠は8ページの PDF で、回避策は「ページを再読み込みする」です。

PDF は既定の書き出し設定を使用します。用紙は A4、向きは Landscape、表紙、手順番号、ページ番号を有効にし、説明は画像の前に配置します。これらの設定をカスタマイズするには Temposhot Pro が必要です。既定値のままでも不具合報告に適しています。

手順もテキストで書く

PDF に手順が含まれている場合でも、番号付きの手順を課題本文にテキストとして貼り付けます。テキストの手順は検索でき、コメントで引用でき、テストケースにコピーできます。その場合、スクリーンショットは唯一の記録ではなく、各手順の証拠として機能します。

送信前に報告をテストする

不具合を一度も見たことがないつもりで、報告を先頭から読みます。さらに確実なのは、同僚に自分の Mac で報告の手順をたどってもらうことです。同僚が質問せずに不具合を再現できれば、報告は完成です。

試験的な確認で見つかる一般的な不備

同僚による試験的な確認では、通常3種類の不備のいずれかが見つかります。1つ目は、開始状態が欠けている場合です。例えば、事前に存在している必要があるプロジェクトが記載されていない場合です。2つ目は、キーボードショートカットのように、クリックなしで行われる操作があり、ページがない場合です。3つ目は、失敗がタイミングに依存する場合です。例えば、入力後2秒未満で Save を選択する場合です。

不足している状態は最初の手順に追加します。キーボード操作には、手動ショートカットで撮影したページを追加します。タイミングはページの説明に記載します。その後、試験的な確認をもう一度行います。

元の Document を保管する

Document は書き出し後も編集できます。開発者からスクリーンショットを1枚追加で求められた場合は、Document を開き、Capture new images… でページを追加して、再度書き出します。書き出し済みのファイルは自動で更新されません。

よくある質問

不具合報告に動画とスクリーンショットのどちらを含めるべきですか？

ほとんどの不具合では、スクリーンショットで十分です。スクリーンショットは確認しやすく、注釈も付けやすい形式です。タイミングの問題やアニメーションには、動画が役立ちます。詳細は 手順ごとのスクリーンショットガイドと画面録画の比較 を参照してください。

不具合報告には何枚のスクリーンショットが必要ですか？

必要な操作1件につき1枚と、失敗画面の1枚です。結果に影響しないページは削除します。

報告を送った後、スクリーンショットはどこに保存されますか？

Document は Mac 上に残ります。Temposhot にはホスト型のリンクがないため、書き出したファイルを課題管理ツールまたはチケットに添付します。

無料プランで手順が5件を超える不具合の場合はどうすればよいですか？

実行は手順数の上限で一時停止し、それまでに保存された手順を保持します。再現を2回の実行に分け、両方を1つの Document に追加するか、Temposhot Pro を使って上限を超えて記録します。

クリックなしで現れる不具合も撮影できますか？

はい。誤った状態が表示されたら、手動撮影のショートカットを押します。既定のショートカットは Shift+Command+2 です。この手順はクリックなしで保存され、クリックマーカーの設定が有効な場合は、その設定も適用されます。

クリックを明確な手順ガイドに変える

Action Capture は、操作を行いながら再現手順を記録し、クリックマークと下書きのタイトルを付けます。Temposhot をダウンロード して、次の不具合報告を順序付きのガイドとして添付してください。