Usage Guide

The Test and Development phases of the software development life cycle process are seen as key indicators to the success and efficiency of a product being available to the general public on time. Here's a usage scenario of how Go2Group synapseRT can add value to your workflow.

Go2Group synapseRT for JIRA 6 Usage Guide

Prerequisite

Please read Technical Documentation for Go2Group synapseRT Plugin as a prerequisite to this document.

Overview

Go2Group synapseRT plugin allows you to operate JIRA Projects by requirement based testing methodology. The operation schematic is shown below.

Release Versions are defined for Jira Project and include Requirement sets. Requirement realization is tested by Test Cases, assigned to one or several Requirements of one or several Releases. Bugs that appeared in testing are used in Defect Tracking process. SynapseRT plugin provides automatic creation of synapseRT Test Project. This Project has Releases, Requirements, Test Cases, Bugs, Workflows already created. This manual is aimed at providing a description of Requirements Based Testing Scenario with usage of synapseRT JIRA plugin.

Requirement Based Testing Scenario

Release Version operation

JIRA Project Administration screen allows us to add new version and manage existing versions. For more information on managing versions, refer to the Atlassian Guide.

Requirements

Release Version is characterized by their Requirements.

Please note - The Requirement issue type is a custom issue type, created during the installation process. Since synapseRT v2.3 all Jira issue types can be Requirements or bugs. See details in Configuration manual.

Requirements Tree

If you have huge amount of requirements and want to organize them into tree view, synapseRT allows you to set a parent record. When you create or edit a requirement you can set a parent requirement for the issue or select None at the parent requirement field.

You can navigate through the tree by pressing - sign to collapse branch and + sign to expand. When you are ready with your selection you can save the issue. You will see a link to parent requirement at your issue in Issue Links section and information about parent requirement for your child requirement. When you change the parent requirement link will be updated automatically.

Please note - The Parent Link is a custom link, created during the installation process.

On the parent requirement page you can see a list of child issues which are accessible through the links

It means that you will have a set of root requirements with child requirements that are organized into a tree and can be used in Requirement field for Test Cases and Bugs.

Requirement Creation Practice

Let's take a look at creating requirements and assigning them to some Versions, Parent Requirements and add an estimate time. If you haven't yet created a test project yet, please create the test project creation provided by synapseRT plugin.

Click on the COG icon on the top right corner of the page and select Add-ons.
Click on "synapseRT Configuration" on the left menu bar.
Click on "Create Test Project"

synapseRT will create a test project named "synapseRT". You should now be able to see it in the list of JIRA projects.

Create two versions in the project "synapseRT". Call it "Version A" and "Version B". For information on how to create new versions, click here.
Click on Create Issue and select synapseRT project and Requirement issue type. Choose the "Fix Versions", Original Estimate and Parent Requirement as shown in the screenshots below.
On the created Requirement page you will see all parameters specified.

Please note - The Time Tracking estimates will update as work is performed (Work Log created) and logged against this requirement.

Sub-Requirements

Sub-requirements are sub-tasks to a JIRA issue. Just create a sub-task of type SubRequirement. Click here for information on how to create sub-tasks.

Select the Releases and Estimated time as it was done for Requirement and click Create button. On the previously created Requirement page now you can see new SubRequirement in Sub-Tasks section.

Test Cases

Test Cases are used for Requirements testing, so one or more Requirements can be assigned to one Test Case. SynapseRT provides the set of useful Test Case custom fields: assigned Requirements (from Requirement tree described above), Test Suite and Test Case State.

Please note - The Test Case issue type is a custom issue type, created during the installation process.

Test Cases tree

From Go2Group synapseRT v3.1 Test Cases are tree based in the same way as the Requirements. So when you create or edit a test case you can set a parent test case for the issue or select Root tree level at the parent test case field.

To navigate through the tree use "-" sign to collapse branch and "+" sign to expand. When you are ready with your selection you can save the issue.

