3 JTR-Runners: concepts and configurability


While in the former section we have introduced some basic concepts concerning the overall configuration of the JTR runtime via the jtr.xml configuration file, here we are going to dive into the details of the runners configuration capabilities provided by the JTR project.


Runner’s element attributes

  1. •runs: this represents the number of times each runner instance will have to execute its logic in every epoch

  2. •sleepTime: this JTR-standard parameter determines the amount of time expressed in milli-seconds that each runner instance should pause between two subsequent runs. This valorization applies at the category-level, that’s to say to every running instance of the current runner category.
    Note: this value can be specified on an instance-basis by means of the parameters element.

  3. •enterprise: this JTR-standard parameter specifies the default enterprise configuration that must be made available to every runner of the current category.
    Note: this value can be specified on an instance-basis by means of the parameters element.

  4. •jms: this JTR-standard parameter assigns the category-level JMS configuration
    Note: this value can be specified on an instance-basis by means of the parameters element.

  5. •binding: this JTR-standard parameter states which webservice configuration should be made available to the category
    Note: this value can be specified on an instance-basis by means of the parameters element.


Runner’s sub-elements

  1. •runner-fqn: the FQN of the Java class qualifying the current runners’ category

  2. •instance-count: the number of concurrent instances for this runner class

  3. •parameters-assignment-policy: a mnemonic that tells the JTR-runtime how this runner instances should be parameterized (more details are provided later on in this section)

  4. •parameters: along with its param sub-elements, defines a set of parameters (also called a parameter-set) that must be injected into each runner instance belonging to the current category before being launched

  5. •script-params and script-param sub-elements are used to define the inputs that a parameterization-script must be provided with


Runners parameterization

The JTR framework allows different runner parameterization strategies. It basically comes with two predefined strategies, namely indexed and cyclic. These two keywords can be used to assign a legal value to the above mentioned parameters-assignment-policy element.


Indexed runner parameterization

With the indexed strategy the i-th runner instance gets always initialized with the i-th(n) parameter-set defined in the configuration.


Cyclic runner parameterization

With the cyclic strategy, every runner instance will be injected for its i-th run with the i-th(n) parameter-set available in the provided configuration.


Custom runner parameterizations

The JTR project also allows you to define your own parameterization strategies. Further details on this subject are provided here.


Parameters elements and its sub-elements

As stated before, the parameters element allows you to define a parameter-set that will be used by the JTR-runtime to initialize your runner instances when necessary. Each actual parameter is defined by  a param element, accepting the following attributes:

  1. •name: this must match with one of the current runner class’ properties

  2. •type: specifies the parameterization-type and can be one of the following: default, statistical, scripted. This attribute defaults to default when omitted (only with JTR 5)

  3. •value: this is the string representation of the actual value that must be assigned to the runner property in case type is default. If type is statistical (only with JTR 5) it must be the invocation of a valid built-in statistical function (see here for more details). If type is scripted (only with JTR 5) it must be the invocation of a valid parameterization-script (see here for more details).


Parameters localization & accessibility

As we have just seen the name attribute of the param element must uniquely identify a Java property that can be found in either the runner class or in any of its ancestors.

Note: the JTR runtime (from version 4.0) does not impose neither any particular visibility nor the presence of suitable mutator methods for these properties that should be set during the assignment phase.


Overriding category-level parameters

As we have already seen before, the JTR-standard parameters allow us to perform both test-wide configurations (if applied to the test element) and category-level configurations (if applied to the runner element).

It is anyway still possible overriding these defaults on a per-instance basis thanks to the param element. Defining a param element named just like one of the JTR-standard parameters you can override configurations already set at an higher level.


Some Examples

For sake of clarity we now provide an example that should help you fix what learnt so far.


<?xml version = '1.0' encoding = 'UTF-8'?>


<!-- JTRunner is free software; you can redistribute it and/or modify

    it under the terms of the GNU General Public License as published by

    the Free Software Foundation; either version 2, or (at your option)

    any later version.

-->


<test xmlns="http://jtrunner.sourceforge.net"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://jtrunner.sourceforge.net file:./config/jtr.xsd"

    runs="5">


    <!-- JTR components factories -->

    <factories>

        <factory key="IAssignmentPolicyFactory" fqn="jtr.assigner.impl.DefaultAssignmentPolicyFactory" />

        <factory key="IOutcomeFactory" fqn="jtr.test.impl.DefaultOutcomeFactory" />

        <factory key="IWsHelperFactory" fqn="jtr.ws.jaxws.JaxWsHelperFactory" />

        <factory key="ITestCompletionListener" fqn="jtr.test.impl.DefaultTestCompletionListener" />

        <factory key="ITestResultDisplayer" fqn="jtr.test.impl.DefaultTestResultDisplayer" />

        <factory key="ITestResultsExporter" fqn="jtr.test.results.exporters.impl.ExcelExporter" />

        <factory key="ITestScriptingEngine" fqn="jtr.script.impl.BshScriptEngine" />

        <factory key="ITestStatFunctions" fqn="jtr.lang.functions.impl.DefaultStatFunctionsFactory" />

    </factories>


    <!-- Runners -->   

    <runner runs="1" sleepTime=”5000”>

        <runner-fqn>org.test.FooRunner</runner-fqn>

        <instance-count>2</instance-count>

        <parameters-assignment-policy>indexed</parameters-assignment-policy>

        <parameters>

            <param name="sleepTime" value="100" />

        </parameters>

        <parameters/>

    </runner>


    <runner runs="1" sleepTime=”40”>

        <runner-fqn>org.test.BarRunner</runner-fqn>

        <instance-count>1</instance-count>

        <parameters-assignment-policy>indexed</parameters-assignment-policy>

        <parameters/>

    </runner>

</test>


This example jtr.xml file defines a test-suite that will consist of 5 epochs and 2 runner categories. The first category (org.test.FooRunner) requires 2 instances, the second one just one instance.


The 2 instances of the FooRunner class will run with an indexed assignment policy, thus the first instance will have a 100 ms sleep-time, while the second one will inherit the sleep-time of 5000 ms defined at the category-level.


The only instance of the BarRunner class will run with an indexed assignment policy inheriting the 40 ms sleep-time defined at the category-level.



Next step: working with statistical parameters