A golden ticket from QA

published 20.4.2020

debuggingmentoringtesting

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.

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:

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:

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

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:

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:

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.