API Reference

Test runner

zope.testrunner.run(defaults=None, args=None, script_parts=None, cwd=None, warnings=None)

Main runner function which can be and is being used from main programs.

Will execute the tests and exit the process according to the test result.

Changed in version 4.8.0: Add the warnings keyword argument. See zope.testrunner.runner.Runner

zope.testrunner.run_internal(defaults=None, args=None, script_parts=None, cwd=None, warnings=None)

Execute tests.

Returns whether errors or failures occured during testing.

Changed in version 4.8.0: Add the warnings keyword argument. See zope.testrunner.runner.Runner

class zope.testrunner.runner.Runner(defaults=None, args=None, found_suites=None, options=None, script_parts=None, cwd=None, warnings=None)

Bases: object

The test runner.

It is the central point of this package and responsible for finding and executing tests as well as configuring itself from the (command-line) options passed into it.

Changed in version 4.8.0: Add the warnings keyword argument. If this is None (the default) and the user hasn’t configured Python otherwise with command-line arguments or environment variables, we will enable the default warnings, including DeprecationWarning, when running tests. Otherwise, it can be any string acceptable to warnings.simplefilter() and that filter will be in effect while running tests.

register_tests(tests)

Registers tests.

run_tests()

Run all tests that were registered.

Returns True if there where failures or False if all tests passed.

Add unit and functional testing support to setuptools-driven eggs.

zope.testrunner.eggsupport.skipLayers(suite, _result=None)

Walk the suite returned by setuptools’ testloader.

o Skip any tests which have a ‘layer’ defined.

class zope.testrunner.eggsupport.SkipLayers

Bases: ScanningLoader

Load only unit tests (those which have no layer associated with them).

• Running the tests using ‘setup.py test’ cannot, by default, drive the full testrunner, with its support for layers (in functional tests). This loader allows the command to work, by running only those tests which don’t need the layer support.

• To run layer-dependent tests, use ‘setup.py ftest’ (see below for adding the command to your setup.py).

• To use this loader your package add the following your ‘setup()’ call:

  setup(
      ...
      setup_requires=[
          'eggtestinfo' # captures testing metadata in EGG-INFO
      ],
      tests_require=['zope.testrunner', ],
      ...
      test_loader='zope.testrunner.eggsupport:SkipLayers',
      ...
  )
  

loadTestsFromModule(module)

Return a suite of all tests cases contained in the given module

If the module is a package, load tests from all the modules in it. If the module has an additional_tests function, call it and add the return value to the tests.

loadTestsFromNames(testNames, module)

Return a suite of all test cases found using the given sequence of string specifiers. See ‘loadTestsFromName()’.

class zope.testrunner.eggsupport.ftest(dist, **kw)

Bases: test

Run unit and functional tests after an in-place build.

• Note that this command runs all tests (unit and functional).

• This command does not provide any of the configuration options which the usual testrunner provided by ‘zope.testrunner’ offers: it is intended to allow easy verification that a package has been installed correctly via setuptools, but is not likely to be useful for developers working on the package.

• Developers working on the package will likely prefer to work with the stock testrunner, e.g., by using buildout with a recipe which configures the testrunner as a standalone script.

• To use this in your package add the following to the ‘entry_points’ section:

  setup(
      ...
      setup_requires=[
          'zope.testrunner',
          'eggtestinfo' # captures testing metadata in EGG-INFO
      ],
      ...
  )
  

Construct the command for dist, updating vars(self) with any keyword parameters.

initialize_options()

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

finalize_options()

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.