Quick Start Guide

Itai Agmon edited this page Mar 28, 2018 · 6 revisions
Clone this wiki locally

Quick Start Guide

In this example we will create a simple JSystem project to verify existence of files.

Preconditions

Java JDK

JSystem is a pure Java framework and it needs Oracle’s JVM to run. To create and compile tests, the Java compiler and tools that are part of the JDK package are also required. If Java is not already installed on your machine, download and install Java 1.7 from Oracle’s site. After you have installed Java 1.7, you need to set the JAVA_HOME environment variable to point to the JRE installation directory and update your path environment variable.

Maven

Apache Maven is a software project management and comprehension tool. JSystem’s projects follow the Maven conventions and it will be used for building our projects. If Maven is not already installed on your machine download it, extract it and add the bin folder to your path environment variable. If you want to make sure that it is installed correctly, open your operating system console and type

> mvn -version

You should see something like

Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T18:41:47+02:00)
Maven home: C:\Program Files (x86)\apache-maven-3.0.4\bin\..
Java version: 1.8.0_31, vendor: Oracle Corporation
Java home: C:\Program Files\Java\jdk1.8.0_31\jre
Default locale: en_US, platform encoding: Cp1255
OS name: "windows 7", version: "6.1", arch: "amd64", family: "dos"

Reference: More instructions on installing Maven can be found in this link

JSystem

Go to the downloads page and install the latest stable JSystem version. Generate a test project

Tests Project

Top-Q Maven repository holds an archetype catalog which describes different projects archetypes that can be generated.

Generating Tests Project

We will start by generating a new JSystem Tests project. Open your operating system console, change directory to the folder that you would like to create the project in, and type the following command

> mvn archetype:generate -DarchetypeCatalog=http://maven.top-q.co.il/content/groups/public/archetype-catalog.xml

NOTICE: If you are using Maven 3, the archetypeCatalog property is no longer supported. You will need to set the catalog URL in Maven's settings file or to force Maven to use an older version of the maven-archetype-plugin

> mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=http://maven.top-q.co.il/content/groups/public/archetype-catalog.xml

You will be asked to select the archetype to use.

Choose archetype:
1: http://maven.top-q.co.il/content/groups/public/archetype-catalog.xml -> org.jsystemtest.archetypes:jsystem-tests-archetype (-)
2: http://maven.top-q.co.il/content/groups/public/archetype-catalog.xml -> org.jsystemtest.archetypes:jsystem-so-archetype (-)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

To generate from tests project archetype, select 1. In the following steps, you will be asked to select the JSystem version to be used.

Choose org.jsystemtest.archetypes:jsystem-tests-archetype version:
1: 6.0.01
2: 6.0.02-SNAPSHOT
3: 6.0.02
4: 6.0.03-SNAPSHOT
5: 6.1.00-SNAPSHOT
6: 6.1.00
7: 6.1.01-SNAPSHOT
8: 6.1.01
9: 6.1.02-SNAPSHOT
10: 6.1.02
11: 6.1.03-SNAPSHOT
12: 6.1.03
13: 6.1.04-SNAPSHOT
14: 6.1.04
15: 6.1.05-SNAPSHOT

Select the latest stable version. In this case we will select 14. In the following step, you will be asked to define the project group Id, artifact Id, version and package.

Define value for property ‘groupId’: : org.jsystem
Define value for property ‘artifactId’: : my-tests-proj
Define value for property ‘version’: 1.0-SNAPSHOT: :
Define value for property ‘package’: org.jsystem: :
Confirm properties configuration:
groupId: org.jsystem
artifactId: my-tests-proj
version: 1.0-SNAPSHOT
package: org.jsystem
Y: : Y

In this example, we will use org.jsystem as the groupId and my-tests-proj as an artifactId. You can leave the default values for the version and package. If everything has gone smoothly, you should get a BUILD SUCCESS message and a project with the following structure would be generated.

