[tahoe-lafs-trac-stream] [Tahoe-LAFS] #1439: add docs/tests.rst documenting how to run tests and how to interpret the output

[Tahoe-LAFS]

#1439: add docs/tests.rst documenting how to run tests and how to interpret the
output
-------------------------------+------------------------
     Reporter:  davidsarah     |      Owner:  somebody
         Type:  task           |     Status:  new
     Priority:  major          |  Milestone:  eventually
    Component:  documentation  |    Version:  1.8.2
   Resolution:                 |   Keywords:  docs test
Launchpad Bug:                 |
-------------------------------+------------------------

Comment (by warner):

 I'm picky about making tests run quickly, so I've identified three ways to
 run them, with various levels of nuisance and performance:

 * 1: `python setup.py test [-s allmydata.test.test_FOO]`
 * 2: `./bin/tahoe debug trial [allmydata.test.test_FOO]`
 * 3: `PYTHONPATH=support/lib/pythonX.Y/site-packages trial
 allmydata.test.test_FOO`

 The last is the fastest, but you have to have twisted/trial already
 installed (or add more to $PATH/$PYTHONPATH), tests which involve
 searching $PATH won't work (or add more to $PATH), and you have to know
 what minor version of python you're running (to get the support/ directory
 right).

 2 is easier, and only slightly slower: the `bin/tahoe` wrapper performs a
 fork+exec to re-run the entry point with the right $PATH/$PYTHONPATH

 1 is how the test automation does it, because it's not particularly tahoe-
 specific. It's even slower because it runs a second subprocess.call to
 invoke the second form. More importantly, it actually runs `setup.py
 build` first (because of the aliases in `setup.cfg`), which can spend
 several seconds looking at your support/ directory and deciding whether to
 install dependencies or not.

 And if you use `python setup.py test --coverage`, then you get one
 subprocess.call to invoke `bin/tahoe @coverage`, a second one inside the
 `bin/tahoe` wrapper to run the real bin/tahoe, and third one in bin/tahoe
 to run `coverage`. But for large tests, that's usually small compared to
 the overhead induced by the coverage tracing function.

 I'm hoping that our #2255/#2207 overhauls can remove these extra calls.

--
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1439#comment:2>
Tahoe-LAFS <https://Tahoe-LAFS.org>
secure decentralized storage