JTorX Manual

this page is under construction

In this page we discuss JTorX version 1.9.0; most of the text here will also apply to earlier or later versions of JTorX; in version 1.10.0 a few user interface elements are changed, as we explain in footnotes.

Introduction

The main functionality provided by JTorX is model-based testing.
This means: interacting with a SUT (system under test), to test whether the SUT conforms to the model.
The SUT conforms to the model when the model predicts all responses of the SUT to stimuli that are in (allowed by) the model.

Typically, many different test can be derived using a model. A user has three ways to control which test case is derived and executed:
  • direct interaction with JTorX (manual selection of the next test step)
  • providing guidance information to JTorX, to automatically steer the test derivation
  • providing the seed to the random number generator that is used by the random selection machinery in JTorX.

Graphical User Interface

All configuration and usage is done via the JTorX graphical user interface1.
Typically, configuration items can not be changed when a test run is active.

Panes

The graphical user interface uses panes to group related user interface items together.
Some of the panes are always there: Config, UtracesCheck, IocoCheck, and Test.
Additional panes appear due to user interaction: Log and Simulate.
  • a Log pane appears when a test run is started and "show log" is checked;
  • a Simulate pane appears when the user presses a "Simulate" button, like those present e.g. in the "Config" "Components" sub pane.

Panes can be reorded by clicking and holding the tab that shows the pane name, and dragging it left or right.
The panes that appear due to user interaction can be deleted, one by one, by clicking on its tab to make it visisble, at which point an X will appear in the tab -- pressing this X deletes the pane.

Behaviour of "file browser" confirmation on text fields

For many configuration items, the path to one or more files must be given in text fields. Many of these text fields have a dedicated "Browse" button that shows a file browser. Confirming a choice in such file browser may have two different effects:

  • for configuration items where only a single item is expected (like e.g. the path to a model), the entire contents of the text field is replaced by the value chosen in the file browser;
  • for configuration items where multiple items are expected (like a program with arguments), the current selection in the text field is replaced by the value chosen in the file browser.

Window orientation vs screen size

Depending on the screen size, JTorX will show itself in 'portrait mode' (when the screen is high enough) or 'landscape mode' (when the screen height is < 875 pixels). In 'portrait mode' the Config and Test pane appear together in a single window; in 'landscape mode' only one of them is visible at a time.
JTorX can be invoked with command line flags --portrait to force portrait mode and --landscape to force landscape mode.

Messages window

The bottom of the JTorX window contains a messages pane, and two progress bars.

The message pane shows messages from JTorX, and messages that JTorX receives from the programs that it starts to do its work, like Adapter programs that are used to interact with the system-under-test, and programs to access models.

The Messages pane shows one message at a time. The buttons to the right of the message text area can be used to scroll through the list of messages.
When a message is very long, a scroll bar appears inside the message area; it can only be used to scroll the text of the message that is being shown.
It is possible to shrink the Messages pane, but it is not possible to increase its size.

The progress bars are not used at the moment (updating them seemed to make the testing proceed much slower).

Panes

We now discuss the panes one by one.

Config

This pane consists of two sub-panes: "Config Items", and "Components".

Config: Config Items

This pane contains the main configuration items of JTorX. Not all configuration items are always visible -- typically, irrelevant items are not shown.

Model: specify path to the model in the text field, or click "Browse" to navigate to it.
(The path selected via "Browse" will replace the entire contents of the text field.)
Two kinds of models can be given:
  • ready-to-use in the form of an automaton, or state space (file formats e.g. .aut, .graphml, .bcg);
  • to be expanded on-the-fly (file formats e.g. .lps)
Click "View" to obtain a visualization of the model; but be careful:
  • When the model is not given as explicit state space, JTorX will first generate the entire state space before visualizing it, which may take quite a while, or might not finish at all when your model has an infinite state space.
    Thus, don't click "View" when you know that the model has an infinite state space.
  • When your model has a large state (or location) space, the visualization algorithm will typically be slow.
  • For STS models it will show the locations and the switches (without trying to generate the entire state space).