Created issue will have the link to Parent Test Case in the Issue Links section. This section also includes the links to the child Test Cases of the issue.

Subtests

Subtest issue type is additional feature provided by synapseRT. It belongs to Sub-tasks issue types. If it is enabled on synapseRT Dashboard configuration page then when you assign a Test Case to a Test Plan, synapseRT creates Subtest for the Test Case and assigns the Subtest in place of the Test Case. See more in Test Plans section .

Requirements tab

You can see the nested tree of requirements that are assigned to an issue (Test Case, Bug) in the requirement panel. If requirement was not selected for Test Case or Bug then Requirement tab will not be displayed.

Test Suites Management

It can be very useful to organize Test Cases in Test Suites for different Project, Project Categories or globally for Jira. Go2Group synapseRT for JIRA 6 includes Test Suite management feature that allows you to group individual test cases. Test suites will be displayed within JIRA issue windows, similar to the Test Case scenario described above. From synapseRT v2.3 Test Cases can have multiple Test Suites assigned.

You can find the Test Suites management Guide in the corresponding section of Installation Guide .

It is possible to link a Test Case to the Test Suites during creation of a Test Case as it is described in the Test Case Creation Practice section. On the Test Case creation page find Test Suite list. Use [Ctrl] + Left Mouse Click to select several Test Suites in the list.

Test Suite Dashboard mode

To review the linked Test Cases open synapseRT Test Case Planning dashboard.

Set Order option to Test Suite (1). After page reloading you will see several columns with Test Cases. These Test Cases are all linked to Test Suites. The Test Cases linked to several Test Suites are in Undefined column (2). The Test Cases linked to one Test Suite are in corresponded columns (3). You can dynamically change Test Suite for a Test Case using drag and drop functionality.

Test Suite Project tab.

To browse Test Suites which relate to a Jira Project, you can open the Test Suite tab of the Project, see image below.

If you want more Test Cases information on the page, you can enable this feature on synapseRT Configuration page as it is described in the Installation Guide. The tab view with information on Test Case Assignee, Reporter and Fix Versions presented below.

Some Actions are available for the Test Suites in Project Jira Container. These Actions include Edit, Delete, Update operations.

Edit Action allows to rename Test Suite and Delete Action allows to delete Test Suite.

Update Action allows to update Test Cases in the Test Suite. You can change Test Case States and Statuses according to the Active Test Case Workflow.

When Update operation is complete you will see all Test Cases in the Test Suite have new Test Case States and Statuses.

Test Case State and Test Case Results

To run the test scenarios and track the test results synapseRT contains Test Case State and Test Case Results custom fields. Test Case State can be set to one of the following states:

In Progress
Failed
Passed
Can't Test

If you run the test you may update Test Case State field with information about that test run (i.e. test was failed). Also you can put additional information on run in Test Case Results field.

Information to Test Case Result will be appended, not replaced by new values

On the requirements panel you can see that all requirements connected to the test case were marked red. It means that these requirements are connected to failed Test Cases.

If you follow to the requirement view and look at Test Case Coverage you will see a list of Test Cases colored according to their Test Case State

Color Scheme for Test Case States

Test Case State	Color
In Progress	Blue
Failed	Red
Passed	Green
Can't Test	Yellow

This color scheme is available in the Tracebility dashboard too.

There is another option to automate Test Case State change. You can link Test Case State change to real transition in your workflow. During installation process workflow post-function and custom screen were created. See the corresponding section of Installation Guide for instructions.

Test Case State can be applied to the set of user-choosable requirements and test plans

Test Case State can be applied to the requirements and test plans which were defined for a test case by user. User can choose needed issues from issues assigned to a test case.

Create three requirements and three test plans with the summaries provided below. Link each issue with an existing Test Case (SYNAPSE-14 for example).

