Introduction

QualitSpy is a framework for monitoring software development process. Failing to deliver requested feature on eligible schedule and quality may cause serious loss (e.g. financial). Therefore, it is important to keep an eye on the work progress and early identify problems. There are a number of tools employed in most of the software development environment. We believe that these tools are reliable source of metrics that can be used to evaluate project’s current state and predict about the further development. The QualitSpy framework is designed to integrate with the issue tracking system, the version control system, the continuous integration system and the source code itself by collecting raw data as well as software metrics. The collected data is used for research (empirical experimentation, estimation/prediction model creation) and for project evaluation.

Detailed information regarding project concept can be found in an article published in Journal of Theoretical and Applied Computer Science: http://staff.iiar.pwr.wroc.pl/marian.jureczko/QualitySpy.pdf

QualitySpy First Steps

Starting QualitySpy (released version)

To start the application you need:

• Jre 1.8+ (https://java.com/en/download/)
• MySQL 5.1.17+

When the prerequisites is fulfilled do the following:

1. Download the latest qualityspy-acquisition-*-run.zip package from Download section
2. > unzip qualityspy-acquisition-*-run.zip
3. > cd qualityspy-acquisition-*-run
4. > ./start.sh

(where * is version)

Configuring database

For the correct operation of the tool database is needed. Before first use it is important to create one with name, user and password. In application there is a configuration menu, in which we can then type those credentials. To configure database (assuming you have mysql) you need to type those commands:

 mysql -u root -p

 Enter password: Password_that_you_typed_while_installation

 mysql> CREATE DATABASE qs_dev;

 mysql> USE mysql;

 mysql> CREATE USER 'qs'@'localhost' IDENTIFIED BY 'qspass';

 mysql> GRANT ALL PRIVILEGES ON qs_dev.* to 'qs'@'localhost';

 mysql> FLUSH PRIVILEGES;

 mysql> EXIT;

Configuration with those creates:

* Database: qs_dev

* User: qs

* Password: qspass

Settings for database in application can be found here:

Below you can see how the data is typed to connect correctly:

Starting QualitySpy snapshot version

To build and start the project you need:

• Git client
• Jdk 1.8+ (http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
• Maven 3+ (http://maven.apache.org/)
• MySQL 5.1.17+

When the prerequisites are fulfilled do the following:

1. > git clone git@bitbucket.org:MarianJureczko/qualityspy.git
2. > mvn clean install
3. > cd apps/qualityspy-acquisition/target/
4. > unzip qualityspy-acquisition-*-run.zip
5. > cd qualityspy-acquisition-*-run
6. > ./start.sh

(where * is version)

Features and configuration

Before using QualitySpy tool, a proper configuration for each of QualitySpy's services (external tools/services which will be used with QualitySpy) needs to be provided. In order to do that there is a Configuation tab with 4 subtabs: CKJM, Repository, JIRA and CI:

In this section all configuration steps will be described in details. Each of the subsections describes all setting's fields in a particular Configuration's tabs. All described settings in that section refer to QualitySpy desktop application.

CKJM - Product metrics

Can be executed using Fetch → Metrics (ckjm). It collects metrics from Java code using CKJM extended. More inforomation about CKJM extended - http://gromit.iiar.pwr.wroc.pl/p_inf/ckjm/. The metrics can be calculated from jar or from class file. For the sake of metrics calculation correctness all dependencies of investigated Java code must be provided. They may be given explicit or using Apache Maven (for projects developed with Apache Maven, i.e. having pom.xml file)

Parameter	Despcription	Sample Data	Required
ckjmSourceType	Type of the input artifact. Ckjm will be used to calculate metrics for this artifact	JAR/CLASS
ckjmJar	Name with path (can be relative) of the jar file to analyse. It is used only when the CkjmSourceType is set to JAR	src/test/resources/catalina.jar
ckjmClass	Path to the directory that contains classes to analyse (without package directories). It is used only when the CkjmSourceType is set to CLASS	src/test/resources/catalina.class
ckjmLibrariesSeparator	The character that is used to separate libraries on the property CkjmLibraries. If is not set, the default path separator	':' on Linux, ';' on Windows
ckjmLibraries	List of libraries (jar files) that are necessary to calculate metrics. A jar archive is necessary to calculate the metrics when at least one of the measured classes refers to a class that is in the jar archive	src/test/resources/lib_Tomcat/servlet-4.0.6.jar; src/test/resources/lib_Tomcat/commons-modeler-1.1.jar; src/test/resources/lib_Tomcat/tomcat-util-5.5.7.jar
ckjmMavenProjectDirectory	Path to Maven project directory. Should contains pom.xml file	module/core/maven/main
ckjmMavenHome	Instalation directory, needed for resolving dependencies using maven
ckjmJavaHome	Instalation directory, needed for resolving dependencies using maven
addTestHome	TO REMOVE?

Repository

QualitySpy can collect data from two different version control systems, i.e. Subversion and git. One of them must be selected in the configuration. Some of the parameters are relevant only for one of them.

*Git accepts various date formats (+0200 signifies timezone):

• rfc2822: Mon, 3 Jul 2006 17:18:43 +0200
• iso8601: 2006-07-03 17:18:43 +0200
• local: Mon Jul 3 15:18:43 2006
• short: 2006-07-03 (not in 1.9.1, works in 2.3.0)
• default: Mon Jul 3 17:18:43 2006 +0200
• relative: e.g. "yesterday", "today", "5 minutes ago", "1 month 2 days ago",
"six minutes ago", "last Tuesday", "3PM GMT" etc. 

(For full explanation of dates in git visit this page or the stackoverflow issue here.)

Issue Tracker

QualitySpy can collect data from two different issue trackers, i.e. JIRA and GitHub's Issues. One of them must be selected in the configuration. Some of the parameters are relevant only for one of them, e.g. only JIRA supports JQL strings.

JIRA & GitHub issue trackers settings

Field	Field Type	GitHub Support	JIRA Support	Description	Sample Data	Default	Required
Bugtracker	Connection Info			Name of the issue tracking tool	"jira" or "github"
trackerUrl	Connection Info			URL address of the JIRA system. Required if Bugtracker is setted to "jira"	https://jira.attlasian.com
Login	Connection Info			Login to the JIRA or GitHub system	user123
Password	Connection Info			Password for JIRA or GitHub user	pwd123
Timeout	Connection Info			Timeout given in ms after which application should abort trying to establish connection.	5000	60000
jiraJQLString	Filter			JQL query which is a filter for searching issues in JIRA	project = crucible and fixVersion = 3.0.2
githubIssueRepo	Connection Info			GitHub repository name	octobox
githubOwner	Connection Info			Username of the GitHub repository owner	andrew
state	Filter			State of the issues which should be contained in the search results.	"open" / "closed" / "all"	"open"
Title	Filter			Issue title on GitHub	"Add Development doc"
number	Filter			Issue number on GitHub, preceded by "#" sign	#123
Reporter	Filter			Username of the user who created an issue on GitHub	arthurnn
assignee	Filter			Username of the user who is assigned to an issue on GitHub	"user123" / "none" / "*"	"*"
labels	Filter			Allows filtering issues by label(s) which identifies issues on GitHub	"bug" (any label which occurs on specified GitHub)
CreatedAt	Filter			Search for issues which was created on specified time or later. Time should be given in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ	2017-01-13T20:15:30Z
UpdatedAt	Filter			Search for issues which was updated on specified time or later. Time should be given in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ	2017-01-13T20:15:30Z
mentioned	Filter			Search for issues in which given user was mentioned	arthurnn

CI (Continuous integration)

QualitySpy can collect data from two different continuous integration systems, i.e. Jenkins and Hudson. One of them must be selected in the configuration.

Parameter	Description	Sample Data	Required
CI server type	Name of continuous integration server used	Hudson/Jenkins
CI server URL	URL address of CI server	http://snow.iiar.pwr.wroc.pl:8082
CI server login	User login for CI server	jan007
CI server password	User password for CI server	1q2w3e4R
CI job name	Job name for CI server	QualitySpy

Browse through collected data

One of the most important activities in QualitySpy project is to fetch the data collected so far. To retrieve the data - press "Fetch X" button, where X would be replaced with one of the following:

• SVN/GIT (Version Control/Repository)
• CKJM (Metrics)
• JIRA (Issue Tracker)
• CI (Continuous Integration)

After this operation, collected data will contain informations about the project chosen by us. In order to present the collected data in a transparent way, the output would always be organized as follows:

• on the left side there are some entries with the particular attributes of the project
• on the right side there are values of these attributes

The collected data output might cover:

• ProjectHistories - these entries are connected with particular versions of project
• Job - CI's system (e.g. Jenkins) jobs alongside with their details and build made by that particular job.
• Revisions - version control system (e.g. GIT/SVN) entries
• Classes - Java code metrics values
• Issue - issues entries obtained from issue tracking system along with their details, for example:
  
  

Every single issue consists of several directories. These directories are issue description, issue change, issue comments and issue logs. Directory has its own attributes. For example: issue description has "summary" attribute which containts information about this issue. Another one attribute called issue key (e.g. CRUC-6555) is an ID of the issue.

Web application

To start web application you need:

• Git client (https://git-scm.com/downloads)
• Jre 1.8+ (http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html)
• Jdk 1.8+ (http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
• Maven 3+ (http://maven.apache.org/)
• MySQL 5.1.17+

Then you should do the following:

• Clone a project with git from https://bitbucket.org/opendce/qualityspy.git
• Execute command: mvn clean install (or mvn clean install -DskipTests if you want to skip tests)
• Run MySQL (e.g. using Xampp)
• Find a jar file (\apps\qualityspy-webapp\target) and run qualityspy-webapp from command line (java -jar qualityspy-webapp-0.5-SNAPSHOT.jar) 
• You can access your application from: http://localhost:10080
• Web application has Actuator endpoints that allow you to monitor application, those endpoints are available on http://localhost:8081. For more details check out Actuator documentation.
• In a web browser you can see a start page of web application:
  
  
  
  

Web application has only one functionality: when you click Swagger UI, you can see a list of available REST endpoints:

Using QualitySpy to moving project to new Jira instance

The first step is to run QualitySpy application and fetch choosen project. Below is the instruction how to create a new project, configure IssueTracker and collect data.

1. Select from main menu "Project" → "New" or click icon "Create new project", type name of the project, version and then click "Ok".

2. Necessary fields are: bugtracker and trackerUrl. Set bugtracker field to "jira" and trackerUrl to your address for Jira system (e.g. https://jira.atlassian.com/). If your repository is protected you need to enter login and password. 

3. You can also set more options:

• timeout - given in miliseconds after which application should abort trying to establish connection
• jiraJQLString - query which is a filter for searching issues in Jira (e.g. "project=NameOfProject" will import project named "NameOfProject") 

4. Next choose your project version, select "Fetch" from menu and click Issue Tracker option. After collecting data you should see information "Collected!" in message box. Click "OK".

5. Run web application (link), open your web browser and type in the address field: http://localhost:10080/swagger/index.html

6. Find projects section and click "get" button. Click "Try it out"  button. 

7. Next execute it by clicking button.

8. You should receive list of collected projects. Remember number that is in projectHistories tags.

9. Find and click "/jiraexport/projecthistory/{projectHistoryId}" section. Select "text/csv" from "Response content type" list. Next press "Try it out" button and type number from projectHistories tag into projectHistoryId input. Click "Execute" button.

10. Copy data from "Response body" to any text editor and save it with.csv extension.

11. Importing .csv file to Jira server is described on official website: https://confluence.atlassian.com/adminjiraserver071/importing-data-from-csv-802592885.html.