=======================================================
The ``py.test`` distributed features - developer's view
=======================================================

.. contents::
.. sectnum::

starting point: new session objects
===================================

There are two new session objects, both located in `rsession.py`_. `RSession`
and `LSession`. `RSession` is responsible for running tests distributedly,
while `LSession` runs tests locally, but with different implementation
details (as well as using details).

Abstraction layers:
===================

Main difference between normal session and `(L|R)Session` is split into
reporter and actual session. Reporter is an object or function (also defined
in `rsession.py`_) which gets all the events (listed in `report.py`_) and
represents them to the user. Default reporter is command line one (to be
precise, there are different reporters for L and R Sessions because of
different needs), but there is existing reporter which runs web server 
(`web.py`_) and communicates over XMLHttp requests with the browser.

Writing down new reporter is relatively easy, way easier than writing session
from a scratch, so one can write down GTK reporter and whatnot.

Only thing to do is to write down new reporter classs which subclasses
`AbstractReporter` in `reporter.py`_ and overrides all the report_Xxx methods
(each of these method is called when one of the message, defined in 
`report.py`_ arrives to reporter). Special consideration is needed when dealing
with ReceivedItemOutcome, which is in details described in `outcome.py`_.

Another abstraction layer (present only in `LSession`) is runner. Actual
object which runs tests. There are two existing runners: box_runner and
plain_runner, both defined in `local.py`_. box_runner can run tests
after fork, so signals are properly handled (you get error instead of
crash of all the program), plain_runner is running in local process, needed
for --pdb command line option for example. There are several different runners
in my mind, like exec_runner (for implementing --exec), apigen_runner, for
creating documentation, benchamrk_runner for benchmarks etc. etc.

.. _`rsession.py`: http://codespeak.net/svn/py/dist/py/test/rsession/rsession.py
.. _`report.py`: http://codespeak.net/svn/py/dist/py/test/rsession/report.py
.. _`web.py`: http://codespeak.net/svn/py/dist/py/test/rsession/web.py
.. _`local.py`: http://codespeak.net/svn/py/dist/py/test/rsession/local.py
.. _`reporter.py`: http://codespeak.net/svn/py/dist/py/test/rsession/reporter.py
.. _`outcome.py`: http://codespeak.net/svn/py/dist/py/test/rsession/outcome.py

Implemented features:
=====================

Actually most of normal py.test features are implemented in distributed
version. Quite missing is testing LSession under 
OSX/Windows or other machines than mine.

Unique features:
================

Besides distribution (which is quite unique for testing framework I guess)
there is boxing code (`box.py`_) which makes possible catching SIGSEGV and
other strange stuff as well as separates memory usage between tests (ie
we're quite sure that memory is not kept allocated during test runs) as long
as it's not gathered during setup/teardown stuff.

Another unique feature is web server which allows you to track down tests and
how they goes.

.. _`box.py`: http://codespeak.net/svn/py/dist/py/test/rsession/box.py