System overview

The QualitySpy system consists of two applications: qualityspy-server and qualityspy-acquisition. Both are made of several modules rendered in the source code as maven modules. Both works with the very same data base - MySQL or MariaDB are recommended, however, every relational database should be good enough.

The qualityspy-server is a web application (war) and as such must be deployed into an application container, the Apache Tomcat is recommended. The qualityspy-acquisition is a desktop application.

Integration of Acquisition GUI

QualitySpy project is developed in pursuance of the principle of separating GUI from business logic:

• requests are created in front-end but executed in back-end
• progress bar status is updated from back-end.
• cancel button performs asynchronous call from front-end to back-end

Web application

QualitySpy provides REST endpoints via qualityspy-webapp module located in apps package. QualitySpy-webapp can be run as standalone application, but as whole project it requires connection with database. 

This module is created using SpringBoot v.1.5.2 and designed to build as jar file. Seed for this application was generated with Spring Initializr - https://start.spring.io/ with all necessary dependencies including:

• Embedded Tomcat web serwer
• MySQL database connector
• HSQLDB used mainly for testing 
• Actuator for monitoring and managing application

and more that you can find in pom.xml.

Main functionality of qualityspy-webapp is providing REST endpoints which are simple interface for reading database content. Endpoints are provided by 12 classes located in qualityspy.webapp.rest package. Their methods and classes names are fully describing their purpose and behavior. New classes should be also placed in rest package and have suffix "RestService". All classes that are defining REST are registered in "JerseyConfig". 

The fastest way of trying out REST endpoints responses is by using embedded Swagger UI which is available after running app http://localhost:10080/swagger/index.html. Keep in mind that "/api" is placed before all REST endpoints.

Application properties like ports configuration or database connection credentials are located in "application.properties" file in resources directory:

. 

Resources also contains static folder where all Swagger UI and bootstrap files are located. In templates you can find index.html page template. 

Running application

While working with modern Java IDE for example InteliJ IDE it should automatically recognize Spring Boot application and configure it for you, if not check your configuration it should look like this:

Make sure that your main class is set up for pl.wroc.pwr.qualityspy.webapp.QualityspyWebappApplication and classpath of module is set for qualityspy-webapp.

Tests

Web application integration tests are located in test package. It's important to remember that for testing purpose is used different database than default MySQL. Test data is provided by in memory database HSQLDB. It's configuration can be found in tests → java → resources → application.properties. In test resources you can also find dbunit.xml this file describes test data set.

Naming conventions and code formatting

The source code should be formatted according to default settings of the last version of IntelliJ IDEA.

Data Access Objects classes are located in seperated package named qualityspy-dao.

This article describes how to configure IntelliJ enviroment to launch QualitySpy.

To start with, clone source codes from git repository. Link to git repository:

https://bitbucket.org/opendce/qualityspy.git

Open IntelliJ and on starting page choose highlighted option.

Copy link to git repository and paste it. Then specify directory. After pressing clone wait a while, source files will begin to download.

After that create project for sources you just downloaded.

On next window select Maven model. 

Then press next until you will be asked to choose project SDK. You should select jdk 1.8. 

When project files will properly load you have to add project build configuration.

Then specify Main class, working directory and classpath of module as following:

Now your build configuration is finished. If you already had set up database you can build project. If you didn't go here to see how to do that.

Testing

Unit tests

JUnit tests are the simple and fast tests that use mocks to check simple, single functionality. You should write JUnit to check every function that you use in your code. JUnit must be fast, it should be matters of seconds to run that test.

Naming param is <className>Test.java

Integration tests

Integration tests are here to check whenever the functions that you use in code work well together. Those tests may take longer to run. In maven they are run in integration-test phase.

Naming param is <className>IT.java, or <className>IntegrationTest.java.

Acceptance tests

Acceptance testing is a testing technique performed to determine whether or not the software system has met the requirement specifications. The main purpose of this test is to evaluate the system's compliance with the business requirements and verify if it is has met the required criteria for delivery to end users.

There are various forms of acceptance testing: User Acceptance Testing, Business Acceptance Testing, Alpha Testing, Beta Testing.

Naming param is AcceptanceTest<className>.java.

Cucumber

Cucumber is a software tool used by computer programmers for testing other software. It runs automated acceptance tests written in a behavior-driven development (BDD) style. Central to the Cucumber BDD approach is its plain language parser called Gherkin. It allows expected software behaviors to be specified in a logical language that customers can understand. As such, Cucumber allows the execution of feature documentation written in business-facing text.

Testing with Cucumber

To start working with Cucumber we have to add following dependencies to project:

<dependency>
    <groupId>info.cukes</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>1.2.5</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>info.cukes</groupId>
    <artifactId>cucumber-junit</artifactId>
    <version>1.2.5</version>
    <scope>test</scope>
</dependency>

To make a executable test you have to prepare 3 files: Feature description, Steps definition and Runner file.

Feature file should be located in resources directory, i.e. (...)/<moduleName>/src/test/resources/cucumber/<FeatureFileName>.feature

It is preferred that Steps definitions file is located in following directory (...)/<moduleName>/src/test/java/steps/<StepsFileName>.java

Runner file like all tests should be located in (...)/<moduleName>/src/test/java/AcceptanceTest<TestedClassName>.java

Feature

A feature is a Use Case that describes a specific function of the software being tested. There are three parts to a Feature

    The Feature: keyword

    The Feature name (on the same line as the keyword)

    An optional description on the following lines

Example Feature definition

Feature: Withdraw Money from ATM
    A user with an account at a bank would like to withdraw money from an ATM.
    Provided he has a valid account and debit or credit card, he should be allowed to make the transaction. The ATM will tend the requested amount of money, return his card, and subtract amount of the withdrawal from the user's account.

    Scenario: Scenario 1
        Given preconditions
        When actions
        Then results

    Scenario: Scenario 2
        ...

Steps Definitions

It is a file which contains steps definitions. It contains source code which should be done within a test step. Parameters defined in feature files are passed to step definitions with regular expressions. To make them work correctly, you should configure methods for each step defined in Feature file. Each step is preceded by an annotation connected to step keywords defined in feature file (e.g. @Then, @When etc.).
Example step definition:

@Given("I have a cucumber step")
public void i_have_a_cucumber_step() throws Throwable {
    System.out.println("Step definition exact match");

Runner file

In Runner file you have to set all options about tests, like which features are tested or where steps are located. There's few more options to configure but they are optional, the main thing of this file is that he making our test code working.

Required options are:

• format - It describes how cucumber will format test case output and if it create reports.
• glue - It contains path to package containing Step definition files
• features - It contains path to feature file.

Example runner:

package pl.wroc.pwr.qualityspy.vc;

import cucumber.api.CucumberOptions;
import cucumber.api.junit.Cucumber;
import org.junit.runner.RunWith;

@RunWith(Cucumber.class)
@CucumberOptions(
        monochrome = true,
        format = { "pretty", "html:target/cucumber" },
        glue = "pl.wroc.pwr.qualityspy.vc.steps",
        features = "classpath:cucumber/Repository.feature"
)
public class AcceptanceTestRepositoryCucumber {
}

To run our test all we have to do is just run our test
 

If everything was configured correct, we should got message about completed tests.

After completed tests Cucumber automatically generate report file, where you can check what was tested, or if something went wrong where was the problem. Report file is generated as file (...)/<moduleName>/target/cucumber/index.html.