Apama 10.15.4 | Release Notes | What's New in Apama 10.11.0 | PySys changes in 10.11.0
 
PySys changes in 10.11.0
This release of Apama ships with a new version of PySys, version 2.0.
New PySys features
The 2.0 release contains many enhancements including:
*A new standard test structure that avoids the use of XML by allowing descriptor values such as the test title to be specified alongside your Python test class in a single pysystest.py file, instead of separate run.py and pysystest.xml files. You can mix and match the old and new styles within the same project. For new PySys projects, a simpler directory layout is now recommended in which the self.input directory is configured to be the main testDir/ (which also contains the pysystest.py file) instead of having a separate testDir/Input/ subdirectory for input files. This can make test contents easier to navigate.
*Some big extensions to the concept of modes that allow for more powerful configuration and use, including mode parameters for easier handling of multi-dimensional modes, and dynamic mode lists configured with a Python lambda expression.
*A new template-based implementation of pysys make, allowing easy configuration of how new tests are created - on a per-directory basis - and also automatic generation of test identifiers for new tests (when using numeric identifiers).
*Several improvements to the pysys.mappers API for more easily transforming text files during copy and grep operations, including support for multi-line exception stack traces.
*A large set of smaller additions, many based on end-user requests.
For more information on the above and also details on the many smaller enhancements in this PySys release, see the PySys Change Log (PySys Test Framework > Change Log in the API Reference for Python).
New Apama helper features
There are several improvements to the Apama helper classes for PySys in this release:
*The ApamaPlugin class (self.apama) has a new method JoinEPLStackLines which can be used in an assertGrep(..., mappers=[...]) list to convert multi-line EPL stack dumps to a single line. This can make it easier to ignore expected errors while still checking for unanticipated errors. For example:
self.assertGrep('testCorrelator.log', '(ERROR|FATAL|Failed to parse) .*', contains=False, 
mappers=[self.apama.JoinEPLStackLines(), pysys.mappers.JoinLines.JavaStackTrace()])
See Apama Helper Classes for PySys in the API Reference for Python for more information. 
*The CorrelatorHelper and IAFHelper classes have a new method waitForLogGrep which (much like waitForGrep) can be used to wait for a log message to appear in the log file, but with automatic checking for errors and an early abort with a clear outcome reason if an error is detected. For example:
correlator.waitForLogGrep('INFO .* Test completed')
*The ApamaPlugin class (self.apama) has a new field defaultLogIgnores which holds a list of project-level regular expressions that should be ignored when checking for errors, warnings and other messages in Apama component logs. The default value contains a small set of WARN messages which should be ignored in testcases. Additional ignores can be added to this list with a multi-line list of regular expressions in your pysysproject.xml configuration:
<property name="apamaDefaultLogIgnores">
WARN .*My warning to ignore
ERROR .*My error to ignore
</property>
*It is recommended to add at least one maker-template to your pysysproject.xml file to provide a good starting point when creating new testcases using pysys make. A default Apama test template is provided with the product which includes some typical PySysTest commands. You should delete any aspects not needed in your testcase. To make this template available in existing projects, just add the following XML to your pysysproject.xml file:
<pysysproject>
<pysysdirconfig>
<maker-template name="apama-default-test"
description="a test for an Apama application that runs in a local correlator"
copy="${pysysTemplatesDir}/apama-default-test/*"
/>
</pysysdirconfig>
</pysysproject>
Breaking changes
There are a several changes that could require changes to existing PySys projects. A full list is provided in the PySys Change Log, but the main ones are summarized below:
*When user-defined mappers= are used (for example, during self.copy), it is now an error for a mapper to strip off the trailing \n character at the end of each line, as failure to do so can have unintended consequences on later mappers. This requirement is also more clearly documented.
*Some mistakes in the pysystest.xml structure that were previously tolerated will now produce stderr warning messages (for example, incorrectly nesting <modes> inside <groups>) and others will produce a fatal error (for example, multiple occurrences of the same element). To find out if any tests need fixing up, just execute pysys print in your PySys project directory and act on any warning or error messages.
*The deprecated supportMultipleModesPerRun=false project property (only used in very old PySys projects) can no longer be used. Please change your tests to use the modern modes approach instead.
*On Windows, the testDir (and the input, output, and reference directories) no longer start with the \\?\ long path prefix. Instead, this can be added for operations where it is needed using pysys.utils.fileutils.toLongPathSafe (as the standard PySys methods already do, for example self.copy). Where possible, it is recommended to avoid nesting tests and output directories so deeply that long path support is needed.
In addition, your tests may be subject to breaking changes from the upgrade to Python 3.9. See also Python upgrade in 10.11.0.
Deprecations
*It is strongly recommended to use the new pysys.constants.PREFERRED_ENCODING constant instead of Python's built-in locale.getpreferredencoding() function, to avoid thread-safety issues in your tests.
*If you have a custom pysys.utils.perfreporter.CSVPerformanceReporter subclass, the signatures for pysys.utils.perfreporter.CSVPerformanceReporter.getRunDetails and pysys.utils.perfreporter.CSVPerformanceReporter.getRunHeader have changed to include a testobj parameter.
Although this should not immediately break existing applications, to avoid future breaking changes, you should update the signature of those methods if you override them to accept testobj and also any arbitrary **kwargs that may be added in future.
*The pysys.xml module is deprecated. Use pysys.config instead.
*The pysys.utils.fileunzip module is deprecated. Use BaseTest.unpackArchive instead. For example, replace unzip(gzfilename, binary=True) with self.unpackArchive(gzfilename, gzfilename[:-3]).
*The (undocumented) DEFAULT_DESCRIPTOR constant is now deprecated and should not be used.
*The old <mode> elements are deprecated in favor of the new Python lambda syntax (support for these will not be removed any time soon, but are discouraged for new tests).
*The pysys.utils.pycompat module is now deprecated.
*The ConsoleMakeTestHelper class is now deprecated in favor of pysys.launcher.console_make.DefaultTestMaker.
*If your pysysproject.xml contains an APAMA_COMMON_JRE property with its default value set to ${APAMA_HOME}/../jvm/jvm/jre, you should either remove the property or change the default value to ${APAMA_HOME}/../jvm/jvm as the /jre directory has been removed in this release of Apama. 
A quick way to check for the removed and deprecated items in your test project is to use the regular expression as shown in the following grep command:
grep -r "\(supportMultipleModesPerRun.*alse\|DescriptorLoader\|pysys.utils.loader\|_stringToUnicode\|pysys[.]xml\|pysys.utils.fileunzip\|[^_@]DEFAULT_DESCRIPTOR\|pysys.utils.pycompat\|PY2\|string_types\|binary_type\|isstring[(]\|quotestring[(]\|openfile[(]\|ConsoleMakeTestHelper\|def getRunDetails\|def getRunHeader\|locale.getpreferredencoding\|addResource\|CommonProcessWrapper\|TEST_TEMPLATE\|DESCRIPTOR_TEMPLATE\|ThreadFilter\|/jvm/jvm/jre\)" .