Issue type	Summary	Link to
Requirement	Test Case State for user choosable requirement #1	SYNAPSE-14
Requirement	Test Case State for user choosable requirement #2	SYNAPSE-14
Requirement	Test Case State for user choosable requirement #3	SYNAPSE-14
Test Plan	Test Case State for user choosable test plans #1	SYNAPSE-14
Test Plan	Test Case State for user choosable test plans #2	SYNAPSE-14
Test Plan	Test Case State for user choosable test plans #3	SYNAPSE-14

Let us take a look at SYNAPSE-14. Follow the below steps from the View Issue screen of SYNAPSE-14.

Choose the Requirement tab on created Test Case page in Activity section. You will see that assigned requirements have blue color. It means that the requirements are connected to In Progress Test Case.
Open the Test Plans tab. It also contains blue-coloured issues.
Update the issue by clicking on the "Edit" button. You will see links to expand the lists of connected requirements and test plans in the Test Case State custom field.

Please note - synapseRT Dashboard configuration page provides an option to make the Test Plans list always expanded
In the Test Case State select list choose failed. In Requirements list choose first connected requirement. Open linked Test Plans list and select first connected one from the list.Update issue by clicking the Update button.
Set Passed and Can't Test Test Case States in the same way for others two requirements and two test plans. Now you will see that Requirements in Requirement tab have different colors and the Test Case issues has different colors in connected Test Plans. The colors correspond to Test Case States defined for the Requirements and Test Plans. It means that our Test Case Failed in first Requirement, Passed in second one and Can't Test in third Requirement.

Creating Test Cases from Requirements

With Go2Group synapseRT, creating a Test Case directly from a related Requirement is easy. Simply click on the More Actions link found in Issue Operations section within the requirement and select Create Test Case item from popup menu, as shown below.

Specify Fix Versions, Original Estimate time, assigned Requirements, Test Suite and Test Case State custom fields for the Test Case.

Please note - Since the Test Case was created within a specific Requirement, the corresponding Requirement and Fix Versions are already selected.

We can now see the test case coverage beginning to take shape, including:

Fix Versions for this issue.
The Requirement summary within the JIRA issue
Assigned Test Suites information.
Parent Test Case link and summary.
Test Case State field and change history.
Test Case Results field.
The Requirement tab, providing additional Requirement details, including a link to the actual Requirement
Time tracking Estimate.

Test Plan

SynapseRT Test Plan is the issue type that provides a test process with user selected Test Cases. It allows you to assign Test Cases to Test Plans, each of which represents a test process. A test plan should be started when testing starts and close when testing is complete. Test Case parameters will be stored in Test Plan for the test process that has been running, so you can review every test process even when it's Test Cases has been changed in other tests. These parameters are Summary, Version, Component, Status, Test Case State, Test Case Results, Requirements and Bugs and they form Test Case Snapshot for a test process.

The below guide shows how to create a test plan.

Create an issue of type Test Plan. Specify a summary and assign a few test cases. These test cases will be covered by this test plan during the test process. Create the issue.
On the Test Plan View Issue screen, open the test plan tab. This tab contains assigned test cases. You can find current Test Case parameters here. Start Test Plan by clicking on "Start Test Plan" transition.
Test cases can be modified while the test plan is "In Progress". Modify SYNAPSE-14 and fail the test case.
When Test Case is changed during the test process, the Test Plan will display the updated information.
Close the Test Plan.

Please note - Test Plan State has been automatically set to Failed since it is the "worst" Test Case State of assigned Test Cases.
Then all Test Case Snapshots are saved in the Test Plan. To verify this, change one of our Test Cases. Let us restart SYNAPSE-14.
Open the test plans tab of the Test Case. This tab contains information about all current and past Test Plans and corresponding Test Case Snapshots for this Test Case as you can see below. In this example, SYNAPSE-14 has different current Status, Test Case State and Test Case Results custom fields than it's Test Case Snapshot in the Test Plan.

Please note - Test Case Snapshot is the set of the Test Case parameters at the moment of Test Plan closing.
Open Test Plan. You will see that Test Plan contains only saved information about Test Case parameters. These parameters are saved in the Test Case Snapshot by Test Plan at the end of test process when Test Plan was closed.

