Are you lucky to have a QA person, or a QA team, that helps you test your application? Are bug reports from QA easy to understand? Can you replicate the issue based on the ticket? How much time do you spend on gathering the required information?

Part of QA work is reporting issues they discover, back to developers. To make the report useful, there should be an agreement on both sides, regarding content of the report and how it's passed around. This would of course depend on your team needs, but there are few things that work universally.

In this post, I tried to document an imaginary "golden ticket" that a UI developer could get from QA. It is a lot of information, and in practice not all of them are needed for all tickets. You could look at this as a checklist of what could be provided, and take it for discussion with your QA/Dev teams. (See attached PDF below)

Ticket name

Of course this is important. Ticket name is the first thing everyone see. You should try to make the title short, precise, and informative.

Worse: "When u r on the second listing page, u should not be redirected 2 the first page after modal with item details is closed"

This is a fairytale, not a ticket title. No need to have the "when-then" construct, neither the coolest "u-r-2" shortcuts to make the story shorter. The negation in the title is not necessary either.

Better: "Closing item detail redirects to the first page of listing"

Imagine being on the issues index page, where you see tens of issues listed. Do you want this page to be brief and easy to read, or are you trying to make it a novel?

Issue detailed description

This is the part dedicated to prose. The description is what interested parties see if they want and open the ticket. Here you should provide all the details you can. As much as you want to make the title descriptive, keep it for description.

Worse: -nothing-

It could be fine for some rare cases, when the ticket title is so specific that it doesn't need details.

Better: what was the initial state, what are the steps to reproduce, what is the current outcome, what is the expected outcome... And more, as I will cover below

Environment where bug is reproducible

If you have multiple deployments, or environments where the app is running, it's priceless to state the one where you tested. If that environment is not accessible to the developer, share anything that could help developer to configure his environment in similar manner. If you are running multiple versions of the product at the same time, or are doing feature flags or A/B testing, details about those should also be provided.

  • environment hostname
  • cloud account used
  • deployment port number
  • server configuration (timezone, distro, region, ...)
  • proxy settings
  • UI theme selected
  • ssh, kubernetes, docker configs

Especially in complex multiserver apps, this is crucial as the app could behave differently on different distros, server configs, or datacenter locations.

User account

Any credentials the developer would need to see or replicate the issue. These could be:

  • the ones used by your own application
  • login information needed to view 3rd party service where the issue could be seen (eg. Browserstack)
  • accounts for integrated tools
  • license used, plan, or trial status

Example: your product's admin email and password, SSH key to open the backend logs

Steps to reproduce the issue

Once all the details about what & where happened are provided, it's time to try to reproduce the issue. For a developer, to be able to fix the issue, he has to know how to get to the issue in the first place. It is also necessary to successfully verify the issue, even by some other person, and to be able to mark it as resolved.

A list of actions or events to follow, should to be documented. The more details provided here, the better. List values entered into fields, options made while navigating the app. If this is not possible to provide for some reason, you can also use some media to support the case - see below.

Example: description of a password reset flow, including links from emails sent to user account.

Support files

Anything needed to reproduce the issue, or that documents the issue itself. At some point, the issue could depend on file upload, certain configuration file or text snippet. Even if it might seem insignificant, there could be a difference in what file you and the developer upload.

For issue replication, you developer could need:

  • API keys
  • certificate files
  • sample file to upload
  • JSON configuration
  • XML file to be parsed by the app
  • image you used for upload

To document the issue itself, there's plenty of options:

  • web browser screenshots
  • copy of a log file
  • gif recording of some interaction
  • video recording of the flow
  • screen capture video with audio commentary

Example: json file in iso-8859-2 encoding, as used by a customer

Browser details

When working on UI of the app, browser details are often essential. There are many things that could be provided, and it is always not clear what is needed.

Always included should be:

  • browser type (mobile, desktop), vendor (Google, Mozilla), or version (if the app depends on native browser APIs)
  • any browser extensions installed and enabled, that could interfere with the app
  • are you running the app in full size of a 13'' laptop screen or 27'' display?

Example: Mac OS Firefox Developer Edition v76 in private mode (no extensions), on 15'' retina display

Along with these, there are other very useful information that browser could provide:

  • console logs - in Firefox or in Chrome
  • network logs - in Firefox or in Chrome - could be in form of just a list of all requests and their HTTP statuses, or detailed request/response payload of some of the requests
  • HAR file export, containing all the HTTP requests made by browser since page load - in Chrome

Example: screenshot of all XHR calls from network logs, and a file with saved response from one of the API calls

Actual vs expected behavior

It could be useful to also provide the description or screenshot of what the functionality, content, or design should be, as opposed to current state. It could be provided in form of a description, screenshot, video or a link to resource.

Documenting these could help the developer to realize the change that has to be made. It also provides invaluable details documentation team, or for anyone else who does not know that part of the app.

Example: wording of buttons labels right now, and what the labels should read instead


What did I miss? What other details do you use in your team?

Download checklist PDF to go through with your team.


Blog Comments powered by Disqus.

Previous Post Next Post