Introduction to XCore Framework

XCore is a framework that lets you manage your test cases in XML 'test scripts' instead of code. This guide will help you understand your first test run using the XCore framework.

Our recommendation is to grab a copy of our sample XCore project from GitHub. Once your project is built, you can see the XCore Maven dependency automatically placed in your new project's pom file and after successfully running

mvn install

on the project, you should have all of XCore's required libraries.

.POM Snippet

<dependency>
  <groupId>org.finra.jtaf</groupId>
  <artifactId>jtaf-xcore</artifactId>
  <version>1.0</version>
</dependency>

Ready to see the components of what's now your own XCore project?

The relevant files involved in declaring this test run are the Test Suite, Test Library, Test Strategy, Java command, and jtaf.properties configuration. A test run is executed with the XMLTestDriver.

Test Suite
Open up HelloWorldTest.xml under the testscripts folder.

One of these files is where anybody testing an application under test can write tests in a domain specific language and see their test case defined in xml format.

<?xml version="1.0" encoding="ISO-8859-1"?>
<testsuite name="First Tests"> <!-- testsuites can have multiple test scripts inside -->
  <!-- The following is an example of an xml test script: -->
  <test name="HelloWorldTest">
        <desc>Simple Hello World Test Case</desc> <!-- desc tag and coverage are optional -->
	<coverage>APP-001</coverage>
	<automationValue>Regression</automationValue> <!-- a tag for filtering which tests run in your strategy -->
	<teststeps>
	  <ExampleCommand assertableText="Hello world" printHello="true">
	    <map name="mapToPrint">
	      <string name="Hello">World</string>
	      <string name="Test">This is not a test</string>
	      <string name="X">Core</string>
	    </map>
	  </ExampleCommand>
	</teststeps>
  </test>
</testsuite>

Test Strategy

Open up helloworld.strategy.xml, located under profiles/strategies.
Strategy files are where the tests to include in your test run are defined. A full tutorial of the stategy's possibilities can be seen here.

<?xml version="1.0" encoding="ISO-8859-1"?>
<execute>
  <target name="HelloWorldTest.xml" />
</execute>

Test Library

Open up helloworld.commands.xml under src/main/resources/testlibrary.
This is where a definition of your DSL which goes into your test script is declared and where that DSL is mapped to a Java command class.

<?xml version="1.0" encoding="ISO-8859-1"?>
<library>
  <command name="ExampleCommand" class="org.myorg.example.commands.helloworld.ExampleCommand">
    <usage>
      This command is just a simple example to showcase some features of JTAF XCore:
      Assert that some input text is "Hello world", optionally printing a map of key
      value pairs and a "Hello." statement if a boolean's value if included in test script. 
    </usage>
    <requiredParameters>
      <string name="assertableText">What to compare against the text from the application ("Hello world")</string>
    </requiredParameters>
    <optionalParameters>
      <map name="mapToPrint">A map of key value pairs to print if specified</map>
      <boolean name="printHello">A boolean value to print "Hello." if specified true</boolean>
    </optionalParameters>
  </command>
</library>

Command Class

Open up the Java class under org.myorg.example.commands named ExampleCommand.java. Command classes are where the logic behind the DSL is coded.

package org.myorg.example.commands.helloworld;

import java.util.Map;

import org.finra.jtaf.xcore.model.exceptions.NameFormatException;
import org.finra.jtaf.xcore.model.execution.IInvocationContext;
import org.finra.jtaf.xcore.model.invocationtarget.Command;
import org.junit.Assert;

public class ExampleCommand extends Command {

  public ExampleCommand(String name) throws NameFormatException {
    super(name);
  }

  protected void execute(IInvocationContext ctx) throws Throwable {
    String expectedText="Hello world";
    /* All objects from the test script can be accessed from the associated Command class */
    String actualText=getRequiredString("assertableText");
    
    /* The Command class is usually a smart place to perform your assertions */
    Assert.assertEquals("Your text doesn't match " + expectedText, expectedText, actualText);
    
    /* Lists and maps passed into the context from the test script must be casted from objects */
    Map<String, Object> map = (Map<String, Object>) getOptionalObject("mapToPrint");
    
    if(map != null) {
      for(String k : map.keySet()) {
        System.out.println(k + ": " + map.get(k));
      }
    }
    
    boolean printHello = getBooleanOrDefault("printHello", false);
    if(printHello) {
      System.out.println("Hello.");
    }
  }
}

Run Configuration
Open up jtaf.properties, located under the profiles folder

strategy=profiles/strategies/helloworld.strategy.xml

Setting the strategy property in jtaf.properties is necessary so that when you run your project's XMLTestDriver, XCore knows which set of tests to run for the test run. Other run-specific properties can be set in this properties file as well, however are not mandatory. A typical scenario is to set a target property for the test run, which will be used to provide any environment-specific values to be used for the run. See an example showing how to use the Property Manager to retrieve information set from jtaf.properties right here.

Test Execution

Now you're ready to run some tests.

Find the class XMLTestDriver.java in src/test/java under the org.myorg.example package. As XCore runs with JUnit, run the class with JUnit, grab a bowl of popcorn, and watch your XCore test script run!

XCore includes many features like multithreading, exception handling, block statements, random generators, dependency-exclusion handling, looping, plugins and utilities like a Data Comparator and Property Manager. For more information on these, take a look at the Documentation dropdown.

Getting Started