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

[hpk at codespeak.net]

Author: hpk
Date: Tue Jan  9 11:03:49 2007
New Revision: 36321

Modified:
   py/dist/py/documentation/index.txt
   py/dist/py/documentation/test.txt
Log:
some test documentation rework (particularly the
distributed part)


Modified: py/dist/py/documentation/index.txt
==============================================================================
--- py/dist/py/documentation/index.txt	(original)
+++ py/dist/py/documentation/index.txt	Tue Jan  9 11:03:49 2007
@@ -1,7 +1,7 @@
 py.test and the py lib - documentation 
 ---------------------------------------- 
 
-`py.test`_ introduces to the new'n'easy **py.test** utility
+`py.test`_ introduces to the **py.test** testing utility
 
 `py.execnet`_ an innovative way to distribute programs across the net (not stable on win32 yet) 
 

Modified: py/dist/py/documentation/test.txt
==============================================================================
--- py/dist/py/documentation/test.txt	(original)
+++ py/dist/py/documentation/test.txt	Tue Jan  9 11:03:49 2007
@@ -659,27 +659,40 @@
 .. _`py-dev mailing list`: http://codespeak.net/mailman/listinfo/py-dev 
 
 
-Distributed Testing
-===================
+Automated Distributed Testing
+==================================
 
-If you have a project with a large number of tests, and you have several
-machines available ``py.test`` can now speed up your test runs. 
+If you have a project with a large number of tests, and you have 
+machines accessible through SSH, ``py.test`` can distribute
+tests across the machines.  It does not require any particular
+installation on the remote machine sides as it uses `py.execnet`_ 
+mechanisms to distribute execution.  
+
+*Warning*: support for distributed testing is in alpha state 
+and its mechanics and configuration options may change without 
+prior notice.   
 
 Benefits
 --------
 
-The main benefit is speed. There is some overhead required to setup the test
-environment on the remote machines, but if the project has a lot of tests and
-several machines available, the speed up can be quite good. The more machines
-available, the better results you will get. 
-
-Distributing the tests can be also be useful if you need to use remote resouces
-which you do not have locally (perhaps a server has much more RAM or disk
-available). Of course, you could also just ssh into the remote server and run
-``py.test`` there, but only for committed changes. You really don't want to
-manually copy your sources every time you make a change, do you? 
-
-Also, the web interface is quite helpful. 
+The main benefit for using distributed testing is speed. There
+is some runtime overhead required to setup the test environment on the
+remote machines, but if the project has a lot of tests and
+several machines available, the speed up should be significant
+in most cases.  The more machines available, the better results 
+you will get. 
+
+Automatically distributing the tests can be also be useful if you 
+need to use remote resouces which you do not have locally (perhaps 
+a server has much more RAM or disk available). 
+Of course, you could also just ssh into the remote server,
+rsync or checkout your source code and run py.test 
+but that is obviously more cumbersome for the development
+process. 
+
+The distributed testing part of ``py.test`` also provides
+a web server interface which tells you about the progress
+of your distributed test run interactively. 
 
 Requirements
 ------------
@@ -691,11 +704,10 @@
 
 Remote requirements:
 
-* ssh server running
+* ssh daemon running
 * ssh keys setup to allow login without a password
-* python
+* python (2.3 or 2.4 should work)
 * unix like machine (``os.fork``)
-* network access to the machine
 
 How it works
 ------------
@@ -729,7 +741,7 @@
 
 You must create a conftest.py in any parent directory above your tests.
 
-The options are:
+The options that you need to specify in that conftest.py file are:
 
 * `disthosts` - a list of ssh addresses (including a specific path if it 
   should be different than the default: ``$HOME/pytestcache-hostname``)