PySys changes in 10.7.0

You may wish to copy some of the new writers from the APAMA_HOME/samples/pysys/pysysproject.xml file into your own projects to benefit from these, or see the PySys documentation in the API Reference for Python for more information.

A new BaseTest.assertThatGrep() method that extracts a value using a grep expression and then allows asserting its value is as expected. For extract-and-assert use cases, this approach gives much clearer messages when the assert fails than using assertGrep.

PySys 1.6.0 introduces a new plug-in API that provides a simpler and more modular way to share application-specific utility methods across multiple tests than the traditional approach of creating custom BaseTest and BaseRunner classes. Apama makes use of this to provide a new ApamaPlugin that provides easier access to Apama functionality. To use it, just add this to your pysysproject.xml:

You can then access the plug-in's methods using self.apama, for example, to start a correlator:

New way of configuring EPL code coverage reporting

There is a new and easier way to configure EPL code coverage reporting. Just remove the references to ApamaRunner (now deprecated) from your pysysproject.xml and replace them with:

See the EPLCoverageWriter class in the API Reference for Python for more details.

New way of validating Apama events sent by your application

Your PySys tests can now validate the events that are sent out of your Apama application in a new way. The previous approach of validating the output of the engine_receive tool using assertDiff or assertGrep/assertOrderedGrep regular expressions has several disadvantages including uninformative error messages when the match fails, and no easy way to extract the information of interest from complex Apama events. Instead we now introduce a new way to check the events: instead of CorrelatorHelper.receive(evt, channels= [...] ), call CorrelatorHelper.injectTestEventLogger(channels=[...]) to request a message to be written to the correlator log when an event is sent to the specified channels, and then in your validate() method, use ApamaPlugin.extractEventLoggerOutput(logfile) to get a list of events as a standard Python dictionary. For example:

sensor1_temps = [
# Extract only the field value(s) we care about
# (allows us to ignore unimportant information, timestamps, etc):
(evt['temperature'])
for evt in self.apama.extractEventLoggerOutput('testCorrelator.log')

# Filter to include the desired subset of events:
if evt['.eventType']=='apamax.myapp.Alert' and evt['sensorId']=='TempSensor001'
]
self.assertThat('sensor1_temps == expected',
sensor1_temps=sensor1_temps, expected=[
111.0,
120,
145.2,
])

For a concrete example, see Apama_cor_001 in the samples/pysys directory of your Apama installation.

Property settings affecting compatibility with existing projects

In previous versions of the Apama PySys helper classes, the following properties were set on the project object:

As of this version, these properties are no longer set on the project object, except if they are set in the pysysproject.xml file. All uses of APAMA_BIN_DIR and APAMA_LIBRARY_VERSION have been removed from the helper classes. APAMA_COMMON_JRE is still read from the pysysproject.xml file, but is not set on the project otherwise.

If the above three properties are not set in the pysysproject.xml file, a relative directory to APAMA_HOME is now used by default. If you have any PySys tests which explicitly use the above properties, for example, self.project.APAMA_BIN_DIR, then we recommend you rewrite them to use a path relative to self.project.APAMA_HOME instead. As a workaround, you can replicate the original behavior by providing this property in your pysysproject.xml file:

Other changes affecting compatibility with existing projects

The new PySys release includes some changes in behavior that may affect existing projects. For example:

Changes to several project properties (such as defaultAbortOnError) to match best practice and avoid the need for new projects to copy a long list of properties just to get the recommended behavior.

As a result, some existing PySys projects will need changes to work with the new PySys release. However, in most cases this will just require copying in some properties to pysysproject.xml (to maintain the previous behavior) and perhaps adding default="..." values for any optional properties, but significant changes to test cases are unlikely to be needed. For full details of how to migrate an existing test project to the new release, including the project properties that you may need to copy in to retain existing behavior, see PySys Test Framework > Change Log in the API Reference for Python.