A scenario is an executable test case of a single ruleset, defining the input data it is to execute on and performance tests to apply to the ruleset execution results. Scenarios can be defined in XML, in Rule Studio wizards, and in the Rule Scenario Manager Console.

This section describes the scenario XML definition. Scenario definitions are governed by an XML schema (XSD) file located in <InstallDir>/doc/schemas.

A scenario definition is an XML input file that provides the following information:

The following is an example scenario definition that will be analyzed in the following sections:

<scenario>
  <name>loanValidation XML 1</name>
  <description>loan Validation XML Sample 0</description>
  <configuration>./data/scenario/loanValidationConfigurationXML.xml
    </configuration>
  <baseline-report>loanValidationRef1.xml</baseline-report>
  <request>
    <ruleset-path>/loanvalidationruleapp/1.0/loanvalidationrules/1.0
      </ruleset-path>
    <input-data>loanInput.xml</input-data>
    <filters>
      <filter name="INFO_WORKING_MEMORY" value="true"/>
      <filter name="WORKING_MEMORY_FILTER" value="loan.Borrower"/>
    </filters>
  </request>
  <response>
    <report>loanValidationReport1.xml</report>
    <output-data>loanValidationOutput1.xml</output-data>
  </response>
  <tests>
    <test extractor="CANONICAL_RULESET_PATH" operator="REGEXP">/.*/2\.0/.*/.*
      </test>
    <test extractor="NUM_RULES_FIRED" operator="GT">4</test> 
  </tests>
</scenario>

Name and Description

Each scenario definition includes a name for the scenario, which is required to identify it within scenario suites and in the Rule Scenario Manager Console. The name can be a string of up to 32 characters, avoiding special characters. For example:

<name>loanValidation XML 1</name>

You can also provide a short description for the scenario, although this is optional. For example:

<description>loan Validation XML Sample 0</description>

Configuration

Scenarios are associated with a configuration that determines how the scenario execution proceeds. For example, a configuration specifies the databinding classes required to map the input data to Java objects for ruleset execution.

Each scenario can have a configuration file associated with it. The XML configuration file name and path is set in the scenario definition. For example:

<configuration>./data/scenario/loanValidationConfigurationXML.xml
    </configuration>

It is also possible to define one configuration to apply to all scenarios within a scenario suite or to all scenario suites within a simulation. The higher-level configuration applies to all contained scenarios, except in the case where a lower-level configuration exists. That is, the more granular configuration takes precedence. If no configuration is associated with a scenario, either directly or by way of a scenario suite or simulation configuration, the scenario cannot be executed.

Baseline Report

You can compare the results of a ruleset execution against the results contained in the scenario report of an earlier execution. This allows regression testing of a modified ruleset, by comparing subsequent executions of it to a reference execution.

To test against the values in a reference scenario report, specify the tag <baseline-report-value/> in place of a test value in a test definition. The corresponding value from the specified scenario report is compared to the calculated value extracted from the subsequent execution trace.

To enable this method of testing, a baseline report must be specified in the scenario definition. For example:

<baseline-report>loanValidationRef1.xml</baseline-report>

Ruleset Path

When a scenario is executed, it sends a request to the Scenario Service Provider to execute the ruleset specified in the scenario definition. A ruleset is specified by the path to the RuleApp hosting it. For example:

<ruleset-path>/loanvalidationruleapp/loanvalidationrules</ruleset-path>

It is also possible to include version numbers explicitly to execute a specific version of RuleApp/ruleset. For example:

<ruleset-path>/loanvalidationruleapp/1.0/loanvalidationrules/1.0
    </ruleset-path>

Input Data

The input data on which a scenario's ruleset is executed can be supplied in a number of formats:

In the scenario definition, you give the path and name of the data file. For example:

<input-data>loanInput.xml</input-data>

Filters

You can apply filters to the data returned by the Scenario Service Provider to the execution trace. Filtering out unneeded data can improve execution performance.

By default, all filters but one are enabled. The INFO_WORKING_MEMORY filter is disabled by default, owing to the large amount of data that it can return. It must be turned on manually as follows:

<filter name="INFO_WORKING_MEMORY" value="true"/>

In addition, you can apply a specific filter to the working memory data. The WORKING_MEMORY_FILTER is an inclusion filter, composed of a comma-separated list of classnames. For the filter to work, the INFO_WORKING_MEMORY filter must be set to true. An example is shown in the list below.

The filters available are the following:

<filter name="INFO_NUM_RULES_FIRED" value="true"/>
<filter name="INFO_NUM_TASKS_EXECUTED" value="true"/>
<filter name="INFO_RULES_FIRED" value="true"/>
<filter name="INFO_TASKS_EXECUTED" value="true"/>
<filter name="INFO_NUM_RULES_NOT_FIRED" value="true"/>
<filter name="INFO_NUM_TASKS_NOT_EXECUTED" value="true"/>
<filter name="INFO_RULES_NOT_FIRED" value="true"/>
<filter name="INFO_TASKS_NOT_EXECUTED" value="true"/>
<filter name="INFO_EXECUTION_DURATION" value="true"/>
<filter name="INFO_OUTPUT_PARAMETERS" value="true"/>
<filter name="INFO_WORKING_MEMORY" value="true"/>
<filter name="WORKING_MEMORY_FILTER" value="loan.Borrower"/>

Scenario Report

At the end of a scenario execution, the results are collected into a scenario report, which can be in XML or Excel format, and HTML format in the Console. A report contains the following results:

In a scenario definition, you supply the name of the file that will contain this report. For example:

<report>loanValidationReport1.xml</report>

Output Data

When a ruleset is executed, the rule engine may return output data. This data can be stored during a scenario execution in XML or Excel format, and applied in a scenario's tests.

In a scenario definition, you supply the name of the file that will contain the output data. For example:

<output-data>loanValidationOutput1.xml</output-data>

Tests

The results of a ruleset execution can be compared to given values to gain an impression of the performance of the rules. Within scenario definitions, these comparisons are performed by tests, composed of the following elements:

For example:

<tests>
  <test extractor="CANONICAL_RULESET_PATH" operator="REGEXP">/.*/2\.0/.*/.*
      </test>
  <test extractor="NUM_RULES_FIRED" operator="GT">4</test>
</tests>

Test against a baseline report

In place of a specific test value, you can test calculated results against the results contained in a baseline report. The test comparison is then made between the value extracted from the execution trace and the corresponding value in the report of a reference scenario execution. This method of regression testing is set by specifying <baseline-report-value/> in place of an explicit test value in a test definition.

For example:

<tests>
  <test extractor="NUM_TASKS_EXECUTED"
     operator="EQUALS"><baseline-report-value/></test>
</tests>

Example of Generating Input Parameter Files from an Object Model

In the basics-javabinding sample, the class myPackage.MyInOutParametersJUnit contains the testInputParameterHelperForXML method, which shows how to generate XML input parameters with the Rule Scenario Manager API, and the method testInputParameterHelperForExcel, which shows how to generate Excel input parameters with the API.

Related Concepts

Related Tasks

Related Reference

Related Samples