docs: more details, and current output, in contributing.rst

1 files changed, 78 insertions, 43 deletions

diff --git a/doc/contributing.rst b/doc/contributing.rst
index e9d2c3a4..410d0d4c 100644
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@@ -67,57 +67,91 @@ Running the tests
 The tests are written mostly as standard unittest-style tests, and are run with
 pytest running under `tox`_::
 
-    $ tox
-    py37 create: /Users/nedbat/coverage/trunk/.tox/py37
-    py37 installdeps: -rrequirements/pip.pip, -rrequirements/pytest.pip, eventlet==0.25.1, greenlet==0.4.15
-    py37 develop-inst: /Users/nedbat/coverage/trunk
-    py37 installed: apipkg==1.5,appdirs==1.4.4,attrs==20.3.0,backports.functools-lru-cache==1.6.4,-e git+git@github.com:nedbat/coveragepy.git@36ef0e03c0439159c2245d38de70734fa08cddb4#egg=coverage,decorator==5.0.7,distlib==0.3.1,dnspython==2.1.0,eventlet==0.25.1,execnet==1.8.0,filelock==3.0.12,flaky==3.7.0,future==0.18.2,greenlet==0.4.15,hypothesis==6.10.1,importlib-metadata==4.0.1,iniconfig==1.1.1,monotonic==1.6,packaging==20.9,pluggy==0.13.1,py==1.10.0,PyContracts @ git+https://github.com/slorg1/contracts@c5a6da27d4dc9985f68e574d20d86000880919c3,pyparsing==2.4.7,pytest==6.2.3,pytest-forked==1.3.0,pytest-xdist==2.2.1,qualname==0.1.0,six==1.15.0,sortedcontainers==2.3.0,toml==0.10.2,typing-extensions==3.10.0.0,virtualenv==20.4.4,zipp==3.4.1
-    py37 run-test-pre: PYTHONHASHSEED='376882681'
-    py37 run-test: commands[0] | python setup.py --quiet clean develop
-    py37 run-test: commands[1] | python igor.py zip_mods remove_extension
-    py37 run-test: commands[2] | python igor.py test_with_tracer py
-    === CPython 3.7.10 with Python tracer (.tox/py37/bin/python) ===
+    % tox
+    ROOT: tox-gh won't override envlist because tox is not running in GitHub Actions
+    .pkg: _optional_hooks> python /usr/local/virtualenvs/coverage/lib/python3.7/site-packages/pyproject_api/_backend.py True setuptools.build_meta
+    .pkg: get_requires_for_build_editable> python /usr/local/virtualenvs/coverage/lib/python3.7/site-packages/pyproject_api/_backend.py True setuptools.build_meta
+    .pkg: build_editable> python /usr/local/virtualenvs/coverage/lib/python3.7/site-packages/pyproject_api/_backend.py True setuptools.build_meta
+    py37: install_package> python -m pip install -U --force-reinstall --no-deps .tox/.tmp/package/87/coverage-7.2.3a0.dev1-0.editable-cp37-cp37m-macosx_10_15_x86_64.whl
+    py37: commands[0]> python igor.py zip_mods
+    py37: commands[1]> python setup.py --quiet build_ext --inplace
+    py37: commands[2]> python -m pip install -q -e .
+    py37: commands[3]> python igor.py test_with_tracer c
+    === CPython 3.7.15 with C tracer (.tox/py37/bin/python) ===
     bringing up nodes...
-    ........................................................................................................................................................... [ 15%]
-    ........................................................................................................................................................... [ 31%]
-    ...........................................................................................................................................s............... [ 47%]
-    ...........................................s...................................................................................sss.sssssssssssssssssss..... [ 63%]
-    ........................................................................................................................................................s.. [ 79%]
-    ......................................s..................................s................................................................................. [ 95%]
-    ........................................ss......                                                                                                            [100%]
-    949 passed, 29 skipped in 40.56s
-    py37 run-test: commands[3] | python setup.py --quiet build_ext --inplace
-    py37 run-test: commands[4] | python igor.py test_with_tracer c
-    === CPython 3.7.10 with C tracer (.tox/py37/bin/python) ===
+    .........................................................................................................................x.................s....s....... [ 11%]
+    ..s.....x.............................................s................................................................................................. [ 22%]
+    ........................................................................................................................................................ [ 34%]
+    ........................................................................................................................................................ [ 45%]
+    ........................................................................................................................................................ [ 57%]
+    .........s....................................................................................................................s......................... [ 68%]
+    .................................s..............................s...............s..................................s.................................... [ 80%]
+    ........................................................s............................................................................................... [ 91%]
+    ......................................s.........................................................................                                         [100%]
+    1316 passed, 12 skipped, 2 xfailed in 36.42s
+    py37: commands[4]> python igor.py remove_extension
+    py37: commands[5]> python igor.py test_with_tracer py
+    === CPython 3.7.15 with Python tracer (.tox/py37/bin/python) ===
     bringing up nodes...
