mecate(n) 1.2.1 mecate "Mecate Package for Bosal Test Harnesses"

Name

mecate - Interacting with a bosal generated test harness

Table Of Contents

Synopsis

  • package require Tcl 8.6
  • package require mecate ?1.2.1?

Description

This manpage describes the mecate package which is a Tcl script extension that simplifies interactions with a bosal generated test harness.

Commands

The main command in the package is a TclOO class command to create a rein object. The methods of a rean object provide access to the test harness. In addition, some utility procedures are provided. The package commands form a namespace ensemble command.

mecate rein create reinobj ?options?
mecate rein new ?options?

The mecate package is organized as a single TclOO class called rein. The rein class command is also exported as an ensemble command from the mecate namespace. The constructor for rein takes a set of option / value pairs. The options are:

-timeout <msec timeout>

The default time out value for synchronization operations. If no timeout option is given, the default is 2000 milliseconds.

mecate eventTraceFormat trace

The eventTraceFormat converts a raw event trace dictionary into a a human readable string. The output is similar to that produced by formatEventTraces but is intended to format only a single trace.

mecate instrTraceFormat trace

The instrTraceFormat converts a raw instrumentation trace dictionary into a a human readable string. The output is similar to that produced by formatInstrTraces but is intended to format only a single trace.

mecate fatalTraceFormat trace

The fatalTraceFormat converts a raw fatal error trace dictionary into a a human readable string. The output is similar to that produced by formatFatalTraces but is intended to format only a single trace.

Rein Object Methods

This section lists the methods supported by objects of the rein class.

Class Management

reinobj destroy

The destructor for rein objects closes any communications connection made to the harnessed application.

reinobj cget option

The cget method may be used to obtain the values of the options that were set during construction. Option is one of the options described for the constructor. The method returns the value of the given option.

reinobj configure ?opt1 value1 opt2 value2 ...?

The configure method may be used to set the values of the configuration options. Option names and values are those described for the constructor. Returns the empty string.

Test Harness Management

The methods in this section are used to set up and take down a test harness program. It is necessary to start the execution of a test harness before is can be used. Sometimes this is accomplished outside of a test script, for example if the test harness is running under control of a debugger. When a bosal generated test harness starts, it acts as a server, opening a TCP port on the local host and awaiting a connection. To communicate with the test harness program, it is necessary to establish a TCP client connection to the test harness acting as a server. The rein class provides methods to manage these actions directly from a test script.

reinobj start program ?delay?
program

The file name of the test harness program executable.

delay

The the number of milliseconds to wait before control is returned to the caller. This time is used to insure that the harness program has had enough time to establish its communication interface before allowing the test to proceed.

The start method is used to begin execution of the test harness program. Starting is separated out as a method because certain test situations will have the harness program running under a debugger which will be responsible for starting program execution. The return value is the process ID of the harness program, although such a number is of little use in the Tcl world. When the test harness communications channel is destroyed, the harness program itself exits.

reinobj connect ?port?
port

The local host port number on which the test harness program accepts connection requests. By default this is port 3906.

