Commits

lac committed 6081c78

minor fixes, but a few problems remain.

Comments (0)

Files changed (1)

 The `pytest-xdist`_ plugin extends py.test with some unique
 test execution modes:
 
-* Looponfail: run your tests repeatedly in a subprocess.  After each run py.test
+* Looponfail: run your tests repeatedly in a subprocess.  After each run, py.test
   waits until a file in your project changes and then re-runs the previously
-  failing tests.  This is repeated until all tests pass after which again
-  a full run is performed.
+  failing tests.  This is repeated until all tests pass. At this point
+  a full run is again performed.
 
 * multiprocess Load-balancing: if you have multiple CPUs or hosts you can use
-  those for a combined test run.  This allows to speed up
-  development or to use special resources of remote machines.
+  them for a combined test run.  This can speed up
+  development or enable you to use the special resources of remote machines.
 
 * Multi-Platform coverage: you can specify different Python interpreters
   or different platforms and run tests in parallel on all of them.
 
 Before running tests remotely, ``py.test`` efficiently "rsyncs" your
 program source code to the remote place.  All test results
-are reported back and displayed to your local terminal.
+report back and are displayed on your local terminal.
+
 You may specify different Python versions and interpreters.
+XYZZY I think kill this line because you already said that as your last
+bullet point.  
 
 
-Installation
+Installation of xdist
 -----------------------
 
 Install the plugin with::
     pip install pytest-xdist
 
 or use the package in develop/in-place mode with
+
+XYZZY in develop/in-place ??? what does that mean?
+
 a checkout of the `pytest-xdist repository`_ ::
 
     python setup.py develop
     py.test -n NUM
 
 Especially for longer running tests or tests requiring
-a lot of IO this can lead to considerable speed ups.
+a lot of I/O this can lead to considerable speed ups.
+
+XYZZY you need to explain this more.  What is NUM?  The number of cpus you
+have? the number you want py.test to use?  What if you have more cpus than
+the number you specify?  How does py.test determine which cpus to use? 
 
 
 Running tests in a Python subprocess
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+XYZZY is the point of this that you can specify which version of
+python you can use?  Why not use virtualenv or tox then?  If the
+point is something else, I have missed it.  This documentation makes
+it sound as if there is something special about python2.4, whereas
+To instantiate a subprocess with a particular Python version and
+then send tests to it, you may type::  doesn't make 2.4 sound special.
+Is that what you wanted?
 
-To instantiate a python2.4 sub process and send tests to it, you may type::
+To instantiate a python2.4 subprocess and send tests to it, you may type::
 
     py.test -d --tx popen//python=python2.4
 
 
     --tx 3*popen//python=python2.4
 
-then three subprocesses would be created and tests
+then three subprocesses would be created and the tests
 will be load-balanced across these three processes.
 
+XYZZY I have no idea what 'load-balanced across these three processes'
+means.  It sounds like you are measuring the performance of each process
+in some way and trying to balance the work done by each.  But all I think
+you are really doing is dividing the work among all three of them.  I'm
+very curious as to how you do this -- every time one of the three is done
+with a test it gets a new one? 
+
+
 .. _looponfailing:
 
 
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 For refactoring a project with a medium or large test suite
-you can use the looponfailing mode, simply add the ``--f`` option::
+you can use the looponfailing mode. Simply add the ``--f`` option::
 
     py.test -f
    
-and py.test will run your tests, then wait for file changes and re-run the failing test set.  Of course you can pass in more options to select tests or test files.  File changes are detected by looking at the root directory - you can override this automatic default by an ini-file setting::
+and py.test will run your tests, (some of which we assume fail) and then wait for changes in your codebase and re-run the failing tests. This continues until all the tests pass. Of course you can pass in more options to select tests or test files.  File changes are detected by looking at the root directory - you can override this automatic default by an ini-file setting::
+
+XYZZY you mean 'the current directory' by 'the root directory', no?  Where I
+      come from 'the root directory' is another name for the directory '/',
+      the root of the whole filesystem, and isn't a synonym for the current
+      working directory (unless the cwd is /)
 
     # content of a pytest.ini, setup.cfg or tox.ini file
     [pytest]
     looponfailroots = mypkg testdir
 