-    ........................................................................................................................................................... [ 15%]
-    ........................................................................................................................................................... [ 31%]
-    ......................................................................s.................................................................................... [ 47%]
-    ........................................................................................................................................................... [ 63%]
-    ..........................s................................................s............................................................................... [ 79%]
-    .................................................................................s......................................................................... [ 95%]
-    ......................................s.........                                                                                                            [100%]
-    973 passed, 5 skipped in 41.36s
-    ____________________________________________________________________________ summary _____________________________________________________________________________
-      py37: commands succeeded
-      congratulations :)
+    ................................................................................................x...........................x.................s......... [ 11%]
+    .....s.............s.s.....................................................s..............ss............................s.ss....ss.ss................... [ 22%]
+    ......................................................................................................................................s................. [ 34%]
+    ..................................................................................................................s..................................... [ 45%]
+    ...................s.ss.....................................................................................s....................s.ss................... [ 57%]
+    ..................s.s................................................................................................................................... [ 68%]
+    ..........................s.........................................ssss...............s.................s...sss..................s...ss...ssss.s....... [ 80%]
+    .......................................................................................................................................................s [ 91%]
+    .........................................................................s.................................ss....                                        [100%]
+    1281 passed, 47 skipped, 2 xfailed in 33.86s
+    .pkg: _exit> python /usr/local/virtualenvs/coverage/lib/python3.7/site-packages/pyproject_api/_backend.py True setuptools.build_meta
+      py37: OK (82.38=setup[2.80]+cmd[0.20,0.35,7.30,37.20,0.21,34.32] seconds)
+      congratulations :) (83.61 seconds)
 
 Tox runs the complete test suite twice for each version of Python you have
-installed.  The first run uses the Python implementation of the trace function,
-the second uses the C implementation.
+installed.  The first run uses the C implementation of the trace function,
+the second uses the Python implementation.
 
 To limit tox to just a few versions of Python, use the ``-e`` switch::
 
     $ tox -e py37,py39
 
-To run just a few tests, you can use `pytest test selectors`_::
-
-    $ tox tests/test_misc.py
-    $ tox tests/test_misc.py::HasherTest
-    $ tox tests/test_misc.py::HasherTest::test_string_hashing
-
-These command run the tests in one file, one class, and just one test,
-respectively.
+On the tox command line, options after ``--`` are passed to pytest.  To run
+just a few tests, you can use `pytest test selectors`_::
+
+    $ tox -- tests/test_misc.py
+    $ tox -- tests/test_misc.py::HasherTest
+    $ tox -- tests/test_misc.py::HasherTest::test_string_hashing
+
+These commands run the tests in one file, one class, and just one test,
+respectively.  The pytest ``-k`` option selects tests based on a word in their
+name, which can be very convenient for ad-hoc test selection.  Of course you
+can combine tox and pytest options::
+
+    $ tox -q -e py37 -- -n 0 -vv -k hash
+    === CPython 3.7.15 with C tracer (.tox/py37/bin/python) ===
+    ======================================= test session starts ========================================
+    platform darwin -- Python 3.7.15, pytest-7.2.2, pluggy-1.0.0 -- /Users/nedbat/coverage/.tox/py37/bin/python
+    cachedir: .tox/py37/.pytest_cache
+    rootdir: /Users/nedbat/coverage, configfile: setup.cfg
+    plugins: flaky-3.7.0, hypothesis-6.70.0, xdist-3.2.1
+    collected 1330 items / 1320 deselected / 10 selected
+    run-last-failure: no previously failed tests, not deselecting items.
+
+    tests/test_data.py::CoverageDataTest::test_add_to_hash_with_lines PASSED                     [ 10%]
+    tests/test_data.py::CoverageDataTest::test_add_to_hash_with_arcs PASSED                      [ 20%]
+    tests/test_data.py::CoverageDataTest::test_add_to_lines_hash_with_missing_file PASSED        [ 30%]
+    tests/test_data.py::CoverageDataTest::test_add_to_arcs_hash_with_missing_file PASSED         [ 40%]
+    tests/test_execfile.py::RunPycFileTest::test_running_hashed_pyc PASSED                       [ 50%]
+    tests/test_misc.py::HasherTest::test_string_hashing PASSED                                   [ 60%]
+    tests/test_misc.py::HasherTest::test_bytes_hashing PASSED                                    [ 70%]
+    tests/test_misc.py::HasherTest::test_unicode_hashing PASSED                                  [ 80%]
+    tests/test_misc.py::HasherTest::test_dict_hashing PASSED                                     [ 90%]
+    tests/test_misc.py::HasherTest::test_dict_collision PASSED                                   [100%]
+
+    =============================== 10 passed, 1320 deselected in 1.88s ================================
+    Skipping tests with Python tracer: Only one tracer: no Python tracer for CPython
+      py37: OK (12.22=setup[2.19]+cmd[0.20,0.36,6.57,2.51,0.20,0.19] seconds)
+      congratulations :) (13.10 seconds)
 
 You can also affect the test runs with environment variables. Define any of
 these as 1 to use them:
@@ -156,7 +190,8 @@ some warnings.  Please try to keep it that way, but don't let pylint warnings
 keep you from sending patches.  I can clean them up.
 
 Lines should be kept to a 100-character maximum length.  I recommend an
-`editorconfig.org`_ plugin for your editor of choice.
+`editorconfig.org`_ plugin for your editor of choice, which will also help with
+indentation, line endings and so on.
 
 Other style questions are best answered by looking at the existing code.
 Formatting of docstrings, comments, long lines, and so on, should match the