diff options
-rw-r--r-- | doc/contributing.rst | 121 |
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 |