Please note: if you upgrade synapseRT from previous version, synapseRT will create Test Plan workflow and you have to assign this workflow to your workflow schemes.To do this foolow the steps of corresponding Installation Guide section. In the case of clean installation Test Plan Workflow will be assigned to the synapseRT workflow scheme automatically.

Using Subtests in place of Test Cases

If the feature to use Subtests instead of Test Cases in Test Plans is enabled on Dashboard configuration page, then Test Cases assigning process start a job that creates Subtests for the given Test Cases and assign them instead of Test Cases. Subtests inherit the custom fields values of the Test Cases. Only Test Case state custom field value always is In progress and Summary field contains summaries of the Test Plan and the Test Case connected by ":" sign e.g. "TP summary : TC summary". After Test Plan created you will see the job progress information in Test Case custom field and on the Test Plan tab of the issue.

It is possible to cancel the operation using the Cancel Operation button on the Test Plan tab. Current job also will be aborted when the Test Plan is updated during progress. If operation aborted, all created Subtests will be deleted silently.

When the operation completes execution, Test Case field of the Test Plan displays Subtests and their parents in the same way as it does for Test Cases. Test Plan tab displays the keys of parent Test Cases in the Parent column for Subtests children only not for children Test Cases.

The test case also displays information about SubTests.

Filtering Requirements and Test Cases

For project with a large number of requirements and test cases, a use to filter to narrow down your requirements and test cases and find them easily.

Defects

A defect can be created directly from a test case. Simply click on the More Actions link found in Issue Operations section within the requirement and select "Create Bug".

Please note: the "Create Bug" option is disabled on the Test Case page when the feature to use Subtests in place of Test Cases in Test Plans is enabled on synapseRT Dashboard Configuration page.

Fill in a summary for the Defect and update other fields as necessary

Please note - The Defect issue type is a custom issue type, created during the installation process.

Please note - Since the Defect was created within a specific Test Case, the corresponding Test Case and associated Requirements are already selected.

After the Defect has been created, we can now see the Test Cases and Requirements populated within the Defect, as shown on the image below

AJAX

Searching for requirements and parent requirements using issue search

PENDING

Plugin interface

From Go2Group synapseRT v3.0 plugin has AJAX based interface namely custom fields (Requirement, Parent Requirement, Test Case), issue panels and synapseRT dashboards. This is specially helpful when working with projects which have a large amount of issues (over 10k).

AJAX custom fields
- Tree view field loads data only for current level of tree. When user click "+", the data for opened tree level is loaded dynamically.
- Raw view custom fields have "More..." button to load the next portion of data.
Issue panels collect data by small portions too. They have "More..." button to load data dynamically from server.
Dashboards.
- Traceability dashboard has tree view based traceability table. So data is loaded dynamically after pressing "+" sign.
- Release Planning dashboard load user preferred amount of issues.
- The issue limits for dashboards can be configured in SYNAPSE Dashboard configuration section in JIRA Administration.
- More information about AJAX Dashboards is available in Dashboard section.

Dashboards

Traceability Dashboard

To access Traceability Dashboard, click the synapseRT drop down in the JIRA navigation bar and select Traceability. The Traceability Dashboard provides review traceability metrics. It includes Search filters block, Traceability table and Defects (Bugs) area.

SynapseRT provides many simple search panel where you can filter your issue results. You can also choose to search using your saved JIRA filters.

The Search Panel is hidden by default. Click on the "Minimize/Maximize" option on the right side of the Search Panel to Show/Hide the panel. You can also choose to hide the panel here.

Traceability table

The Requirements and Test Cases which meet search conditions are displayed in the Traceability table. Requirements are listed vertically on the left, with Test Cases listed horizontally across the top (you can transpose this table using Transposition button as shown on image below). Each intersection table cell displays bug statuses and summaries and a border around. The border has color that represents the "worst" state between the states of corresponding Test Case and Requirement. Traceability table is AJAX based, see more in the AJAX section.