└───my-tests-proj
    └───src
        └───main
            ├───assembly
            ├───java
            │   └───org
            │       └───jsystem
            └───resources
                ├───scenarios
                └───sut

Creating your first test

You can import the project as a Maven project to your favorite IDE or edit the source files using any text editor.

In the folder my-tests-proj/src/main/java/org/jsystem, create a new Java class file with the name FileOperations.java. Edit the file and paste the following content.

package org.jsystem;

import java.io.File;

import org.junit.Assert;
import org.junit.Test;

import junit.framework.SystemTestCase4;

public class FileOperations extends SystemTestCase4 {

	@Test
	public void verifyFileExistence(){
		File file = new File("pom.xml");
		Assert.assertTrue(file.exists());
	}

}

JSystem tests are very much like regular JUnit tests. The main difference is that JSystem tests classes must extend the SystemTestCase4 class in order to enjoy the various JSystem services.

The Junit @Test annotation is used to signal JSystem about test methods. To learn more about JUnit visit the JUnit site. If you are using any popular Java IDE to create the example, you can already execute the test as a JUnit test

Adding parameters to tests

JSystem allows us to define parameters for each test. This allow us to create single tests that can be used for testing various conditions. Each test parameter is a member in our class that has a getter and a setter method.

package org.jsystem;

import java.io.File;

import org.junit.Assert;
import org.junit.Test;

import junit.framework.SystemTestCase4;

public class FileOperations extends SystemTestCase4 {

	private String fileName;

	@Test
	public void verifyFileExistence() {
		File file = new File(fileName);
		Assert.assertTrue(file.exists());
	}

	public String getFileName() {
		return fileName;
	}

	public void setFileName(String fileName) {
		this.fileName = fileName;
	}

}

Note: It is very common to forget to add setters and getters method to parameters. Remember this if you can’t see the parameters from the runner.

However, this is enough for exposing parameters to the tests, if we will have more than one test in our class, each test will expose the same parameters as the test we have just created. To associate the test method with a subset of parameters, we will use the JSystem's @TestProperties annotation which has a string array that is used to specify all the associated parameters.

	@Test
	@TestProperties(paramsInclude = { "fileName" })
	public void verifyFileExistence() {
		File file = new File(fileName);
		Assert.assertTrue(file.exists());
	}

Building the project

If you are using any popular IDE like Eclipse or Intellij, and the IDE is configured to perform automatic build, you can skip this step. Before executing our tests we will need to compile the project. Open your operating system console, change directory to the project root folder and type the following command

> mvn clean compile

This will use Maven to compile the Java sources in the project target directory.

Executing The tests

We now met the minimum requirements for executing JSystem tests. Change directory to the runner folder and launch JSystem by clicking on the run.bat batch file or the run shell script according to your operating system. First, we will need to switch to our newly created project. From JSystem, Select File->Switch Project

In the file chooser dialog, select the project we have just created.

When JSystem finishes loading the project, the right side pane will display all the tests in the project. You can now select the test we have implemented and use the yellow arrow button for adding the test to the scenario

On the left pane, double click on the test to open the Test Info pane. In this pane you will be able to see the test parameter we have defined earlier.

Set the value for the parameter. Since the test is looking for a file in the current directory, we will select a file that we know exists in the runner root folder.

The scenario is ready. Click on the play button to execute the test.

JSystem reporter tab shows the current execution reports. To see additional information, click on the report button

An HTML report would be opened on your default operating system browser.

Get more descriptive

Let’s get back to our test code and add some descriptive data.

Test name

By default, JSystem uses the class and method name for describing the tests. To use a more descriptive name for the test we will use the name field of the @TestProperties annotation

	@Test
	@TestProperties(name = "Verify that file ${fileName} exists", paramsInclude = { "fileName" })
	public void verifyFileExistence() {
		File file = new File(fileName);
		Assert.assertTrue(file.exists());
	}

Note that we can also use the test parameters as part of the test name.

Test description