Bottom line: JTorX is not very good at visualizing large models, especially when there is no ready-to-use statespace available.

Instantiator: when the checkbox is checked, a text field appears in which to specify the path to program that is to be used as instantiator for symbolic or timed model.
The "Browse" button can be used to navigate; the path selected via it will replace the selection in the text field.)
Specification of an instantiator is now only necessary for a timed model (it is not necessary for a symbolic STS model (file format .sax))

Guide: when the checkbox is checked, a text field appears in which to specify the path to a separate model that is to be used to guide the test derivation process.
(The path selected via "Browse" will replace the entire contents of the text field.)

Click "View" to obtain a visualization of the guidance model; don't do that when you know that the model has an infinite state space.
JTorX is not very good at visualizing large models, especially when there is no ready-to-use statespace available (see the warnings above about viewing models).

The combo box allows selection among of three sources of guidance information:
  • use model below (already containing epsilon labels)
  • use trace below (add epsilon label to end states)
  • use selected IocoChecker failure suspension trace

Implementation: specify the kind of implementation, and/or how it is accessed via the combo box.
Depending on the selection made, the label before the text field below the combo box will change, as indication of the information that has to be given.
Moreover, depending on the selection made, additional items may appear in the dialog.

  • simulation of given model - directly connected
    A simulation of the given model is started when the test run is started. Where applicable the simulator will make its own random choices using its own random number generator, of which the seed can be given.
    The given model to be simulated as SUT must have the same labels as the model from which the test is derived.
    Model: appears before the text field, a text field Seed: appears to the right of the combo box2, and a checkbox Instantiator: appears below the Model: text field.
    • specify path to the model in the text field, or click "Browse" to navigate to it.
      (The path selected via "Browse" will replace the entire contents of the text field.)
    • optionally, specify a random number generator seed in the Seed: text field (if it is left empty, the random number generator seed that is used for the test derivation is also used for the random number generator that is used for the simulator)
    • optionally, an instantiator can be specified, just like described above for the model that is used for test derivation.
  • real program, comm. labels on stdin/stdout
    The given program is started when the test run is started. When JTorX wants to apply a stimulus, it writes a single line of text to the standard input of the program: a text string that represents the label, followed by a carriage-return character. JTorX reads the standard output and the standard error of the program. It reads the standard output line-by-line, and treats each line as an observation, i.e. it should contain a text string that represents a label, followed by a new-line character. JTorX reads the standard error of the program line-by-line and displays them in the message pane.
    Program+args: appears before the text field, and a checkbox RealTime: appears to the right of the combo box.
    The "Browse" button can be used to navigate; the path selected via it will replace the selection in the text field.)
    • specify path to the program in the text field, and optional arguments.
      You can click "Browse" to navigate to the program, and to arguments that are files.
    • optionally, for real-time testing, check the RealTime checkbox. When it is checked, the last (right-most) parameter in each label is interpreted as a timestamp (relative to start of test run), and JTorX keeps track of time. In the interaction with the system under test the parameter that represents time is omitted. When an observation label is read from standard output of the system under test, that label is extended with a parameter that represents the time at which the observation was received, and the result is added to the observation queue. When the timestamp of a stimulus is in the future, JTorX delays passing the stimulus label to system under test, until the moment in time represented by the timestamp is reached; if in the mean time an observation is obtained, the stimulus is not applied. When the timestamp of a stimulus is not in the future, the stimulus label (without timestamp parameter) is passed immediately to the system under test.
  • real program, comm. labels via tcp, JTorX is client
  • real program, comm. labels via tcp, JTorX is server
  • real program, started via given TorX adapter
  • re-run of saved test run log

Config: Components

Test

Log

Simulate

IocoChecker

UtracesChecker

1 This is being changed in version 1.10 (currently in beta), where it is possible to save/load a configuration, and run tests without graphical user interface (like was possible with TorX).

2 From version 1.10 on, the Seed: text field appears in the Test pane.