The number of the issues to be displayed is configured in the Dashboard section of synapseRT configuration. The rest of issues are available on the mini pages.

There are two modes of the table: Line view and Tree view.

Line table has all requirements displayed with indents on the left. The number of requirements to be displayed is configured in the Dashboard section of synapseRT configuration. The rest of issues are available on a mini pages.

Tree table displays tree view of requirements. The number of issues to be displayed in search result before user expanded/closed tree levels is also configured in synapseRT configuration. The rest of issues are available on mini pages. You can expand/close tree levels using "+" and "-" buttons.

Each issue item in the table has several buttons and fields. See image below.

Tree button appears only in the tree mode.
Defects (Bugs) button shows the bugs which are assigned to the issue.
Edit issue button opens the issue edit page.
Issue info displays the popup with short information about many issue parameters such as a Status, Assignee, Components, etc.
Summary field contains issue summary.
Issue key field is a link to view issue in new window.

Issue information popup contains short information about many issue parameters such as Assignee, the number of Defects, Time Spent etc.

Issue bugs are shown below Traceability table after pressing Bugs button.

Release Planning

Let us take a look at the Requirement and Test Case Planning tabs (Planning Dashboards) of the synapseRT dashboard.

The Planning Dashboard allows users to operate issue parameters during interactive actions with drag and drop functionality. It includes Search panel, Issues section (Test Cases in Test Case Planning dashboard and Requirements in Requirement Planning dashboard) and Cork board.

The search filters are similar to the Traceability Search filter except for the addition of the "Order" search parameter. It allows your to order your search results based on Priority, Status, Test Case State and Test Suite.

Issues section

Issues section contains Issue items organized in columns or rows according to their Status, Priority etc. Column view is default for this Dashboard, you can Change View using corresponding link. The number of issues to be displayed on the page is defined in the Dashboard section of the synapseRT configuration. The rest of issues are available on the Pages.

Drag and drop functionality provides simple change Issue parameters as you can see below where Priority change process illustrated.

Issue item contains Context menu, Issue info and Move to buttons, see more information below. It also includes issue key and summary information.

Context menu displays the link to View and Edit an issue.

Issue info button allows you to see short information about many issue parameters such as Assignee, Time Spent, the number of defects, etc.

Move to button allows you to move an issue without drag and drop. Just choose new value of the issue parameter in the menu and issue will be moved in corresponding column/row. Additionally, Move to menu displays information about number issues with different Test Case states in row/columns on the current page.

If you want to see information about number issues with different Test Case states in row/columns on the other pages you can see it in a popup over pages.

Cork board

Please note: corks are assigned to project releases in Release filter. So to view/add the Cork for the Release choose this Release and press Query button.

The images below show the Cork Board in the synapseRT Requirement/Test Case Planning dashboard.

You can create a Cork.

And Edit this Cork without reloading page.

After you save the Cork you can see your changes without reloading page.

Requirements Summary

Requirements summary dashboard provides export to XML functionality for Requirements keys and summaries. Open this dashboard using "Requirements Summary" in the synapseRT drop down menu.

Choose a Project and press Query button in order to load Requirements tree. Use the XML... link to export Requirements tree to XML.

API

SynapseRT plugin provides an API to change the State of Test Cases (Subtests) of the given Test Plan. It allows to operate with plugin's servlet by GET requests using usual Jira REST API authentification.

The request structure is

JIRA_BASE_URL/plugins/servlet/changeStateTCByTPServlet
	?testPlanKey=TEST_PLAN_KEY
	&TEST_CASE_KEY=STATE
	&TEST_CASE_KEY=STATE
	&TEST_CASE_KEY=STATE...

For example

http://localhost:8080/jira/plugins/servlet/changeStateTCByTPServlet
        ?testPlanKey=SYNAPSE-132
        &SYNAPSE-13=In%20Progress
        &SYNAPSE-14=Failed