It is important to describe to users what our test does exactly . JSystem displays the standard javadoc of the method in the Test Info tab.

	/**
	 * Verifies that the specified file exists in the current folder
	 */
	@Test
	@TestProperties(name = "Verify that file ${fileName} exists", paramsInclude = { "fileName" })
	public void verifyFileExistence() {
		File file = new File(fileName);
		Assert.assertTrue(file.exists());
	}

Parameter description

To add description to the test parameters, add JSystem @ParameterProperties annotation to the parameter setter method. Use the description field for the parameter description.

	@ParameterProperties(description = "Expected file name")
	public void setFileName(String fileName) {
		this.fileName = fileName;
	}

To see all the awesome changes you have made, recompile your project using Maven or your IDE, switch to the runner and click on the refresh button.

System Object Project

JSystem enables the user to adjust the automation changes via a modulated system referred to as system objects (SystemObjects), These SystemObjects communicates directly with the business logic of the product. JSystem has the ability to connect directly to the application API enabling low maintenance migration.

Generating System Objects project

Open your operating system console, change directory to the folder in which you would like to create the project, and type the following command

> mvn archetype:generate -DarchetypeCatalog=http://maven.top-q.co.il/content/groups/public/archetype-catalog.xml

You will be asked to select the archetype to use.

Choose archetype:
1: http://maven.top-q.co.il/content/groups/public/archetype-catalog.xml -> org.jsystemtest.archetypes:jsystem-tests-archetype (-)
2: http://maven.top-q.co.il/content/groups/public/archetype-catalog.xml -> org.jsystemtest.archetypes:jsystem-so-archetype (-)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): :

To generate from System Objects project archetype, select 2.

In the following steps, you will be asked to select the JSystem version to be used.

Choose org.jsystemtest.archetypes:jsystem-tests-archetype version:
1: 6.0.01
2: 6.0.02-SNAPSHOT
3: 6.0.02
4: 6.0.03-SNAPSHOT
5: 6.1.00-SNAPSHOT
6: 6.1.00
7: 6.1.01-SNAPSHOT
8: 6.1.01
9: 6.1.02-SNAPSHOT
10: 6.1.02
11: 6.1.03-SNAPSHOT
12: 6.1.03
13: 6.1.04-SNAPSHOT
14: 6.1.04
15: 6.1.05-SNAPSHOT

Select the latest stable version ,(which does not include SNAPSHOT in the name). In this case we will select 14.

In the following step, you will be asked to define group Id, artifact Id, version and package.

Define value for property ‘groupId’: : org.jsystem
Define value for property ‘artifactId’: : my-so-proj
Define value for property ‘version’: 1.0-SNAPSHOT: :
Define value for property ‘package’: org.jsystem: :
Confirm properties configuration:
groupId: org.jsystem
artifactId: my-tests-proj
version: 1.0-SNAPSHOT
package: org.jsystem
Y: : Y

In this example, we will use org.jsystem as groupId and my-so-proj as an artifactId. You can leave the default values for the version and package. If everything has gone smoothly, you should get a BUILD SUCCESS message and a project with the following structure will be generated.

├───my-so-proj
│   └───src
│       └───main
│           ├───assembly
│           ├───java
│           │   └───org
│           │       └───jsystem -> You system objects code comes here
│           └───resources
│               └───sut

You can import the project as a Maven project to your favorite IDE or edit the source files using any text editor.

Creating your first System Object

System Objects are Java modules used to interface with devices and applications in the testing environment. In the folder my-so-proj/src/main/java/org/jsystem, create a new Java class file with the name FileSystemSo.java. Edit the file and paste the following content:

package org.jsystem;

import java.io.File;

import jsystem.framework.system.SystemObjectImpl;
import junit.framework.Assert;

public class FileSystemSo extends SystemObjectImpl {

	private String folder;

	public void verifyFileExistence(String fileName) {
		File file = new File(folder, fileName);
		Assert.assertTrue(file.exists());
	}

