Chapter 5 - Using Test Sheets

Creating and Deleting Objects

Objects can be created, selected, and deleted by using the Selection and Object buttons along the top of the Graphical User Interface (GUI). Figure 5.1 shows the Test sheet buttons.

Selection Button

 Select Mode

Left-click on the select (arrow) button to turn on Select mode. In Select mode, an object can be selected by left-clicking on it. Object selection is indicated by one or more handles being shown on the object. Multiple objects can be selected by holding down the <Shift> key while doing the selections.

If the <Delete> key is pressed while one or more objects are selected, those objects are deleted from the Test sheet. When a Message Test object is deleted, all objects with a temporal dependency on the object are also deleted.

Object Buttons

A left-click on any of the following Object Buttons will put the Test Sheet into a mode where the object can be created.

 PE Test Object

Left-click somewhere on the Test sheet to create a PE Test object. A window will open to allow you to choose which PE object should be associated with this PE Test object.

 Message Test Object

Left-click on a Whitehole or Action object to begin the creation of a Message Test. Complete the Message Test connection by left-clicking on a Blackhole object or on one of the small cross shapes under the appropriate PE Test object.

An Action object emanates from and orbits around a Node. If the circle portion of an Action object is colored white, then a Message object is connected to the corresponding Action event in the model and it is possible to start a Message Test on this Action object. If the Action object is colored red, then there is no Message object available to which to connect a Message Test.

When starting a Message Test from a Whitehole object, a popup menu will display the labels of the Message objects in the model, allowing you to choose the Message object of which the Message Test will be an instance.

Node objects anchor the reception end of a Message Test object to a PE Test object. They are created and destroyed automatically as Message Test objects are attached and detached.

When a Message Test object is deleted, all Message Test, Node, and Action objects with a temporal dependency are also deleted. The temporal dependency is determined by two axioms:

• A received message must be preceded by a sent message.
• Given a Guard event (attached to a Node) which is above another Guard event (attached to a Node) on a PE Test stem, the upper Guard event must precede in time the lower Guard event.

 Whitehole Object

Left-click anywhere on the Test sheet to create a Whitehole object. A Whitehole object is used as a starting point for a Message Test that does not originate on a PE.

 Blackhole Object

Left-click anywhere on the Test sheet to create a Blackhole object. A Blackhole object is used as an ending point for a Message Test that does not terminate on a PE.

 Flag Object

If there is State() associated with a PE Test, then a Flag object can be created to monitor and display the state values. Left-click on a cross shape under a PE Test to create a Flag object. As the Flag is created, a popup menu allows you to select the names of the states that are to be displayed. The displayed values are updated when the test scenario is executed. A Double-left-click on the object will redisplay the popup menu.

 Clock Object

A Clock object is used to represent the passage of wall-clock time. Left-click on a cross shape under a PE Test to create a node and attach the Clock object.

Moving and Resizing Objects

Objects can be moved and resized after being selected in Select mode. Not all objects can be resized with the cursor. For example, a selected Node is shown with only one handle which is used to drag the Node to a new location. Almost all objects have restrictions in their axes of movement in order to maintain object relationships. For example, a Node object must stay on the stem of its associated PE Test.

Like the Edit sheet, there are two types of handles which can appear on objects. The traditional handle is square-shaped and is meant to be clicked and dragged. The other type of handle is diamond-shaped and appears at the ends of lines. When a diamond-shaped handle is clicked, the handle goes away and the line follows the cursor so that the line can be repositioned.

The following objects can be moved and/or resized:

Originating Messages

A Message Test object can originate from a Whitehole object or from an Action object by left-clicking on one of these objects while in Message Test mode.

The creation and connection of a Message Test object represents an instance of a message being sent and received. Origination from a Whitehole object represents a message which seemingly appears "out of nowhere". The Test sheet allows any message in the test scenario to originate from a Whitehole.

When choosing the label of a message originating from a Whitehole, one of the labels available in the list is Init_Msg. This Message object is hard-coded into the model. When the Init_Msg Message Test is connected to a PE Test, all of the Initial Rules are presented in a popup window so you can select which Initial Rule is to be attached to the PE Test. All Rules in the model which have no Guard event are considered to be Initial Rules.

Connecting Messages

The Test Sheet allows a Message Test object to be connected only to a PE Test which corresponds to the PE to which the corresponding Message connects in the model. In Message Test mode, the cursor changes to a crosshair pointer only when under an appropriate PE Test. Left-clicking then causes a Node to be created and the Message Test to be connected to the new Node.

When doing Message Test connections, the Test Sheet does not allow a connection to be made which would be a temporal violation. In other words, you are not allowed to place an event earlier in time than an ancestor event. A forbidden icon appears if a connection would cause a temporal violation.

Using Flag Objects

The Flag object is used to display selected contents of the State() array. When the Flag is created, a popup menu allows you to select the array entries which should be displayed. The entries which appear in the menu are those names which are in the State() array after the latest running of the test scenario.

Once a Flag is created, the test scenario must be executed (with the button) in order to display the runtime values of the selected State() entries.

A Double-left-click on an existing Flag object causes the menu to reappear so that the displayed entries can be changed.

Executing Test Scenarios

Arranging the Message Test connections on a Test sheet creates a specific order of events to execute for each PE Test. The simulation is run by invoking <scenario_tag> execute, which invokes <petest_tag> execute in order to execute the events for each PE Test.

A scenario will be (re)executed in the following situations:

• When connecting or disconnecting a Message Test from a Node
• When the Execute Test Scenario button is pressed
• After a test scenario is loaded into ProtoCollum from a file
• Before a test scenario is saved away to a file