This article presents a requirement for our freelancers. Failure to follow the process might represent a breach of the Freelancer Services Agreement.
When testing an app, if a step fails or it is not possible to test the step due to an issue, testers should report an issue. Before reporting a new issue, the testers need to make sure that their issue is not a duplicate of an issue that has already been reported. See how to look for duplicates.
To create a high-quality report for the new issue, think of:
The Problem – Make sure your title and description are focused on the problem and not less important details.
Length – Keep your report short, simple, and focused so that it is easy to follow and understand.
Proof – Make sure to include screenshots, videos, and logs so the issue can be confirmed.
Related Issues – Are there other actions that could cause the same problem? Are they relevant to mention in your report?
When you have created a basic issue report, get AI suggestions to improve the report.
Other specific guidance relates to the specific report field.
Issue Title
The issue title should have the format [Affected feature] Title of the issue
First specify the affected feature between the [ ] brackets.
Add the title of the issue without brackets.
Do not put a dot at the end of the title
Common Mistakes Made with the Issue Title
Typos
Improvement Needed | Good Example |
[Email] Ap crashes when clicking “Add title” | [Email] App crashes when clicking “Add title”
|
Grammatical Mistakes
Punctuation at the end of the title is not needed.
Improvement Needed | Good Example |
[New issue] New issue fail when, response is shown error 503. | [New issue] Creating new issue fails with error code 503 |
[Chat] No notification when try send PM. | [Chat] Notification is not shown when sending a private message
|
Confusing/Too Complex
Titles should be easily understandable. Issue titles should follow the “failure - when” style and indicate the following things:
Exact failure reason
Conditions under which it fails
Issue severity
Improvement Needed | Good Example |
[Working On] Inviting people to file search wrong results until rotating screen | [Working On] Can’t invite people to search files – have to rotate the screen before the option becomes visible |
Does Not Explain the Full Impact of the Issue
The issue title should explain the full impact of the issue, so that issue importance, severity, and priority can be understood from the title.
Improvement Needed | Good Example |
[Chat] Error appears when posting a message | [Chat] Error appears when posting message, although message is sent successfully |
Not Generalized
Some reported issues can be examples of an already existing issue or only 1 case of a more general problem. This should always be checked and, when possible, the title should be written as generalized as possible.
Improvement Needed | Good Example |
[Feed] Error appears when posting private feed update containing ‘<‘ symbol | [Feed] Error appears when posting public or private feed update with HTML tags |
Issue Severity
Select the severity for the issue based on the explanations for each level. Keep in mind that individual workspaces can have their own requirements.
High
Anything that blocks the use of the app or has a significant negative effect on the normal user flow.
For example:
[Login] User is not able to sign in after restoring the network
[Chat] App crashes and the user is logged out after unfriending the user and sending a message
Medium
Issues that have a heavy negative effect on the user experience.
For example:
[Notification Stream] New private message notification stays in-stream even when the user has read the message
[Sign in] App freezes after tapping the Next button to Sign In and twice changing the device orientation
Low
Typos, missing icons, layout issues, and such issues.
For example:
[Calendar] The background of the 'Delete' confirmation window becomes blank (white) after restoring the app from the background
[Game] When entering a name to a new game the text cursor is not shown clearly on the screen
Affected Feature
Click Affected feature to select from a list of different features of the app under test.
Environment Details
In this section, provide the following details about your testing environment:
Your device and OS
App version (Please add the full app version and not just the release number)
Network
Location
Reproducibility rate (you should try reproducing the issue at least 3 times)
Any requirements noted in the specific workspace
Please note that you need to provide your environment details every time you report a new issue.
Steps to Reproduce
Make sure to list the exact steps to reproduce the issue without skipping any steps.
Use > to indicate navigation from one step to the next.
Keep it simple and easy to follow.
The first step should be the prerequisites someone needs before they can follow your reproduction steps.
In most cases when you need to log in to use the app, you don’t need to mention it as a separate step.
Improvement Needed | Good Example |
Steps to reproduce:
| Steps to reproduce:
0. Prerequisite: Log in with valid credentials 1. Settings > Profile > Edit 2. Change Profile picture > Save |
Expected Result
Write a precise summary of the expected result in this situation.
Actual Result
Write a quick note about the actual result and what is broken.
Attachments
It is really important to attach supporting documents (such as screenshots, recordings, logs) with every issue report to provide proof of how the issue occurs on your end.
Attachment naming
A good practice for attachment naming is to name it with a phrase that describes the issue. This helps the developer who downloads the attachments to diagnose the issue.
Attachments for Visual Issues (UI)
Visual issues that are stationary are often easy to display with a screen recording and screenshot that highlight the problematic behavior.
Attachments for Functionality Issues
We require two attachments with every issue report for issues that affect the functionality of the app.
Video
Many visual issues happen when switching between screens, or need motion to be understood. When this happens, screenshots are not sufficient and you need to record a video. See how to record your screen, including requirements on what to do.
Logs
Logs allow developers to dig deep into the root of the issue to see exactly what went wrong on your device. Many crashes and errors are not easy to reproduce. Without a crash or console log, your report will not provide much value. See how to capture logs.
Example of a Good Issue Report
![A screenshot of an issue being created. The title is "[Invite People] Keyboard is not opened after tapping the 'Name' field. All the other sections are completed and there are two attachments, one an image and the other a .mp4 video file.](https://downloads.intercomcdn.com/i/o/984688694/cc68967fb8437e3a09dd0c15/A-Good-Issue-Report_Example.png?expires=1740080700&signature=0f7786fb713822ddab0ea31f732e769d6d4998a8fe4defa29e96e54b6edb48e4&req=fSgjEMF2m4hbFb4f3HP0gFvM7Ltxq3sp5VxEoH6KpM4hshy3C8E4Hyn8ZY1l%0AdwSEfJzOj1ispLHeNw%3D%3D%0A)
#TestlioBot