The connect` method forms a communications connection to the test harness. All I/O to and from the test harness happens across this connection. The method returns the empty string and throws an error if the connection cannot be established.

reinobj disconnect

The disconnect method closes the communications connection to the test harness. This causes the test harness process to exit.

reinobj null

The null method performs no action on the test domain, but communicates with it to insure that it is responsive.

reinobj version

The version method returns the version number of bosal used to create the test harness code.

Harness Introspection

A bosal generated harness has introspection capabilities that can be used to determine the characteristics of the domains in the harness. This information is available using the query method described in this section.

reinobj query what ?arg1 arg2 ...?
what

The type of query to be performed. The what argument may be one of the following:

domains

Returns the names of the domains contained in the test harness.

operations domain

Returns the names of the domain operations for the given domain.

doparams domain operation

Returns the names and data types of the parameters for the given domain operation.

classes domain

Returns the names of the class for the given domain.

attributes domain class

Returns the names of the attributes for the given class.

instances domain class

Returns the total number of instances and the name and identifiers for the pre-existing instances.

states domain class

Returns the names of the states for the given class.

events domain class

Returns the names of the events for the given class.

evparams domain class event

Returns the parameter names and data types for the given event.

current domain class instance

Returns the current state of the given class instance.

The query method returns the result of querying various entities in a test harness. It is possible to determine the domains in the harness, the classes of each domain and many other characteristics.

Operations on Domains

reinobj domainop operation ?arg1 arg2 ...?
operation

The name of the domain operation to invoke.

argN

Arguments to the domain operation. The order of the arguments must be the same as that defined for the given domain operation.

The domainop method invokes a domain operation on a domain.

Operations on Class Instances

reinobj create domain class
domain

The name of the domain containing the class.

class

The name of the class of the instance to be create.

The create method creates an instance of the given class and returns a integer identifier for the instance. The identifying number is unique only within the class.

N.B. that the instance is created in an uninitialized state and it is necessary to follow up with invocation of the update method on the instance to initialize it attributes. Also, creating instances can cause problems with referential integrity which will be detected on the next transaction boundary. Since there is no way to deal with associations from the test harness interface, creating class instances is of limited utility.

reinobj delete domain class inst
domain

The name of the domain containing the instance.

class

The name of the class to which the instance belongs.

inst

The integer identifier of the instance. Pre-existing instances may use the instance name for this field.

The delete method deletes the given instance.

N.B. Deleting an instance often causes a referential integrity problem that my create a fatal error when the next thread of control is finished. In general, it is not safe to delete arbitrary instances and there is no mechanism provide to manipulate relationship instances in the harnessed domains.

reinobj read domain class inst ?attr1 attr2 ...?
domain

The name of the domain in which the instance is defined.

class

The name of the class to which the instance belongs.

inst

The name or ID number of the class instance to read.

attrN

The names of the attributes whose values are returned. If no attribute names are given, then the return value is a list of alternating attribute name / attribute value elements for all the attributes of the class. Otherwise, only the named attribute values are returned as name / value elements.

The read method reads the values of attributes from classes in a domain.

N.B. Not all attributes of an instance may be read. In particular, instance data used to implement associations and generalizations is not available since these values are memory addresses and not meaningful outside of the domain.

reinobj update domain class inst ?attr1 value1 attr2 value2 ...?
domain

The name of the domain in which the instance is defined.

class

The name of the class to which the instance belongs.

inst

The name or ID number of the class instance to read.

attrN

The name of the attribute to whose value is to be updated..

valueN

The corresponding value that is to be updated into the attribute.

The update method updates the values of attributes of classes in a domain. The attribute names and values are given in pairs as arguments to the method. Note that multiple attributes may be updated in a single invocation of the method.

Signaling Events

One of the primary ways to cause a domain to react is to signal events to the class instances. Both immediate and delayed signaling is supported.

reinobj signal domain class inst event ?param1 param2 ...?
domain

The name of the domain in which the instance is defined.

class

The name of the class to which the instance belongs.

inst

The name or ID number of the class instance to read.

event

The name of the event to signal.

paramN

Parameters of the event. Parameters must be given in the same order as defined for the event or state into which the event causes a transition.

The signal method signals an event to a class instance. Signals generated from a test harness are considered to be generated outside of a state machine context and so start a new thread of control

reinobj delaysignal domain class inst delay event ?param1 param2 ...?
domain

The name of the domain in which the instance is defined.

class

The name of the class to which the instance belongs.

inst

The name or ID number of the class instance to read.

delay

The minimum number of milliseconds that are to elapse before the event is signaled. A delay value of 0 results in the event being signaled immediately.

event

The name of the event to signal.

paramN

Parameters of the event. Parameters must be given in the same order as defined for the event or state into which the event causes a transition.

The delaysignal method signals an event to a class instance at some time in the future.

reinobj cancel domain class inst event
domain

The name of the domain of the instance whose event is to be canceled.

class

The name of the class of the instance whose event is to be canceled.

inst

The instance identifier or instance name whose event is to be canceled.

event

The name of the event to cancel.

The cancel method requests an delayed signal be canceled.

reinobj remaining domain class inst event
domain

The name of the domain for the instance whose remaining time is requested.

class

The name of the class of the instance whose remaining time is requested.

inst

The instance identifier or instance name remaining time is requested.

event

The name of the event for which the remaining delay time is requested.

The remaining method returns the number of milliseconds before the event is to be signaled. A return value of 0, implies that either the event has already been signaled (i.e. its delay time has already expired) or the delayed event did not exist.

reinobj createasync domain class event ?param1 param2 ...?
domain

The name of the domain in which the class resides.

class

The name of the class for which an instance is to be created.

event

The name of the creation event to be signaled.

paramN

The event parameters for the creation event.

The createasync method creates a class instance asynchronously by signaling a creation event.

Controlling Execution

The test harness generated by bosal makes extensive use of the means provided by the micca run-time code to control the event loop. The micca run-time code allows the dispatch of individual events, an entire thread of control and exiting the event event loop. In addition, the test harness installs its own fatal condition handler to prevent the harness program from exiting if a fatal error condition arises.

reinobj eloop ?run | halt | once | toc ?wait | nowait??

With no arguments the eloop method returns the current state of the event loop, either running or halted. An additional argument may be given to control the state of the event loop.

run

Start running the event loop. Returns running.

halt

Halt the dispatching of events. Returns halted.

once

Dispatch one event from the event loop. Returns true if the event was dispatched and false if no event was awaiting dispatch.

toc ?wait | nowait?

Dispatch one thread of control. If wait is specified (or if no additional option is given), then the event loop will wait until a thread of control event arrives. If nowait is given and if there is no pending thread of control event, the command returns immediately. Returns true if a thread of control was dispatched and false otherwise.

State Machine Traces

Test harnesses can output traces showing the chronological sequence of event dispatch for the state machines. Mecate has methods to accumulate and synchronize to the event traces. Internally, rein object keep a cache of the state machine traces as well as accumulate them for later storage. The cache is used to search and wait for particular events.

reinobj trace ?on | off?
on | off

Turn tracing either on or off. In all cases, the current state of the tracing is returned.

The trace method controls whether state machine dispatch traces are output from the test harness and accumulated by mecate.

reinobj waitForEventTrace ?field1 pattern1 field2 pattern2 ...?
fieldN

The name of a field of the event trace. Valid field names are:

type

The type of the transition. The value of the type field is either transition, polymorphic, or creation.

event

The name of the event.

source

The class instance that signaled the event.

target

The class instance that received the event.

time

A timestamp of when the event was dispatched.

For transition type events, the following fields are also available:

currstate

The name of the state before the event dispatch.

newstate

The new of the state after the event dispatch. If this field is IG, the event was ignored. If this field is CH, the event caused an error condition.

For polymorphic type events, the following fields are also available:

relationship

The name of the generalization relationships across which the polymorphic event is inherited.

newevent

The new name the event has in the context of the next level of the generalization.

subclass

The name of the subclass to which the superclass instance was related when the polymorphic event was dispatched.

For creation type events, there are no additional fields.

patternN

The corresponding pattern to match for the given key. Patterns may be of any form accepted by the `string match` command.

The waitForEventTrace method examines the cache of state machine event traces in chronological order searching for a match to the field / pattern pairs given. Any trace that does not match is discarded from the cache. If necessary, execution of the test is suspended until a state machine trace matching the given parameters arrives or a timeout occurs. Matching multiple fields is conjunctive in nature, i.e. if multiple fields are given, then all fields must match to consider the event trace to be a match.

The method returns the matching state machine trace. If a timeout or fatal error occurs, then the method throw an error.

reinobj clearEventTraceCache

The clearEventTraceCache method deletes any accumulated state machine event traces contained in the event trace cache. All future attempts to match an event trace will operate only against those traces received after this method was invoked.

reinobj formatEventTraces ?begin? ?finish?
begin

An optional number giving the starting trace to include in the output. If missing, then `begin` is taken as 1, the first trace accumulated.

finish

An optional number giving the last trace to include in the output. If missing, then `finish` is taken as the last trace accumulated.

The formatEventTraces method returns a string containing a human readable print out of the received traces.

reinobj discardEventTraces

The discardEventTraces method deletes the set of accumulated event traces.

reinobj traceNotify ?prefix?
prefix

A command prefix.

The traceNotify method returns and optionally sets the command prefix for a command that is executed whenever a state machine trace arrives from a test harness. The prefix argument is optional. If present, then the argument is interpreted as a command prefix and will be invoked with an additional argument as: prefix trace where trace is a dictionary with the trace information. The keys to the trace dictionary are the same as the field names listed in the waitForEventTrace method. If missing, then no changes are made to the notification command. In both cases, the current value of the notification command prefix is returned. Setting the prefix to the empty string, disables trace notification.

reinobj seqDiag ?begin? ?finish?
begin

An optional number giving the starting trace to include in the output. If missing, then `begin` is taken as 1, the first trace accumulated.

finish

An optional number giving the last trace to include in the output. If missing, then `finish` is taken as the last trace accumulated.

The seqDiag method returns a string consisting of text that can be given to plantuml to create a graphical representation of the state machine traces as a UML sequence diagram.

reinobj seqDiagConfig ?option 1 value1 option2 value2 ...?
optionN

An option name used to control details of how sequence diagrams are rendered. Value options are:

-showstates boolean

A boolean option which determines if state information is shown in the swim langes. It set to true, the initial states of the instances are shown at the top of the swimlane and each new state caused by an event transition is shown. Also, the non-transitioning states of "IG" and "CH" are shown when they occur. If set to false, then no state information is displayed in the swimlanes.

-participants list

This option is a list of names of class instances which are to be included in the sequence diagram. Rather than rendering all the events in the sequence diagram, this option provides a way to control which events are shown in the diagram. Only events that are signaled between participants are shown in the diagram. Participant names are of the form class.instance, where class is the name of a class and instance is either a named instance of the initial population or an instance number for dynamically created instances. The special instance, BOUNDARY, is used to show events signaled from outside a state machine context.

valueN

The value of the corresponding option. The type of valueN depends upon the option as described previously.

The seqDiagConfig method sets one or more options used to control the manner in which sequence diagrams are rendered. The return value of the method is the current configuration which is a dictionary of option name keys with corresponding option values.

reinobj seqDiagToChan channel ?begin? ?finish?
channel

The name of a Tcl I/O channel that is writable.

begin

An optional number giving the starting trace to include in the output. If missing, then `begin` is taken as 1, the first trace accumulated.

finish

An optional number giving the last trace to include in the output. If missing, then `finish` is taken as the last trace accumulated.

The seqDiagToChan method writes to a Tcl channel a string consisting of text that can be given to plantuml to create a graphical representation of the state machine traces as a UML sequence diagram.

reinobj seqDiagToFile filename ?begin? ?finish?
filename

The name of a file to which the sequence diagram text is to be written.

begin

An optional number giving the starting trace to include in the output. If missing, then `begin` is taken as 1, the first trace accumulated.

finish

An optional number giving the last trace to include in the output. If missing, then `finish` is taken as the last trace accumulated.

The seqDiagToFile method writes to a file a string consisting of text that can be given to plantuml to create a graphical representation of the state machine traces as a UML sequence diagram.

Instrumentation Traces

In addition to event traces, micca domains produce instrumentation traces. During code generation, micca inserts trace statements into state activities and other functions. The traces statements are actually "C" pre-processor macros which, by default, produce instrumentation output of the function name, the file containing the function, and line number. This gives a record which functions in the the domain are executed. In addition, the MRT_DEBUG macro, which has the same interface as printf(), is available to activities for generating instrumentation output. In a test harness, the instrumentation output is directed to the harness communications port and the methods in this section define the operations that can be applied to instrumentation traces.

reinobj instr ?on | off?
on | off

Turn tracing either on or off. In all cases, the command returns the current state of instrumentation tracing.

The instr method controls whether instrumentation traces are output from the test harness and accumulated.

reinobj waitForInstrTrace ?field1 pattern1 field2 pattern2 ...?
fieldN

The name of a field of the instrumentation trace. Valid field names are:

time

A timestamp of when the trace was generated.

message

The text of the instrumentation trace message.

patternN

The corresponding pattern to match for the given key. Patterns may be of any form accepted by the string match command.

The waitForInstrTrace method suspends execution until a instrumentation trace matches the given parameters or a timeout occurs.

reinobj clearInstrTraceCache

The clearInstrTraceCache method deletes any accumulated instrumentation traces contained in the instrumentation trace cache. All future attempts to match an instrumentation trace will operate only against those traces received after this method was invoked.

reinobj formatInstrTraces ?begin? ?finish?
begin

An optional number giving the starting trace to include in the output. If missing, then `begin` is taken as 1, the first trace accumulated.

finish

An optional number giving the last trace to include in the output. If missing, then `finish` is taken as the last trace accumulated.

The formatInstrTraces method returns a string containing a human readable print out of the received instrumentation traces.

reinobj discardInstrTraces

The discardInstrTraces method deletes the set of accumulated instrumentation traces.

reinobj instrNotify ?prefix?
prefix

A command prefix.

The instrNotify method returns command prefix for a command that is executed whenever an instrumentation trace arrives from a test harness. The prefix argument is optional. If present, then the argument is interpreted as a command prefix and will be invoked with an additional argument as: prefix instr where instr is a dictionary with the instrumentation information. If missing, then no changes are made to the notification command. In both cases, the current value of the notification command prefix is returned. Setting the prefix to the empty string, disables instrumentation notification.

Fatal Error Traces

The micca run-time code detects several fatal errors. By default, the micca run-time invokes the `abort` function from the "C" standard library. Most implementations of abort cause the process to terminate and dump core for debugging. When running as a test harness, terminating the process is not desirable. We would like to be able to examine the state of things after the fatal error has happened. So, bosal generates code to install its own fatal error handler and this handler allows the test harness communication socket to remain open. The fatal error handle also emits a fatal error message with the details. Note that the fatal error messages are sent asynchronously to any command / response sequence and cannot be tuned off.

reinobj waitForFatalTrace ?field1 pattern1 field2 pattern2 ...?
fieldN

The name of a field of the fatal error trace. Valid field names are:

time

A timestamp of when the trace was generated.

message

The text of the fatal error trace message.

patternN

The corresponding pattern to match for the given key. Patterns may be of any form accepted by the `string match` command.

The waitForFatalTrace method suspends execution until a fatal error trace matches the given parameters or a timeout occurs.

reinobj clearFatalTraceCache

The clearFatalTraceCache method deletes any accumulated fatal error traces contained in the fatal error trace cache. All future attempts to match an fatal error trace will operate only against those traces received after this method was invoked.

reinobj formatFatalTraces ?begin? ?finish?
begin

An optional number giving the starting trace to include in the output. If missing, then `begin` is taken as 1, the first trace accumulated.

finish

An optional number giving the last trace to include in the output. If missing, then `finish` is taken as the last trace accumulated.

The formatFatalTraces method returns a string containing a human readable print out of the received traces.

reinobj discardFatalTraces

The discardFatalTraces method deletes the set of accumulated fatal error traces.

reinobj fatalNotify ?prefix?
prefix

A command prefix.

The fatalNotify method returns command prefix for a command that is executed whenever a fatal error trace arrives from a test harness. The prefix argument is optional. If present, then the argument is interpreted as a command prefix and will be invoked with an additional argument as: prefix fatal where fatal is a dictionary with the fatal error information. If missing, then no changes are made to the notification command. In both cases, the current value of the notification command prefix is returned. Setting the prefix to the empty string, disables fatal error notification.

Saving Traces

Traces received by mecate are accumulated and can be saved. The traces can be serialized to the native format of TclRAL or can be written to a SQLite database.

reinobj saveTraces filename ?ral | sqlite?
filename

The name of the file to which trace data is stored.

ral | sqlite

A string to designate the type of file to which trace data is stored. If ral is given or the option is missing, trace data is stored in the native serialization format of TclRAL. If sqlite is given, then trace data is stored in SQLite database.

The saveTraces method stores any accumulated event, instrumentation and fatal traces to a file.

Keywords

bosal, micca