Quick Start Guide
In this example we will create a simple JSystem project to verify existence of files.
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.
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
Go to the downloads page and install the latest stable JSystem version. Generate a test project
Top-Q Maven repository holds an archetype catalog which describes different projects archetypes that can be generated.
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 org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeCatalog=https://maven.top-q.co.il/service/local/repositories/releases/content/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
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
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());
}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.
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.
Let’s get back to our test code and add some descriptive data.
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.
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());
}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.
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.
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.
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.
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>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.
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.
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;
}
}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.