	public String getFolder() {
		return folder;
	}

	public void setFolder(String folder) {
		this.folder = folder;
	}
}

Close JSystem and open your operating system console. Change directory to the my-so-proj project and build it using the following command:

> mvn clean install

If everything has gone smoothly, you should get a BUILD SUCCESS message and the my-so-proj artifact will be add to your local Maven repository.

Linking the projects together

Adding the System object project as a dependency

Tests projects use the system objects for communicating with the system under test. To link the projects we should add the system objects project as a dependency in the tests project.

Open the tests project my-tests-proj POM.xml file. You can use Eclipse POM Maven Editor or just use your favorite text editor. Find the Dependencies section and add a section that describes your system object GAV coordinated (Group Id, Artifact ID and version).

<dependencies>
.
.
	<dependency>
		<groupId>org.jsystem</groupId>
		<artifactId>my-so-proj</artifactId>
		<version>1.0-SNAPSHOT</version>
	</dependency>
.
.
</dependencies>

Lib folder

Make sure JSystem is closed and open your operating system console. Change directory to my-tests-proj project and type the following command:

> mvn clean install

Maven will compile and build the project. Under my-so-proj project a new folder with name lib will be created that will contain the my-so-proj-1.0-SNAPSHOT.jar jar.

└───my-tests-proj  
    ├───lib -> Project dependencies
    ├───src
    │   └───main
    │       ├───assembly
    │       ├───java
    │       │   └───org
    │       │       └───jsystem
    │       └───resources
    │           ├───scenarios
    │           └───sut

Important If JSystem wasn’t closed during the command execution, JSystem would lock the Jar files under lib and Maven will not be able to replace them with new ones.

JSystem does not and should not work with Maven dependency mechanism. For that reason, every time you build your tests project the Maven assembly plugin is configured to create lib folder under your tests root project and copy all the dependencies which are not already included in JSystem to this folder.

When JSystem begins to execute the projects tests it includes all the jars that are located in the lib folder to the Java class path.

Note: If you want to exclude some of the jars from being copied to the lib folder, for example, your tests project jar, edit the create-lib.xml file that is located in src/main/assembly folder.

Using the system object in the test

To instantiate the SO from the test add the following method:

        
        private FileSystemSo fileSystem;

	@Before
	public void setUp() throws Exception {
		fileSystem = (FileSystemSo) system.getSystemObject("fileSystemSo");
	}

@Before is used to execute set of preconditions before executing every test in the class.

Learn more about @Before

Edit the test file and paste the following content:

package org.jsystem;

import jsystem.framework.ParameterProperties;
import jsystem.framework.TestProperties;
import junit.framework.SystemTestCase4;

import org.junit.Before;
import org.junit.Test;

public class FileOperations extends SystemTestCase4 {

	private String fileName;
	private FileSystemSo fileSystem;

	@Before
	public void setUp() throws Exception {
		fileSystem = (FileSystemSo) system.getSystemObject("fileSystemSo");
	}

   	/**
	 * Verifies that the specified file exists in the current folder
	 */
	@Test
        @TestProperties(name = "Verify that file ${fileName} exists", paramsInclude = { "fileName" })
        public void verifyFileExistence(){
		fileSystem.verifyFileExistence(fileName);

        }

        public String getFileName() {
            return fileName;
        }

       @ParameterProperties(description = "Expected file name")
       public void setFileName(String fileName) {
           this.fileName = fileName;
       }

}

Using System Under Test (SUT) independence

SUT Independence is the ability to run the same test on different setups without changing the test. Learn more about SUT

To create a SUT file, open JSystem and click on the SUT Planner button.

Click on the first row in the table, and the Add system object will become enabled. Click on the button. You will be asked to select the system object you have just created.

Enter the name of the system object. The name is the key used in the tests to address the specific system object that is configured in the SUT file.

Set a folder name for fileSystemSo data member, folder. (e.g. c:) and click on the save button.

That’s it. You can now execute your first test.