[py-svn] r33536 - py/dist/py/documentation

[fijal at codespeak.net]

Author: fijal
Date: Sun Oct 22 15:45:58 2006
New Revision: 33536

Added:
   py/dist/py/documentation/test-distributed.txt   (contents, props changed)
Log:
Added document describing distributed tests implementation details.


Added: py/dist/py/documentation/test-distributed.txt
==============================================================================
--- (empty file)
+++ py/dist/py/documentation/test-distributed.txt	Sun Oct 22 15:45:58 2006
@@ -0,0 +1,69 @@
+=======================================================
+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). Options available are varying, I'll try to
+write them down later.
+
+
+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.
+
+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
+
+Implemented features:
+=====================
+
+Actually most of normal py.test features are implemented in distributed
+version. These are command line options: -v -x -k --pdb (only for LSession).
+Missing options are -s (makes sense for LSession, easy), --exec (moderatly
+easy for L/R Sessions), --pdb for RSession (with screen, unsure if it'll
+be implemented). 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 (but I'm not sure whether anyone really wants to use it - it's
+just a cool feature).
+
+.. _`box.py`: http://codespeak.net/svn/py/dist/py/test/rsession/box.py