metaprogramming and politics

I just merged the plugin branch and am very happy about it. Part of the effort was driven by moving core functionality to become a plugin: Terminal reporting is now fully a plugin, contained in a single file including tests. It does it work solely by looking at testing events. Plugins can also add new aspects to tests files – for example the pytest_restdoc.py plugin adds ReST syntax, referential integrity and URL checking for Text files. (I used it for checking my blog post and its links, btw).

Pytest’s good old conftest.py files are still useful: you can define project or directory specific settings, including which plugins to use. For now, many old extensions should work unmodified, as exemplified by PyPy‘s extensive conftest.py files. It’s easy to port a conftest file to a plugin. In fact, you can first define a local "ConftestPlugin" and later move it to become a cross-project one – a matter of renaming the file and the class, done!

To serve as guiding examples, I drafted some initial plugins and implemented neccessary hooks within py.test core.

• pytest_unittest.py: collects traditional unittest.py based tests.
• pytest_xfail.py: marks tests as "expected to fail" and reports them specially.
• pytest_pocoo.py: supplying -P will send failures to http://paste.pocoo.org and report URLs to the terminal.

If you wan’t to get a feel on how plugins are implemented, here is the pytest_eventlog.py plugin which adds a command line option to allow logging of all testing events. It’s instructive to look at how it’s done as well as the output because it shows which testing events are generated.

class EventlogPlugin:
    """ log pytest events to a file. """

    def pytest_addoption(self, parser):
        parser.addoption("--eventlog", dest="eventlog",
            help="write all pytest events to the given file.")

    def pytest_configure(self, config):
        eventlog = config.getvalue('eventlog')
        if eventlog:
            self.eventlogfile = open(eventlog).open('w')

    def pytest_unconfigure(self, config):
        if hasattr(self, 'eventlogfile'):
            self.eventlogfile.close()
            del self.eventlogfile

    def pyevent(self, eventname, *args, **kwargs):
        if hasattr(self, 'eventlogfile'):
            print >>self.eventlogfile, eventname, args, kwargs
            self.eventlogfile.flush()

This plugin code is complete, except that the original pytest_eventlog.py file contains tests. The eventlog plugin methods above are called in the following way:

• def pytest_addoption(self, parser) is called before
  commandline arguments are parsed.
• def pytest_configure(self, config) is called after parsing
  arguments and before any reporting, collection or running
  of tests takes place.
• def pytest_event(self, eventname, *args, **kwargs) is called
  for each testing event. Events have names and come with
  arguments which are supplied by the event producing site.
• def pytest_unconfigure(self, config) is called after
  all test items have been processed.

If you want to start writing your own plugin, please use an svn checkout of:

http://codespeak.net/svn/py/trunk/

and activate it by e.g. python setup.py develop.

If you want to write a plugin named pytest_XYZ, you can tell pytest to use it by setting the environment variable PYTEST_PLUGINS=XYZ or by putting pytest_plugins = 'xyz' into a test module or conftest.py file.

A good way to contribute is to copy an existing plugin file to your home dir and put it somewhere into your PYTHONPATH. py.test will use your version instead of the default one and you can play with it untill you are happy (and see to also add some tests showing the new behaviour).

If you have questions or problems, you are invited to post here or to the py-dev mailing list. I’d definitely like to pluginize more of pytest and add hooks as needed and am happy for feedback and suggestions before i freeze the API for 1.0.

holger

py.test just grew a new way to provide test state for a test function. First the problem: those of us dealing with writing tests in the hundreds or thousands usually setup test state at class, method or module level. Then we access it indirectly, through self, local or global helper functions. For larger applications, this usually leads to scattered, complex and boilerplatisch test code. This then stands in the way of refactoring the original code base … but wait, weren’t tests meant to ease refactoring, not hinder it?

Here is the idea: Python Test functions use their function definition to state their needs and the test tools calls a function that provides the value. For example, consider this test function:

   def test_ospath(self, tempdir):
      # needs tempdir to create files etc.

.

py.test provides the value for tempdir by calling a matching method that looks like this:

  def pytest_pyfuncarg_tempdir(pyfuncitem):
      # use pyfuncitem to access test context, cmdline opts etc.

.

This matching provider function returns a value for tempdir that is then supplied to the test function. For more complex purposes, the pyfuncitem argument provides full access to the test collection process including cmdline options, test options, project specific configuration. You can write down this provider method in the test
module, in configuration files or in a plugin.

Once i started using this new paradigm, i couldn’t resist and refactored pytest’s own tests to use the new method everywhere. Here are my findings so far:

• self contained test functions: i don’t need to wade through unneccessary layers and indirection of test setup.
• fewer imports: my test modules don’t need to import modules that are only needed for setting up application state.
• easy test state setup: I can place test support code in one place and i can grep for pytest_pyfuncarg_NAME. I can reuse this setup code easily across modules, directories or even projects. Think about providing test database object or mocking objects.
• more flexible test grouping: I can logically group tests however i like, independently from test setup requirements. I found it very easy to shuffle test functions between classes or modules because they are rather self-contained.