Using XJRunner Integration

XJRunner Integration allows the user to run tests that have been defined in a project previously created within XJDeveloper. A Runner instance must first be created, and its methods can then be used as described below.

Creating a Runner Instance

A Runner instance is created with GetRunner(), which must be passed the instance of the XJLink being used. This Runner object gives access to the project’s XJEase functions.

In C#, it can be created as follows:

	var xjlink = XJLink.GetXJLink();
	var runner = project.GetRunner(xjlink);
  

In LabVIEW, this is done using the CreateRunner.vi, as shown in Figure 7 (taken from the example XJTAG Single Test Run.vi):

GetRunner will create a Runner instance Pass in a refnum to the XJLink to be used Pass in a refnum to the project being used A refnum for the Runner instance is output Optionally a refnum to the XjtagOutputBox may be passed to the Test Output Box input terminal

Figure 7: Creating a Runner Instance in LabVIEW

• Each time a new board is tested, the previous Runner instance should be disposed using the CloseRunner.vi, and a new one created in order to reset global variables.

XJRunner Tests

The tests available to run are defined by the project's test list. Individual tests from that list can be run using RunTest(), or all the tests enabled in the list can be executed in sequence using RunTests(). In addition, XJIntegration provides access to the set of underlying XJEase functions that are used by tests, and they can be executed in isolation – see The Difference Between Tests and Functions below.

As an example, consider the test list of Figure 8, which includes a group of tests called LED Tests. To run the individual test D1.Test, it is selected by name, and RunTest() is then used to execute that test.

Figure 8: XJDeveloper's Test List

A C# example to run the test D1.Test from the group LED Tests could be:

	var testList = runnerProject.GetTestList();
	var ledTest = testList.TestFunctionByName("LED Tests", "D1.Test");
	uint result = runner.RunTest(ledTest); //Runs a single test function
  

The call to RunTest() returns the test function result as an unsigned integer.

Running A Complete Test List Using XJRunner Integration

To run a set of tests in a similar way to XJRunner, RunTests() is used, with the test collection being passed in. By default, it will run only those tests that were enabled in XJDeveloper as shown in this C# example:

	var testList = runnerProject.GetTestList(); //retrieve test collection with only default tests set to run
	runner.RunTests(testList); //runs the default test list
  

The test collection returned by GetTestList() contains the complete set of tests, but only some of them might have been set to run when it was created in XJDeveloper. It is possible to override this default and modify which tests are enabled by using methods from the TestCollection class: SelectAllToRun() can be used to enable all the tests, while SelectTestGroup() can be used to enable just those in a particular group. Similar methods are available for disabling tests.

Retrieving Test Results and Output

The LastTestRunPassed property returns true if no tests in the last test run failed. The OutputFromLastTestRun property contains the full text output from the last test run. If details from individual tests are required then the GetResultsFromTest() method may be used. This method takes either a TestFunction object or a group name and function name to specify the chosen test. It returns a TestResult instance for each iteration of the chosen test from the last test run. This TestResult object has three properties, Output, TimeTaken and Result. which provide the text output generated, the time taken to run and the result of the test respectively. A C# example for accessing this result data for the test ledTest could be:

	foreach (var iteration in runner.GetResultsFromTest(ledTest))
	{
		var result = iteration.Result; //The result from this iteration
		var timeInMs = iteration.TimeTaken.Milliseconds; //the time taken to run the test in milliseconds
		var textOutput = iteration.Output; //the text output generated by the test
		...
	}
  

Running XJDeveloper Tests Within LabVIEW

The example XJTAG Single Test Run.vi demonstrates a way in LabVIEW to run XJEase tests from the test list. As shown in Figure 9, the Runner is created (as outlined above) and the Sub-VI RunTestCollection.vi is used to run the default test list selection, as defined in XJDeveloper. This example uses the XjtagOutputBox .NET control to display any testing output to the VIs front panel.

RunTestCollection.vi runs the default test selection Pass in a refnum for the RunnerProject instance Pass in a refnum for the Runner instance

Figure 9: Using RunTestCollection.vi to run the default test selection

The RunTestCollection.vi has some additional terminals for selecting tests and retrieving output from the completed test run, as shown in Figure 10.

Optional input terminal Selected Tests takes an array of strings to select tests Output terminal returns all text output as a string Returns an array of LabVIEW clusters with results for each test that ran

Figure 10: The available terminals on RunTestCollection.vi.

The full text output can be accessed from the PlainTextOutput output terminal on RunTestCollection.vi. The test results may also be accessed through the Test Results output terminal. This terminal outputs a LabVIEW array containing a cluster with the data for each test iteration that ran. Each cluster contains elements for Test Name, Group Name, Result, Text Output and Time Taken (in milliseconds). For more details, see the documentation in LabVIEW for the VI and its terminals.

The VI has an optional input terminal Selected Tests which takes an array of strings that specify the test groups or individual tests within the test collection to run (not used in the example). A whole test group may be specified by name, or individual tests may be specified using the format TestGroupName*TestName.

The Difference Between Tests and Functions

When RunTest() is called, an XJEase test from the project's test list is executed in a similar manner to when it is used in the XJRunner application. However, those tests may call lower-level XJEase functions to perform the individual steps of the test. For example, the XJEase file led.xje uses Test() to flash an LED until a key is pressed; but Test() then makes calls to the lower-level function setLED(val), which switches the LED on or off. If the top-level test is unsuitable for some reason, it is possible to use XJIntegration to call these underlying functions directly.

As an example of when this might be necessary, consider the situation where it is needed to turn on an LED to allow external test equipment to check its colour and intensity, before switching it back off. The high-level Test() could not be used because it flashes the LED rather than providing constant illumination, but the underlying function setLED() would be suitable as it allows the LED to be controlled as needed.

To call a lower-level function, RunFunction() should be used instead of RunTest().

The LabVIEW example XJTAG LED User Interaction.vi demonstrates how to make these function calls in LabVIEW.

The Difference Between Run and Start

XJRunner tests can be called inside the Runner instance in two ways – by using RunTest() or StartTest(). The difference between the two is an important one: "Run" triggers a test to start and waits for it to complete, whereas "Start" triggers the test but immediately returns control so that other tasks can be performed.

As an example, StartTest() or StartFunction() might be used when the code also interacts with other test equipment: it could trigger a test or function and then return control to LabVIEW for it to capture a measurement from external test equipment (as illustrated in the LED Test described above); or to display a progress bar during a long routine such as programming.

StartTest() and StartFunction() must be used in conjunction with the WaitForCompletion() method to know when they have finished running. WaitForCompletion() must be called after starting a background test or function and it returns when they have completed.

• It is recommended that RunTest() and RunFunction() are used instead of their "Start" equivalents unless there is a definite need to return control before the test has completed: the "Start" commands give users more opportunities to make errors!

In LabVIEW, the difference between RunTest() and StartTest() can be seen by comparing the two examples XJTAG Single Test Run.vi (which uses the RunTestCollection VI) and XJTAG Multiple Test Runs.vi (which uses the XJTAG START RUN VI).

Disposing the XJRunner Object

Once all the tests on a particular board have been completed, the Runner object should be disposed. In C#, this is done using the command:

	runner.Dispose();
  

In LabVIEW, it can be done using CloseRunner.vi and passing in the refnum for the Runner instance:

CloseRunner.vi calls DisposeDotNet.vi to dispose the runner instance Pass in the Runner instance An optional timeout to wait for tests to complete before disposal may be given

Figure 11: Disposing a Runner Object in LabVIEW

Note that this only disposes the Runner instance; the RunnerProject or AnalyserProject and the XJLink instances remain instantiated.