bgtests

tools for automatically triggering test suites.

The bgtests module is accessible via the testtools module.

... for example, continuous integeration or unit testing triggered from a subversion post-commit hook.

Since repositories in real life contain several packages that most likely will not be tested in the exact same way, there is no generic script provided here to trigger test suites.

Defining your own bgtest script is easy though. Here is an example with custom packages

from testtools.bgtests import TestablePackage, run_packages
class MyPackage(TestablePackage):
    svn_path = 'file://%s/widget/trunk'
    ex = 'nosetests -v'
    def recognizes_file(self, filepath, code=None):
        return filepath.startswith('widget/trunk')

run_packages( [MyPackage()], '/path/to/repos', notify='egg@yourface' )

You can fire something like this off very nicely inside a subversion post-commit hook by passing through the repos_root and revision.

The default test command is nosetests, a discovery test runner for python, but any command can be used here.

If you want to run your tests on a machine separate from that which holds your repository, then you can run a SimpleXMLRPCServer using the PackageTestHandler (see its docstring for an example).

Attributes

a STDOUT

-2

a PIPE

-1

Functions

f run(svn_path, out=None, rev=None, test_cmd='nosetests', stream=<open file '<stdout>', mode 'w' at 0x12068>, notify=None, tmp_dir=None, tmp_prefix='tmp_bgtest_', setup=None) ...

runs tests in the background.

exports svn_path (URL to package) into a temp dir and runs test_cmd.

Keyword Arguments:

  • out -- reporter object, will be created otherwise
  • rev -- optional revision to export (head otherwise)
  • test_cmd -- command to run tests with
  • stream -- filelike object for reporter, defaults to sys.stdout
  • notify -- if not empty, results are emailed here
  • tmp_dir -- directory to export into and run tests
  • tmp_prefix -- a unique temporary directory is created with this prefix
  • setup -- a callback to do any setup work once you are in the dir of your project

returns True if test passed, false otherwise.

f run_packages(packages, repos_root=None, rev=None, stream=<open file '<stdout>', mode 'w' at 0x12068>, notify=None, tmp_dir=None, repos_meta=None) ...

runs tests for packages who were affected by the last change in a repository.

gets last changed paths from a repos_meta object to ask each package if it was affected by any one of the file paths. If so, the package's test suite is run in the manner defined by the package.

Arguments:

Keyword Arguments:

  • repos_root -- abs path to base of repository (cannot be a URL); may be omitted in lieu of a repos_meta object
  • rev -- revision to inspect, defaults to None (head of repos)
  • stream -- filelike object for reporter, defaults to sys.stdout
  • notify -- if not empty, results are emailed here
  • tmp_dir -- directory to export into and run tests
  • repos_meta -- instance that provides the interface of SvnInspector

see run for how svn exporting works.

returns True if all tests passed (or none ran), False otherwise.

Classes

C TestablePackage(...) ...

encapsulates a package that can be extracted and tested.

This class contains 8 members.

C Reporter(...) ...

reports the test results.

outputs to a log and/or email address.

Keyword Arguments:

  • stream -- filelike object for reporter
  • notify -- if not empty, results are emailed here
  • export -- svn path we are reporting about
  • revision -- revision we are reporting about
  • header -- gets added to buffer
  • skip_notify -- callback that accepts buffer contents on error and returns True if notification should be skipped
  • em_from -- email From address

This class contains 4 members.

C PackageTestHandler(...) ...

runs test packages via XMLRPC.

a handler designed for SimpleXMLRPCServer .

Example of starting the server:

pkg = TestablePackage(svnpath = 'http://svn.myrepo/')
handler = PackageTestHandler([pkg])
serv = SimpleXMLRPCServer(("localhost", 8000))
serv.register_introspection_functions()
serv.register_instance(handler)
serv.serve_forever()

You send a request to the server and call a method to trigger tests. see trigger_from_svnlook for a concrete example of client/server interaction.

Arguments:

Keyword Arguments:

  • stream -- filelike object for reporter, defaults to sys.stdout
  • notify -- if not empty, results are emailed here
  • tmp_dir -- directory to export into and run tests

This class contains 2 members.

C SvnInspector(...) ...

encapsulates meta data for a repository.

currently this is subversion specific.

Arguments:

  • repos_root -- abs path to base of repository (cannot be a URL)

Keyword Arguments:

  • revision -- inspect this revision (defaults to head)

This class contains 3 members.

See the source for more information.