Apama 10.15.0 | Release Notes | What's New In Apama 10.7.0 | PySys changes in 10.7.0
 
PySys changes in 10.7.0
This release of Apama ships with a new version of PySys, version 1.6.1. The 1.6.0 and 1.6.1 releases contain many enhancements including:
*Several new writers for recording test results, including GitHub Actions support and a writer that produces .zip archives of test output directories.
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.
*Numerous minor usability improvements to the pysys.py command line, project configuration file, and to many PySys helper methods.
*Other enhancements and changes as described below.
New plug-in API
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:
<test-plugin classname="apama.testplugin.ApamaPlugin" alias="apama"/>
You can then access the plug-in's methods using self.apama, for example, to start a correlator:
correlator = self.apama.startCorrelator('testCorrelator', ...)
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:
<writer classname="apama.coverage.EPLCoverageWriter">
<property name="destDir" value="__coverage_epl.${outDirName}"/>

<!-- The following (optional) properties take a comma-separated list,
for example, "**/foo/Bar*.mon, **/baz/*.mon".
See the EPLCoverageWriter API documentation for details on these and
other available configuration parameters.
-->
<property name="srcIncludes" value=""/>
<property name="srcExcludes" value=""/>
</writer>
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:
*APAMA_BIN_DIR
*APAMA_COMMON_JRE
*APAMA_LIBRARY_VERSION
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:
<property name="APAMA_BIN_DIR" value="${env.APAMA_HOME}/bin"/>
Other changes affecting compatibility with existing projects
The new PySys release includes some changes in behavior that may affect existing projects. For example:
*Stricter checking of project configuration files so that mistakes are easier to spot.
*Checks to prevent dangerous practices like editing os.environ during test execution.
*Removal of support for descriptor.xml/.pysystest.xml (all tests should now be defined with a pysystest.xml file).
*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.
Deprecated APIs
See Removed and deprecated features in 10.7.0 for a list of all PySys APIs that are deprecated in this release.