For the project managers, developers and QA engineers working on an application, clear communication is the key to efficiency. The project requirements and workflow status has to be clearly conveyed between them. This makes it necessary that bugs detected during testing be properly documented for software quality assurance. JIRA makes the task of issue reporting easier for QA engineers by including some nifty formatting features. Let's take the example of an issue to show how these features help when documenting bugs.
The following screenshot shows the issue screen in JIRA. Formatting features are available in the “Description” field to help make it more organized and presentable.
While documenting the issue in the description field, the QA engineer must clearly convey the following information:
-
What is the issue?
The description should start with a brief and clear statement of the issue. While testing a mobile application, the QA engineer could mention here the devices used to test that particular application component, as in the previous screenshot. Under the heading Environment, the mobile devices used by users A and B are listed in a table format.
The table looks like this because of the syntax behind it. For a header, use the h4. command at the beginning of the line, followed by the header text (such as the word ‘Environment’ here). Headers can be placed in the description by writing hn. at the beginning of the line followed by the header text where n is a number from 1 to 6 in decreasing order of font size.
To add tables to a description, use vertical bars (||) to enclose table headers and to enclose column text.
In the previous example, the syntax for the table is:
|Device A|iPhone 6|User A|
|Device B|Samsung S5|User B|
You can see the effect here:
You want to present the information in an organized manner, so that it easy to understand. The use of headers and tables helps you to do so.
-
How to reproduce the issue step-by-step?
To fix the issue, the developers will need to reproduce it. It would help them if you, as a QA engineer, outline the steps needed to do so. You can use numbered lists to outline those steps.
For creating a numbered list, use the pound or hash symbol (#) in the first space of the syntax. And, if you need to insert any step into the list later on, JIRA helps you out by automatically re-adjusting the order of list numbers.
In the example, the syntax for the steps is:
# Given User A has uploaded video in his private library
# On Device A, send this video to User B as self-destruct
# On Device B, look at the photo preview inside message thread
You can see the effect in the previous image.
If you want to create a bulleted list, you can use an asterisk (*) in the first space of the line. For further indentation, use two asterisks (**).
-
What is the expected behavior?
As a QA engineer, you should describe what the application component is expected to do as part of the issue documentation. Whenever possible, provide a link to the relevant section in the specification documentation.
-
What is the actual behavior?
Of course, you will need to document the actual behavior of the component. This description should be clear and concise. To draw attention to an attribute, you can use syntax to highlight it in bold using an asterisk (*) or italics , use underscore (_) or even choose to display it in a different color. JIRA offers text formatting options for this.
Whenever possible, you should attach test evidence like an image or a video to show the actual behavior of the component. JIRA provides an image-capturing tool called JIRA Capture for web application testing. To use this tool, the URL address of the image is enclosed within ! in the syntax within the Description.
The URL address is further enclosed within the vertical bar (|) symbol so that the image is displayed within a box conforming to its dimensions. The syntax can be something like this :
http://jira.onpathtesting.com:8080/secure/attachment/12747/Screenshot_2015-04-30-18-08-31.png|height=300|width=150!|
What you see in the Description is:
Keep in mind to test for the language of your target market, particularly if it is US or UK English. Developers and QA engineers should use the appropriate spell checker to check for spelling mistakes in error messages.
Conclusion
The use of these formatting features makes it easier to write the documentation for the issue. As you have seen, the syntax of these features is easy to comprehend and use. The clearer your documentation, the better the developers can understand and resolve the issue.
You can learn more about JIRA in our article "Configuring JIRA for mobile software quality assurance".
The features discussed in this blog - namely: text, heading, lists, images and tables - are only a few of the formatting features available in JIRA. For a complete list, follow this link: https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all
