pysys.xml.descriptor

The TestDescriptor class holds metadata for each testcase (pysystest.xml) or directory (pysysdirconfig.xml), and the DescriptorLoader class allows customization of the test discovery process.

TestDescriptor

class pysys.xml.descriptor.TestDescriptor(file, id, type='auto', state='runnable', title='(no title)', purpose='', groups=[], modes=[], classname='PySysTest', module='run', input='Input', output='Output', reference='Reference', traceability=[], executionOrderHint=0.0, skippedReason=None, testDir=None, isDirConfig=False, userData=None)

Bases: object

Descriptor metadata for an individual testcase (pysystest.xml) or defaults for tests under a directory subtree (pysysdirconfig.xml).

The DescriptorLoader class is responsible for determining the available descriptor instances.

Variables

• file (str) – The absolute path of the testcase descriptor file.

• testDir (str) – The absolute path of the test, which is used to convert any relative paths into absolute paths.

• id (str) – The testcase identifier, or the id prefix if this is a directory config descriptor rather than a testcase descriptor. Includes a mode suffix if this is a multi-mode test and supportMultipleModesPerRun=True.

• idWithoutMode (str) – The raw testcase identifier with no mode suffix.

• type (str) – The kind of test this is (auto or manual)

• skippedReason (str) – If set to a non-empty string, indicates that this testcase is skipped and provides the reason. If this is set then the test is skipped regardless of the value of state.

• state (str) – The state of the testcase (runnable, deprecated or skipped). This field is deprecated - we recommend using skippedReason instead, which provides a descriptive outcome to explain why.

• title (str) – The one-line title summarizing this testcase.

• purpose (str) – A detailed description of the purpose of the testcase.

• groups (list[str]) – A list of the user defined groups the testcase belongs to.

• modes (list[str]) – A list of the user defined modes the testcase can be run in.

• primaryMode (str) – Specifies the primary mode for this test id (which may be None if this test has no modes). Usually this is the first mode in the list.

• mode (str) – Specifies which of the possible modes this descriptor represents or None if the the descriptor has no modes. This field is only present after the raw descriptors have been expanded into multiple mode-specific descriptors, and only if supportMultipleModesPerRun=True. Note that after a descriptor is created from the on-disk file, the mode attribute is not set until the later phase when multi-mode descripors are cloned and expanded based on the selected modes.

• classname (str) – The Python classname to be executed for this testcase.

• module (str) – The path to the python module containing the testcase class. Relative to testDir, or an absoute path.

• input (str) – The path to the input directory of the testcase. Relative to testDir, or an absoute path.

• output (str) – The path to the output parent directory of the testcase. Relative to testDir, or an absoute path.

• reference (str) – The path to the reference directory of the testcase. Relative to testDir, or an absoute path.

• traceability (list) – A list of the requirements covered by the testcase.

• executionOrderHint (float) – A float priority value used to determine the order in which testcases will be run; higher values are executed before low values. The default is 0.0.

• isDirConfig (bool) – True if this is a directory configuration, or False if it’s a normal testcase.

• userData (dict(str,obj)) – A dictionary that can be used for storing user-defined data in the descriptor. In a pysystest.xml, this can be populated by one or more user-data elements e.g. <data><user-data name="key" value="val"</user-data></data>.

toDict()

Converts this descriptor to an (ordered) dict suitable for serialization.

DescriptorLoader

class pysys.xml.descriptor.DescriptorLoader(project, **kwargs)

Bases: object

This class is responsible for locating and loading all available testcase descriptors.

A custom DescriptorLoader subclass can be provided to customize the test discovery process, typically by overriding loadDescriptors and modifying the returned list of descriptors and configuring your pysysproject.xml with:

<descriptor-loader module="mypkg.custom" classname="CustomDescriptorLoader"/>

You could use this approach to add additional descriptor instances to represent non-PySys testcases found under the search directory, for example based on discovery of unit test classes.

Another key use case would be dynamically adding or changing descriptor settings such as the list of modes for each testcase or the executionOrderHint, perhaps based on a per-group basis. For example, you could modify descriptors in the “database-tests” group to have a dynamically generated list of modes identifying the possible database servers supported without having to hardcode that list into any descriptor files on disk, and allowing for different database modes on different platforms.

Variables

project (pysys.xml.project.Project) – The pysys.xml.project.Project instance.

_handleSubDirectory(dir, subdirs, files, descriptors, parentDirDefaults, **kwargs)

Overrides the handling of each sub-directory found while walking the directory tree during loadDescriptors.

Can be used to add test descriptors, and/or add custom logic for preventing PySys searching a particular part of the directory tree perhaps based on the presence of specific files or subdirectories within it.

This method is called before directories containing pysysignore files are stripped out.

Parameters

• dir (str) – The full path of the directory to be processed. On Windows, this will be a long-path safe unicode string.

• subdirs (list[str]) – a list of the subdirectories under dir, which can be used to detect what kind of directory this is, and also can be modified by this method to prevent other loaders looking at subdirectories.

• files (list[str]) – a list of the files under dir, which can be used to detect what kind of directory this is, and also can be modified by this method to prevent other loaders looking at them.

• descriptors (list[TestDescriptor]) – A list of TestDescriptor items which this method can add to if desired.

• parentDirDefaults (TestDescriptor) – A TestDescriptor containing defaults from the parent directory, or None if there are none. Test loaders may optionally merge some of this information with test-specific information when creating test descriptors.

• kwargs (dict) – Reserved for future use. Pass this to the base class implementation when calling it.

Returns

If True, this part of the directory tree has been fully handled and PySys will not search under it any more. False to allow normal PySys handling of the directory to proceed.

_parseTestDescriptor(descriptorfile, parentDirDefaults=None, isDirConfig=False, **kwargs)

Parses a single descriptor file (typically an XML file) for a testcase or directory configuration and returns the resulting descriptor.

Parameters

• descriptorfile – The absolute path of the descriptor file.

• parentDirDefaults – A TestDescriptor instance containing defaults to inherit from the parent directory, or None if none was found.

• isDirConfig – False for normal test descriptors, True for a directory configuration.

Returns

The TestDescriptor instance, or None if none should be added for this descriptor file. Note that subclasses may modify the contents of the returned instance.

Raises

UserError – If the descriptor is invalid and an error should be displayed to the user without any Python stacktrace. The exception message must contain the path of the descriptorfile.

loadDescriptors(dir, **kwargs)

Find all descriptors located under the specified directory, and return them as a list.

Subclasses may change the returned descriptors and/or add additional instances of their own to the list after calling the super implementation:

descriptors = super(CustomDescriptorLoader, self).loadDescriptors(dir, **kwargs)
...
return descriptors

Parameters

dir – The parent directory to search for runnable tests.

Returns

List of pysys.xml.descriptor.TestDescriptor objects which could be selected for execution.

If a test can be run in multiple modes there must be a single descriptor for it in the list returned from this method. Each multi-mode descriptor is later expanded out into separate mode-specific descriptors (at the same time as descriptor filtering based on command line arguments, and addition of project-level execution-order), before the final list is sorted and passed to pysys.baserunner.BaseRunner.

The order of the returned list is random, so the caller is responsible for sorting this list to ensure deterministic behaviour.

Return type

list

Raises

UserError – Raised if no testcases can be found.