The pi4soa tools provide a simple mechanism for documenting the specific use cases associated with a business process, and simulating these use cases against the participants (or services) that are derived from a choreography description, to ensure the choreography description correctly caters for the sequence of interactions defined in the scenarios.
The sub-topics within this section of the user guide describe how a scenario is created and simulated against a choreography description.
The scenario is exercised within a single Java process, which directs the example message to the appropriate participants. These messages are then passed through a pi4soa endpoint monitor or runtime that has been configured with the endpoint projection for that participant. The decision as to whether a particular endpoint is monitored or executed is dependent upon the configuration parameters supplied when simulating the scenario. If the 'Simulate and Execute' menu item is selected, then a list of participant types will be presented, which can be ticked to indicate that they should be executed.
Using this approach, the mechanism simulates a sequence of messages being passed between the endpoints for each of the participants. As the message events for each part of an interaction between a pair of participants is defined (i.e. for the send and receive separately), it enables scenarios to be constructed to test failure situations, as well as successful scenarios.
It is possible to use scenarios to ensure that a choreography defines the expected behavior for all participants. It is also possible to ensure that the implementation of specific participants, given a particular sequence of inbound messages (as part of the overall scenario), produce the appropriate expected message results. Thus, it is both possible to ensure the choreography handles a set of required scenarios, as well as perform unit testing of one or more of those participant services using the same scenarios.
To create a new Scenario, the first step is to locate the folder in which the file will be created. This will usually be the same folder as the Choreography Description that is being simulated, or one of its sub-folders. Once this folder has been found (or created), the user should select the 'New...' menu item (on the context menu), as follows:
The user should select the 'Other...' menu item from this menu, which will cause a wizard to be displayed with the various items that can be created. Within the list, there is a sub group with the title 'Choreography'. This group contains an entry called 'Scenario' that should be selected:
The user should then press the 'Next' button to see the following form:
This form enables the user to select both the folder, within which the new Scenario should be created (defaults to the folder previously chosen when invoking the context menu), and the name of the scenario (by default this is My.scenario).
When the 'Finish' button is pressed, a new Scenario file (with the specified name) will be created in the nominated folder. An editor will automatically be opened for the newly created Scenario.
The XML schema for the Scenario file is: scenario.xsd
This can be used to create the XML representation of a Scenario directly.
The first step is to launch the Scenario Editor on a Scenario file (i.e. a file with the .scn extension). This can be achieved by double clicking on the filename. The following image shows an example of the Scenario Editor with the various components of a scenario:
The components within the scenario are:
-
Scenario
This is the top level component within the scenario, and provides the link from the scenario to the CDL model file that this test is associated with.
The 'Choreography Description URL' can represent a URL or the relative path to the local CDL model file (as in the image above). When the scenario is executed, the endpoint projections will be obtained for each of the participant types defined in this referenced CDL model.
The 'Evaluate State' field determines whether the simulation should be based on managing state information, and evaluating expressions against that information, or if not observable messages are used to determine the path through the choreography.
The other attributes associated with the Scenario component are for information purposes only.
-
Event Group
The Event Group component provides a mechanism for organizing sets of message events into appropriate groups. Event groups can also be contained within other event groups, allowing hierarchical organization of the message events.
Using this component, it is possible to group events in a structure that relates to the choreography they are being used to test. Having relevant events grouped in this way means that it is easier to re-organize the sequence of the message events simply by dragging and dropping event groups.
-
Message Event
The message event component is the primary component of interest within the scenario, as it provides the indication that a message has been sent or received by a participant that is being monitored in the test environment. The properties associated with this component are show in the following image, and described in the subsequent table:
Property Description Causes Exception This field is used by the test environment to determine if this message event is intended to be invalid - i.e. not correct in terms of the choreography description. This indication is therefore used to determine whether the choreography error is expected. Channel Id If the choreography description provides a means of identifying the channel instance, based on information contained within the message, then this field is not required. Otherwise an explicit id should be provided to correlate the message to a particular channel instance. Description This field can be used to provide a detailed description of the purpose of the event. Fault Name If the message event relates to a fault. If so, then the name of the fault should be placed in this field. Is Request This field is a boolean value that indicates whether the message event represents a request. If not, it will be considered a response (or fault if the fault name is supplied). Operation Name This is the name of the operation that is to be invoked on the service endpoint. Session Id If the choreography description provides a means of identifying the session instance, based on information contained within the message, then this field is not required. Otherwise an explicit id should be provided to correlate the message to a particular session instance. Value This field can be used to define an XML document that would represent the contents of a message. If the session and channel identity for an associated Choreography Description is based on extracting details from the message content, then this field needs to hold valid data. Value URL This field can be used to reference (via a relative file path or HTTP URL) an XML document that would represent the contents of a message. If the session and channel identity for an associated Choreography Description is based on extracting details from the message content, then this field needs to hold valid data. -
Message Link
The message link has similar properties to the Message Event, with the exception that if a choreography description is associated with the scenario, then the operation, fault, 'is request' and message type fields will be represented by a single Message field instead.
This single field becomes a dropdown menu referencing a message definition within the choreography, that encapsulates the four individual pieces of information that are hidden.
-
Import
It is possible to reference (or import) another scenario into a specific location within another scenario. This enables common sequences of interaction, between the same set of participant types, to be shared amongst many higher level scenarios.
-
Elapsed Time
This component can be used to document elapsed time in a scenario. When simulated, it will cause the state machines managing the state for each participant to have their current time effectively moved forward by the specified amount, which may result in timeouts occurring.
-
Assert or Record State
Currently these scenario components are for documentation purposes only. They can be used by external software to imply additional constraints on the interacting parties.
Note
- The Session and Channel Id fields will not be displayed if the choreography description associated with the scenario uses token locators to determine identities from the message contents.
- The 'Value' and 'Value URL' fields are mutually exclusive, enabling the message event to specify the associated value either directly (inline) or by reference to a file or HTTP URL.
To simulate the scenario, the user should launch the Scenario Editor with the relevant file, and choose the 'Simulate' menu item on the 'Scenario' sub-menu from the context menu (as shown in the following image):
Once the menu item is selected, it will the scenario to be simulated against the associated choreography description. Where a message event is valid, the send or receive icon will turn green.
Where an error is detected, the send or receive icon will turn red.
It is also possible to execute some services, while simulating others, using the 'Simulate and Execute' option from the menu above. When this menu item is selected, a popup window appears with the list of services. The services that should be executed can be ticked. Any services that are left un-checked will be monitored - by default all services are only monitored. To execute a service, the relevant Java generated extensions (and other dependencies) must be fully implemented and available.
When the 'Ok' button is pressed, this will cause the test scenario to be evaluated, which will produce an endpoint projection for each participant, create an endpoint monitor or runtime to operate on each of the endpoint descriptions, and then work through the list of message events defined in the scenario.
The information produced as a result of the execution of the test scenario is displayed in two different forms. The first window (the 'Scenaro Editor' tab) presents the elements of the test scenario as they are evaluated. If they complete successfully, they are displayed in green, otherwise they are shown in red. If an event group contains a message event that resulted in a failure, then it will also turn red (as in the image above).
The second form in which the results from the test scenario evaluation are presented are in the 'SImulation Log' tab. This information is presented as generated by the logging output from the scenario tester. This is in the form of INFO, WARNING and SEVERE (i.e. error) log messages.
To enable the user to identify which tracing output information is related to the element within the Scenario Results display, it is possible to select an item in the Scenario Editor and have the associated tracing output text for the selected item presented in the simulation log.
Log messages are recorded for both the test harness, as it works through the event groups and message events within a scenario, and also from the endpoint monitoring and runtime engines. The test harness produces three types of message, 'processing' to mark the start of processing a scenario element, and 'completed' or 'failed' to mark the end of a particular region of the test scenario (i.e. either the whole scenario, an event group or a particular message event). For example, the messages that would bound the processing of a particular message event would be:
INFO: <processing id="simplerfq-invalid/4/2" text="Message event" />
{other log messages from monitoring or runtime engine}
INFO: <completed id="simplerfq-invalid/4/2" text="Message handled" />
The id attribute in the log messages identifies the index to the relevant item within the scenario. In the above example, this indicates that the message event is in the fourth event group, and is the second message event within that group.
The other logging information, generated from the monitoring or runtime engines, provide tracing that will indicate:
- when a new service session has started
- when an existing service session has finished
- when a message has been sent/received that is valid in relation to the endpoint description
- when a message is sent/received that is not expected in the context of a current service session, and is not appropriate to initiate a new service session