Note: If Subtasks feature is enabled, then the plugin will search for Subtests of the given Test Cases and change State for them.

Response is XML-formatted and is described below.

CASE: Empty test Plan key
RESPONSE: 400
<root>
    <error type="wrongtp">Test Plan key is empty</error>
</root>

CASE: Test Plan does not exist
RESPONSE: 404
<root>
    <error type="notp">Test Plan does not exist</error>
</root>

CASE: No permission
RESPONSE: 403
<root>
    <error type="noperm">No permission</error>
</root>

CASE: Valid request
RESPONSE: 200
<root>
    <success type="DS-3237">Passed</success>
    <success type="DS-3243">Failed</success>
    <success type="**TC Key**">**New TC State**</success>
</root>

Client App Example

In this section we will write simple App that will connect to the synapseRT servlet and change Test Case States.
We need username and password for authentification:

CODE

private static String username = "admin";
private static String password = "1";

Then we generate authentificate token and define access point:

CODE

public static void main(String[] args){
	String auth = new String(Base64.encode(username + ":" + password));
	String endPoint = "http://localhost:8080/jira/plugins/servlet/changeStateTCByTPServlet?" +
				"testPlanKey=SYNAPSE-132" +
				"&SYNAPSE-13=In%20Progress" +
				"&SYNAPSE-14=Failed";
}

Now write a simple method to perform GET request:

CODE

private static String makeGetRequest(String endPoint, String auth) throws Exception{
	Client client = Client.create();
	WebResource webResource = client.resource(endPoint);
	ClientResponse response = webResource.header("Authorization", "Basic " + auth).type("application/json")
				.accept("application/json").get(ClientResponse.class);
	System.out.println(response.getEntity(String.class));

Parsing request for errors and making result:

CODE

	if(response != null){
		if(response.getStatus() == 200)
			return response.getEntity(String.class);
		else if(response.getStatus() == 401)
			throw new AuthenticationException("Invalid username/password");
		else if(response.getStatus() == 403)
			throw new Exception("Operation forbidden");
		else
			throw new Exception("Error " + response.getStatus());
	}else
		return null;

Finally we have this class:

CODE

package com.test.app;

import org.apache.commons.httpclient.auth.AuthenticationException;

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.core.util.Base64;

public class APIClient {
	private static String username = "admin"; //Jira user name
	private static String password = "1";// Jira user password
	public static void main(String[] args){
		String auth = new String(Base64.encode(username + ":" + password)); //creating security token for authentification
		String endPoint = "http://localhost:8080/jira/plugins/servlet/changeStateTCByTPServlet?" +
				"testPlanKey=SYNAPSE-132" +
				"&SYNAPSE-13=In%20Progress" +
				"&SYNAPSE-14=Failed"; //GET request body NOTE: URL-encoded space in "In Progress" State
		String result = "";//This string will be displayed in console
		try {
			result = makeGetRequest(endPoint, auth);//It is OK
		} catch (Exception e) {
			result = e.getMessage();//Something wrong :(
		}
		System.out.println(result);
	}

	private static String makeGetRequest(String endPoint, String auth) throws Exception{
		Client client = Client.create();
	    WebResource webResource = client.resource(endPoint);
	    ClientResponse response = webResource.header("Authorization", "Basic " + auth).type("application/json")
	                .accept("application/json").get(ClientResponse.class);//Set header for authentification
	    if(response != null){
	    	if(response.getStatus() == 200)//Request OK
	    		return response.getEntity(String.class);
	    	else if(response.getStatus() == 401)//Unauthorized
	    		throw new AuthenticationException("Invalid username/password");
	    	else if(response.getStatus() == 403)//Request forbidden
	    		throw new Exception("Operation forbidden");
	    	else //Something else happened
	    		throw new Exception("Error " + response.getStatus());
	    }else
	    	return null;
	}
}

Runnig App we can see result in console:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success type="SYNAPSE-133">In Progress</success>
  <success type="SYNAPSE-134">Failed</success>
</root>