-This would lead to only looking for file changes in the respective directories, specified relatively to the ini-file's directory.
+This would cause py.test to only look for file changes in the respective directories, specified relative to the ini-file's directory.
 
 Sending tests to remote SSH accounts
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 Suppose you have a package ``mypkg`` which contains some
-tests that you can successfully run locally. And you
+tests that you can successfully run locally. And you also
 have a ssh-reachable machine ``myhost``.  Then
-you can ad-hoc distribute your tests by typing::
+you can distribute your tests in an ad-hoc fashion by typing::
 
     py.test -d --tx ssh=myhostpopen --rsyncdir mypkg mypkg
 
 This will synchronize your ``mypkg`` package directory
-to an remote ssh account and then locally collect tests
+with a remote ssh account and then locally collect tests
 and send them to remote places for execution.
+XYZZY I am not sure I understand this.  First of all, you synchronise a
+package with another package, not with an account.  Then, when you
+locally collect your tests, you send them to one remote place for
+execution, no? Try
+This will synchronize your local ``mypkg`` package directory
+with a remote one on the machine associated with a ssh account,
+and then collect tests locally  and send them to that  machine for execution.
 
 You can specify multiple ``--rsyncdir`` directories
 to be sent to the remote side.
 
 **NOTE:** For py.test to collect and send tests correctly
-you not only need to make sure all code and tests
-directories are rsynced, but that any test (sub) directory
-also has an ``__init__.py`` file because internally
-py.test references tests as a fully qualified python
+you not only need to make sure that all code and tests
+directories are rsynced, but also that any test (sub)directory
+also has an ``__init__.py`` file.  This is because
+py.test references tests internally as a fully qualified python
 module path.  **You will otherwise get strange errors**
-during setup of the remote side.
+during the setup of the remote side.
+
+XYZZY you might want to paste one in here, so that people who are
+googling for what they did wrong will be referred to this page.
 
 Sending tests to remote Socket Servers
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
     py.test -d --tx socket=192.168.1.102:8888 --rsyncdir mypkg mypkg
 
+XYZZY what is the default port?  and can I specify a particular port
+if I want to use something other than the default?
+
 
 .. _`atonce`:
 
 
 If you specify a windows host, an OSX host and a Linux
 environment this command will send each tests to all
-platforms - and report back failures from all platforms
+
+XYZZY I don't understand what dist=each means.  But the English is
+bad -- you don't 'send each tests', you 'send every test to each platform'
+or you 'send each test to all platforms' or even 'you send each test
+to each platform'.  But maybe there is a technical meaning here I am
+missing.
+
+platforms - and report back failures from all the platforms
 at once.   The specifications strings use the `xspec syntax`_.
 
+XYZZY 'and report back failures from all the platforms at once' - this
+implies that it waits until all the test runs are done on all of the
+platforms and then reports back, at one time, the whole result.  Which
+might be what you meant.  But if you mean that the failures are sent
+back to you _as they occur_ then you need to change 'at once' to 'as they
+occur'.
+
 .. _`xspec syntax`: http://codespeak.net/execnet/basics.html#xspec
 
 .. _`socketserver.py`: http://bitbucket.org/hpk42/execnet/raw/2af991418160/execnet/script/socketserver.py
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 pytest (since version 2.0) supports ini-style configuration.
-You can for example make running with three subprocesses
-your default like this::
+XYZZY this is never defined anywhere.  And here you need to either
+specify which files you can use to configure py.test or refer to
+the section that does this.
+
+For example, you could make running with three subprocesses
+your default::
 
     [pytest]
     addopts = -n3
 
-You can also add default environments like this::
+You can also add default environments::
 
     [pytest]
     addopts = --tx ssh=myhost//python=python2.5 --tx ssh=myhost//python=python2.6
 
 In a ``tox.ini`` or ``setup.cfg`` file in your root project directory
 you may specify directories to include or to exclude in synchronisation::
+XYZZY not pytest.ini?
 
     [pytest]
     rsyncdirs = . mypkg helperpkg