How to record a bug report video developers can act on

What a good bug video shows

A bug video is useful when the person who receives it can repeat what you did. Show these five things, in this order:

• The starting state. The page, screen or account you began on, so the developer can get to the same place.
• The exact steps. Each click and each input, in the order you made them.
• Expected and actual. What should have happened, and what happened instead.
• The error message. If the app shows one, keep it on screen long enough to read.
• The environment. The browser and its version, the app version and the account type, such as admin or a free plan.

Keep the video under about two minutes when you can. That is advice, not a rule. A short clip that starts just before the error is easier to review than a long one where the developer has to search for the moment it happens.

Before you record

Prepare the screen so the recording shows the bug and nothing else.

• Reproduce the bug once. Run the steps before you record, so you know the exact path and that it still fails.
• Clear the test data. Remove what your last attempt left behind, so the first step starts from the same place every time.
• Close private tabs and notifications. Email, chat and personal tabs should not appear in the video.
• Use a test account. Never put real customer data in a video or a ticket.
• Open the console if the bug is in a web app. In Chrome and Edge, press F12 and open the Console tab before you start, so any red error is ready when it appears.
• Note the app version. Look it up before you start and write it down, because the ticket needs it.

Record it with Director

1. Click Choose what to record and pick a whole screen, not a single window. The zoom can only follow your cursor on a whole screen.
2. Turn the microphone on in Director if you want to narrate. Leave it off if you would rather write the explanation.
3. Press CtrlAltP to start.
4. Before each step, say what you expect to happen. For example: “I expect the Save button to close the dialog.”
5. Do the steps slowly. Move the cursor onto each target before you click, and pause on it for a moment.
6. When the bug happens, press CtrlAltN at that moment to drop a marker.
7. Press CtrlAltS to spotlight the error on screen. Press CtrlAltD to turn the spotlight off.
8. If the error message is small, move the cursor onto it and press CtrlAltZ to zoom in. Press CtrlAltX to zoom back out. The zoom guide explains the zoom levels.
9. Keep the error on screen for a few seconds, so it can be read, then press CtrlAltP to stop. The MP4 is saved in your Videos folder, under Director.

Director cannot cut the video. If you make a big mistake, stop and record the take again, which is quick because the take is short. If you need a moment to put the screen back in its starting state, press CtrlAltJ to pause. The video continues with no gap when you resume.

Mark the exact moment

When you stop, Director lists your markers with their timestamps, in the same format as YouTube chapters, such as 01:12 Chapter 3. Copy the timestamp of the bug marker into the ticket, for example: bug at 01:12.

That tells the developer where to look in the video. It does not replace the steps.

Write the ticket next to the video

Director saves the MP4 on your PC. It does not upload the video or create a link, so you attach the file yourself to the ticket in Jira, GitHub issues, Linear or whichever tool your team uses. Then write the ticket text:

• Title: the bug in one line, with the screen or feature where it happens.
• Steps: numbered, from the starting state.
• Expected: what should happen.
• Actual: what happens, with the error message copied as text.
• Environment: browser and version, app version and account type.
• Video: the file name and the marker time, such as bug at 01:12.

The video does not replace written steps. Search finds words, not what happens on screen, so anyone who searches for an error message needs it written in the ticket.

Code reviews and walkthroughs too

The same method works when you show a pull request or explain a change to a teammate. Open the diff in the browser, record a whole screen, and zoom in on the line you are discussing with CtrlAltZ. Then press CtrlAltS to spotlight that line, and CtrlAltN to mark it for the timestamp list.

Related guides

To zoom in on the error while you record, read how to zoom in on a screen recording on Windows. To keep a slow load out of the video, read how to pause a screen recording on Windows. For every hotkey in one place, see screen recording hotkeys on Windows.