From fcebf4f557b1a35a0a541435b139e57defc2240b Mon Sep 17 00:00:00 2001 From: holger krekel Date: Sat, 6 Nov 2010 11:38:53 +0100 Subject: [PATCH] some more improvements and updates to docs, add release announcements --- doc/announce/index.txt | 22 +++++++++ doc/announce/release-2.0.0.txt | 50 ++++++++++++++++++++ doc/announce/releases.txt | 16 ------- doc/apiref.txt | 1 + doc/assert.txt | 4 +- doc/builtin.txt | 16 +++---- doc/conf.py | 4 +- doc/contact.txt | 6 ++- doc/doctest.txt | 4 +- doc/example/builtin.txt | 6 +-- doc/example/controlskip.txt | 6 +-- doc/example/index.txt | 4 ++ doc/example/mysetup.txt | 8 ++-- doc/example/nonpython.txt | 31 ++++++------- doc/example/pythoncollection.txt | 17 ++++--- doc/example/simple.txt | 21 ++++----- doc/example/xunit_setup.txt | 4 +- doc/funcargs.txt | 80 +++++++++++++------------------- doc/getting-started.txt | 11 +++-- doc/index.txt | 1 + doc/mark.txt | 12 ++--- doc/monkeypatch.txt | 4 +- doc/nose.txt | 42 +++++++++++++++++ doc/plugins.txt | 46 +++++++++++++++--- doc/tmpdir.txt | 22 +++++---- doc/unittest.txt | 6 +-- pytest/plugin/assertion.py | 3 ++ pytest/plugin/capture.py | 4 +- pytest/plugin/config.py | 2 +- pytest/plugin/doctest.py | 2 +- pytest/plugin/genscript.py | 1 + pytest/plugin/helpconfig.py | 3 +- pytest/plugin/junitxml.py | 5 +- pytest/plugin/mark.py | 6 +-- pytest/plugin/monkeypatch.py | 2 +- pytest/plugin/nose.py | 39 +--------------- pytest/plugin/pdb.py | 5 +- pytest/plugin/pytester.py | 4 +- pytest/plugin/python.py | 4 +- pytest/plugin/recwarn.py | 2 +- pytest/plugin/resultlog.py | 2 +- pytest/plugin/runner.py | 9 ++-- pytest/plugin/session.py | 10 ++-- pytest/plugin/skipping.py | 4 +- pytest/plugin/terminal.py | 3 +- pytest/plugin/tmpdir.py | 11 +---- pytest/plugin/unittest.py | 4 +- 47 files changed, 315 insertions(+), 254 deletions(-) create mode 100644 doc/announce/index.txt create mode 100644 doc/announce/release-2.0.0.txt delete mode 100644 doc/announce/releases.txt create mode 100644 doc/nose.txt diff --git a/doc/announce/index.txt b/doc/announce/index.txt new file mode 100644 index 000000000..7590c06a3 --- /dev/null +++ b/doc/announce/index.txt @@ -0,0 +1,22 @@ + +Release announcements +=========================================== + +.. toctree:: + :maxdepth: 2 + + release-2.0.0 + release-1.3.4 + release-1.3.3 + release-1.3.2 + release-1.3.1 + release-1.3.0 + release-1.2.1 + release-1.2.0 + release-1.1.1 + release-1.1.0 + release-1.0.2 + release-1.0.1 + release-1.0.0 + release-0.9.2 + release-0.9.0 diff --git a/doc/announce/release-2.0.0.txt b/doc/announce/release-2.0.0.txt new file mode 100644 index 000000000..4cdd19c8f --- /dev/null +++ b/doc/announce/release-2.0.0.txt @@ -0,0 +1,50 @@ +py.test 2.0.0: standalone, features++, implementation++, docs++ +=========================================================================== + +XXX PENDING + +Welcome to pytest-2.0.0! With this release py.test becomes its own standalone +PyPI distribution, named ``pytest``, installing the ``py.test`` command line +tool. Apart from a great internal cleanup this release comes with tons +of improvements and new features and a completely revamped extensive +documentation, including many continously tested examples. See + + http://pytest.org + +New Features +----------------------- + +- new invocations through Python interpreter and from Python:: + + python -m pytest # on all pythons >= 2.7 + python -m pytest.main # on all pythons >= 2.5 + import pytest ; pytest.main(args, plugins) + + see http://pytest.org/2.0.0/invoke.html for details. + +- new configuration through ini-files (setup.cfg or tox.ini recognized), + for example:: + + [pytest] + norecursedirs = .hg _build + python_collect_funcprefix = test_ + python_collect_classprefix = Test + + see http://pytest.org/2.0.0/customize.html + +- + +Thanks to issue reporters, people asking questions, complaining and +generally to Ronny Pfannschmidt for his awesome help on many issues. + +cheers, +holger krekel + +Changes between 1.3.3 and 1.3.4 +================================================== + +- fix issue111: improve install documentation for windows +- fix issue119: fix custom collectability of __init__.py as a module +- fix issue116: --doctestmodules work with __init__.py files as well +- fix issue115: unify internal exception passthrough/catching/GeneratorExit +- fix issue118: new --tb=native for presenting cpython-standard exceptions diff --git a/doc/announce/releases.txt b/doc/announce/releases.txt deleted file mode 100644 index 309c29bac..000000000 --- a/doc/announce/releases.txt +++ /dev/null @@ -1,16 +0,0 @@ -============= -Release notes -============= - -Contents: - -.. toctree:: - :maxdepth: 2 - -.. include: release-1.1.0 -.. include: release-1.0.2 - - release-1.0.1 - release-1.0.0 - release-0.9.2 - release-0.9.0 diff --git a/doc/apiref.txt b/doc/apiref.txt index 52af57de4..4392eb8f3 100644 --- a/doc/apiref.txt +++ b/doc/apiref.txt @@ -20,5 +20,6 @@ py.test reference documentation mark.txt recwarn.txt unittest.txt + nose.txt doctest.txt diff --git a/doc/assert.txt b/doc/assert.txt index 9729e34d4..32438134e 100644 --- a/doc/assert.txt +++ b/doc/assert.txt @@ -21,7 +21,7 @@ assertion fails you will see the value of ``x``:: $ py.test test_assert1.py =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_assert1.py test_assert1.py F @@ -101,7 +101,7 @@ if you run this module:: $ py.test test_assert2.py =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_assert2.py test_assert2.py F diff --git a/doc/builtin.txt b/doc/builtin.txt index 017cc8cc8..2717bcfb1 100644 --- a/doc/builtin.txt +++ b/doc/builtin.txt @@ -28,25 +28,25 @@ You can ask for available builtin or project-custom captures writes to sys.stdout/sys.stderr and makes them available successively via a ``capsys.readouterr()`` method which returns a ``(out, err)`` tuple of captured snapshot strings. - + capfd captures writes to file descriptors 1 and 2 and makes snapshotted ``(out, err)`` string tuples available via the ``capsys.readouterr()`` method. If the underlying platform does not have ``os.dup`` (e.g. Jython) tests using this funcarg will automatically skip. - + tmpdir return a temporary directory path object unique to each test function invocation, created as a sub directory of the base temporary directory. The returned object is a `py.path.local`_ path object. - + monkeypatch The returned ``monkeypatch`` funcarg provides these helper methods to modify objects, dictionaries or os.environ:: - + monkeypatch.setattr(obj, name, value, raising=True) monkeypatch.delattr(obj, name, raising=True) monkeypatch.setitem(mapping, name, value) @@ -54,15 +54,15 @@ You can ask for available builtin or project-custom monkeypatch.setenv(name, value, prepend=False) monkeypatch.delenv(name, value, raising=True) monkeypatch.syspath_prepend(path) - + All modifications will be undone when the requesting test function finished its execution. The ``raising`` parameter determines if a KeyError or AttributeError will be raised if the set/deletion operation has no target. - + recwarn Return a WarningsRecorder instance that provides these methods: - + * ``pop(category=None)``: return last warning matching the category. * ``clear()``: clear list of warnings - + diff --git a/doc/conf.py b/doc/conf.py index f199badaa..b4192bd1c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,7 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode'] # Add any paths that contain templates here, relative to this directory. @@ -65,7 +65,7 @@ release = '2.0.0dev0' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['links.inc', '_build', 'test', 'announce'] # XXX +exclude_patterns = ['links.inc', '_build', 'test', ] # XXX # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None diff --git a/doc/contact.txt b/doc/contact.txt index 727fc0e45..e36d3d827 100644 --- a/doc/contact.txt +++ b/doc/contact.txt @@ -1,11 +1,13 @@ .. _`contact channels`: +.. _`contact`: Contact channels =================================== -- `new issue tracker`_ to report bugs or suggest features. - See also the `old issue tracker`_ but don't submit bugs there. +- `new issue tracker`_ to report bugs or suggest features (for version + 2.0 and above). You may also peek at the `old issue tracker`_ but please + don't submit bugs there anymore. - `Testing In Python`_: a mailing list for Python testing tools and discussion. diff --git a/doc/doctest.txt b/doc/doctest.txt index 434be0975..5120a5392 100644 --- a/doc/doctest.txt +++ b/doc/doctest.txt @@ -44,7 +44,7 @@ then you can just invoke ``py.test`` without command line options:: $ py.test =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 - test path 1: /tmp/doc-exec-197 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 + test path 1: /tmp/doc-exec-400 ============================= in 0.00 seconds ============================= diff --git a/doc/example/builtin.txt b/doc/example/builtin.txt index bc867c049..008d4eec2 100644 --- a/doc/example/builtin.txt +++ b/doc/example/builtin.txt @@ -3,8 +3,9 @@ writing well integrated assertion helpers ======================================================== If you have a test helper function called from a test you can -use the ``pytest.fail``_ builtin to cleanly fail a test with a message. -The test support function will never itself show up in the traceback. +use the ``pytest.fail`` marker to fail a test with a certain message. +The test support function will not show up in the traceback if you +set the ``__tracebackhide__`` option somewhere in the helper function. Example:: # content of test_checkconfig.py @@ -33,4 +34,3 @@ Let's run our little function:: test_checkconfig.py:8: Failed 1 failed in 0.02 seconds - diff --git a/doc/example/controlskip.txt b/doc/example/controlskip.txt index 096bba765..3194034f4 100644 --- a/doc/example/controlskip.txt +++ b/doc/example/controlskip.txt @@ -36,12 +36,12 @@ and when running it will see a skipped "slow" test:: $ py.test test_module.py -rs # "-rs" means report on the little 's' =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_module.py test_module.py .s ========================= short test summary info ========================== - SKIP [1] /tmp/doc-exec-195/conftest.py:9: 'need --runslow option to run' + SKIP [1] /tmp/doc-exec-435/conftest.py:9: need --runslow option to run =================== 1 passed, 1 skipped in 0.02 seconds ==================== @@ -49,7 +49,7 @@ Or run it including the ``slow`` marked test:: $ py.test test_module.py --runslow =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_module.py test_module.py .. diff --git a/doc/example/index.txt b/doc/example/index.txt index 24b78d528..a84ddf984 100644 --- a/doc/example/index.txt +++ b/doc/example/index.txt @@ -4,6 +4,9 @@ Usages and Examples =========================================== +This is a (growing) list of examples. :ref:`Contact ` us if you +need more examples or have questions. + .. toctree:: :maxdepth: 2 @@ -14,3 +17,4 @@ Usages and Examples detectpytest.txt nonpython.txt simple.txt + xunit_setup.txt diff --git a/doc/example/mysetup.txt b/doc/example/mysetup.txt index 507210471..ef325b441 100644 --- a/doc/example/mysetup.txt +++ b/doc/example/mysetup.txt @@ -49,7 +49,7 @@ You can now run the test:: $ py.test test_sample.py =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_sample.py test_sample.py F @@ -57,7 +57,7 @@ You can now run the test:: ================================= FAILURES ================================= _______________________________ test_answer ________________________________ - mysetup = + mysetup = def test_answer(mysetup): app = mysetup.myapp() @@ -122,12 +122,12 @@ Running it yields:: $ py.test test_ssh.py -rs =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_ssh.py test_ssh.py s ========================= short test summary info ========================== - SKIP [1] /tmp/doc-exec-198/conftest.py:22: 'specify ssh host with --ssh' + SKIP [1] /tmp/doc-exec-438/conftest.py:22: specify ssh host with --ssh ======================== 1 skipped in 0.02 seconds ========================= diff --git a/doc/example/nonpython.txt b/doc/example/nonpython.txt index 2e7ae9a9a..98433c7ea 100644 --- a/doc/example/nonpython.txt +++ b/doc/example/nonpython.txt @@ -27,17 +27,17 @@ now execute the test specification:: nonpython $ py.test test_simple.yml =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_simple.yml - + test_simple.yml .F - + ================================= FAILURES ================================= ______________________________ usecase: hello ______________________________ usecase execution failed spec failed: 'some': 'other' no further details known at this point. - ==================== 1 failed, 1 passed in 0.37 seconds ==================== + ==================== 1 failed, 1 passed in 0.42 seconds ==================== You get one dot for the passing ``sub1: sub1`` check and one failure. Obviously in the above ``conftest.py`` you'll want to implement a more @@ -47,22 +47,21 @@ your own domain specific testing language this way. .. note:: ``repr_failure(excinfo)`` is called for representing test failures. - If you create custom collection nodes you can return an error + If you create custom collection nodes you can return an error representation string of your choice. It will be reported as a (red) string. - ``reportinfo()`` -is used for representing the test location and is also consulted for +``reportinfo()`` is used for representing the test location and is also consulted for reporting in ``verbose`` mode:: nonpython $ py.test -v =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 -- /home/hpk/venv/0/bin/python + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 -- /home/hpk/venv/0/bin/python test path 1: /home/hpk/p/pytest/doc/example/nonpython - - test_simple.yml:1: usecase: ok PASSED - test_simple.yml:1: usecase: hello FAILED - + + test_simple.yml <- test_simple.yml:1: usecase: ok PASSED + test_simple.yml <- test_simple.yml:1: usecase: hello FAILED + ================================= FAILURES ================================= ______________________________ usecase: hello ______________________________ usecase execution failed @@ -74,7 +73,7 @@ While developing your custom test collection and execution it's also interesting to just look at the collection tree:: nonpython $ py.test --collectonly - - - - + + + + diff --git a/doc/example/pythoncollection.txt b/doc/example/pythoncollection.txt index 22c6343ee..99b4f5d1e 100644 --- a/doc/example/pythoncollection.txt +++ b/doc/example/pythoncollection.txt @@ -18,12 +18,11 @@ finding out what is collected You can always peek at the collection tree without running tests like this:: - $ py.test --collectonly collectonly.py - - - - - - - - + . $ py.test --collectonly collectonly.py + + + + + + + diff --git a/doc/example/simple.txt b/doc/example/simple.txt index fa49c6de8..06e525bed 100644 --- a/doc/example/simple.txt +++ b/doc/example/simple.txt @@ -36,9 +36,9 @@ Let's run this without supplying our new command line option:: F ================================= FAILURES ================================= _______________________________ test_answer ________________________________ - + cmdopt = 'type1' - + def test_answer(cmdopt): if cmdopt == "type1": print ("first") @@ -46,7 +46,7 @@ Let's run this without supplying our new command line option:: print ("second") > assert 0 # to see what was printed E assert 0 - + test_sample.py:6: AssertionError ----------------------------- Captured stdout ------------------------------ first @@ -58,9 +58,9 @@ And now with supplying a command line option:: F ================================= FAILURES ================================= _______________________________ test_answer ________________________________ - + cmdopt = 'type2' - + def test_answer(cmdopt): if cmdopt == "type1": print ("first") @@ -68,7 +68,7 @@ And now with supplying a command line option:: print ("second") > assert 0 # to see what was printed E assert 0 - + test_sample.py:6: AssertionError ----------------------------- Captured stdout ------------------------------ second @@ -122,16 +122,15 @@ let's run the full monty:: ....F ================================= FAILURES ================================= _____________________________ test_compute[4] ______________________________ - + param1 = 4 - + def test_compute(param1): > assert param1 < 4 E assert 4 < 4 - + test_compute.py:3: AssertionError - 1 failed, 4 passed in 0.03 seconds - + 1 failed, 4 passed in 0.02 seconds As expected when running the full range of ``param1`` values we'll get an error on the last one. diff --git a/doc/example/xunit_setup.txt b/doc/example/xunit_setup.txt index d4c905d2a..2fa6de211 100644 --- a/doc/example/xunit_setup.txt +++ b/doc/example/xunit_setup.txt @@ -19,8 +19,8 @@ custom options:: .. _optparse: http://docs.python.org/library/optparse.html -Working Examples -================ +order of setup/teardown module/class/item methods +==================================================== managing state at module, class and method level ------------------------------------------------------------ diff --git a/doc/funcargs.txt b/doc/funcargs.txt index b1d0ad3bf..9f1650ee8 100644 --- a/doc/funcargs.txt +++ b/doc/funcargs.txt @@ -34,20 +34,20 @@ Running the test looks like this:: $ py.test test_simplefactory.py =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_simplefactory.py - + test_simplefactory.py F - + ================================= FAILURES ================================= ______________________________ test_function _______________________________ - + myfuncarg = 42 - + def test_function(myfuncarg): > assert myfuncarg == 17 E assert 42 == 17 - + test_simplefactory.py:5: AssertionError ========================= 1 failed in 0.02 seconds ========================= @@ -136,70 +136,52 @@ Running this:: $ py.test test_example.py =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_example.py - + test_example.py .........F - + ================================= FAILURES ================================= _______________________________ test_func[9] _______________________________ - + numiter = 9 - + def test_func(numiter): > assert numiter < 9 E assert 9 < 9 - + test_example.py:7: AssertionError - ==================== 1 failed, 9 passed in 0.03 seconds ==================== + ==================== 1 failed, 9 passed in 0.04 seconds ==================== Note that the ``pytest_generate_tests(metafunc)`` hook is called during the test collection phase which is separate from the actual test running. Let's just look at what is collected:: $ py.test --collectonly test_example.py - - - - - - - - - - - - + + + + + + + + + + + + If you want to select only the run with the value ``7`` you could do:: $ py.test -v -k 7 test_example.py # or -k test_func[7] =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 -- /home/hpk/venv/0/bin/python + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 -- /home/hpk/venv/0/bin/python test path 1: test_example.py - - test_example.py:6: test_func[0] PASSED - test_example.py:6: test_func[1] PASSED - test_example.py:6: test_func[2] PASSED - test_example.py:6: test_func[3] PASSED - test_example.py:6: test_func[4] PASSED - test_example.py:6: test_func[5] PASSED - test_example.py:6: test_func[6] PASSED - test_example.py:6: test_func[7] PASSED - test_example.py:6: test_func[8] PASSED - test_example.py:6: test_func[9] FAILED - - ================================= FAILURES ================================= - _______________________________ test_func[9] _______________________________ - - numiter = 9 - - def test_func(numiter): - > assert numiter < 9 - E assert 9 < 9 - - test_example.py:7: AssertionError - ==================== 1 failed, 9 passed in 0.04 seconds ==================== + + test_example.py <- test_example.py:6: test_func[7] PASSED + + ======================== 9 tests deselected by '7' ========================= + ================== 1 passed, 9 deselected in 0.01 seconds ================== .. _`metafunc object`: diff --git a/doc/getting-started.txt b/doc/getting-started.txt index 6908d5c2f..c2f2741cd 100644 --- a/doc/getting-started.txt +++ b/doc/getting-started.txt @@ -14,6 +14,7 @@ Installation options:: To check your installation has installed the correct version:: $ py.test --version + This is py.test version 2.0.0.dev19, imported from /home/hpk/p/pytest/pytest If you get an error checkout :ref:`installation issues`. @@ -33,8 +34,8 @@ That's it. You can execute the test function now:: $ py.test =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev18 - test path 1: /tmp/doc-exec-211 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 + test path 1: /tmp/doc-exec-404 test_sample.py F @@ -120,7 +121,7 @@ run the module by passing its filename:: ================================= FAILURES ================================= ____________________________ TestClass.test_two ____________________________ - self = + self = def test_two(self): x = "hello" @@ -156,7 +157,7 @@ before performing the test function call. Let's just run it:: ================================= FAILURES ================================= _____________________________ test_needsfiles ______________________________ - tmpdir = local('/tmp/pytest-1306/test_needsfiles0') + tmpdir = local('/tmp/pytest-240/test_needsfiles0') def test_needsfiles(tmpdir): print tmpdir @@ -165,7 +166,7 @@ before performing the test function call. Let's just run it:: test_tmpdir.py:3: AssertionError ----------------------------- Captured stdout ------------------------------ - /tmp/pytest-1306/test_needsfiles0 + /tmp/pytest-240/test_needsfiles0 1 failed in 0.04 seconds Before the test runs, a unique-per-test-invocation temporary directory diff --git a/doc/index.txt b/doc/index.txt index d50d4c7a8..6037f6dd7 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -19,6 +19,7 @@ Welcome to ``py.test`` documentation: example/index talks develop + announce/index .. toctree:: :hidden: diff --git a/doc/mark.txt b/doc/mark.txt index 04c41b212..3556b238a 100644 --- a/doc/mark.txt +++ b/doc/mark.txt @@ -88,8 +88,8 @@ You can use the ``-k`` command line option to select tests:: $ py.test -k webtest # running with the above defined examples yields =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 - test path 1: /tmp/doc-exec-171 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 + test path 1: /tmp/doc-exec-407 test_mark.py .. test_mark_classlevel.py .. @@ -100,8 +100,8 @@ And you can also run all tests except the ones that match the keyword:: $ py.test -k-webtest =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 - test path 1: /tmp/doc-exec-171 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 + test path 1: /tmp/doc-exec-407 ===================== 4 tests deselected by '-webtest' ===================== ======================= 4 deselected in 0.01 seconds ======================= @@ -110,8 +110,8 @@ Or to only select the class:: $ py.test -kTestClass =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 - test path 1: /tmp/doc-exec-171 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 + test path 1: /tmp/doc-exec-407 test_mark_classlevel.py .. diff --git a/doc/monkeypatch.txt b/doc/monkeypatch.txt index 632d6f66d..548debad2 100644 --- a/doc/monkeypatch.txt +++ b/doc/monkeypatch.txt @@ -39,8 +39,8 @@ will be undone. .. background check: $ py.test =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 - test path 1: /tmp/doc-exec-172 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 + test path 1: /tmp/doc-exec-408 ============================= in 0.00 seconds ============================= diff --git a/doc/nose.txt b/doc/nose.txt new file mode 100644 index 000000000..9edc2bf6c --- /dev/null +++ b/doc/nose.txt @@ -0,0 +1,42 @@ +Running test written for nose +======================================= + +.. include:: links.inc + +py.test has basic support for running tests written for nose_. +This is implemented in :pymod:`pytest.plugin.nose`. + +Usage +------------- + +type:: + + py.test # instead of 'nosetests' + +and you should be able to run your nose style tests and at the same +make full use of py.test's capabilities. + +Supported nose Idioms +---------------------- + +* setup and teardown at module/class/method level +* SkipTest exceptions and markers +* setup/teardown decorators +* yield-based tests and their setup +* general usage of nose utilities + +Unsupported idioms / issues +---------------------------------- + +- nose-style doctests are not collected and executed correctly, + also fixtures don't work. + +- no nose-configuration is recognized + +If you find other issues or have suggestions please run:: + + py.test --pastebin=all + +and send the resulting URL to a py.test contact channel, +at best to the mailing list. +""" diff --git a/doc/plugins.txt b/doc/plugins.txt index 961e9c803..20ddaaf66 100644 --- a/doc/plugins.txt +++ b/doc/plugins.txt @@ -5,7 +5,7 @@ Writing, managing and understanding plugins py.test implements all aspects of configuration, collection, running and reporting by calling `well specified hooks`_. Virtually any Python module can be registered as a plugin. It can implement any number of hook functions (usually two or three) which all have a ``pytest_`` prefix, making hook functions easy to distinguish and find. There are three basic locations types: -* builtin plugins: loaded from py.test's own `pytest/plugin`_ directory. +* `builtin plugins`_: loaded from py.test's own ``pytest/plugin`` directory. * `external plugins`_: modules discovered through `setuptools entry points`_ * `conftest.py plugins`_: modules auto-discovered in test directories @@ -48,8 +48,8 @@ earlier than further away ones. python package directory (i.e. one containing an ``__init__.py``) then "import conftest" can be ambigous because there might be other ``conftest.py`` files as well on your PYTHONPATH or ``sys.path``. - It is thus good practise for projects to either put ``conftest.py`` - under a package scope or to never import anything from a + It is thus good practise for projects to either put ``conftest.py`` + under a package scope or to never import anything from a conftest.py file. .. _`installing plugins`: @@ -90,6 +90,7 @@ to implement their wide-ranging functionality. .. _`setuptools entry points`: + Making your plugin installable by others ----------------------------------------------- @@ -97,8 +98,8 @@ If you want to make your plugin externally available, you may define a so called entry point for your distribution so that ``py.test`` finds your plugin module. Entry points are a feature that is provided by `setuptools`_ or `Distribute`_. -The concrete entry point is ``pytest11``. To make your plugin -available you can insert the following lines in your +The concrete entry point is ``pytest11``. To make your plugin +available you can insert the following lines in your setuptools/distribute-based setup-invocation: .. sourcecode:: python @@ -171,6 +172,37 @@ the plugin manager like this: If you want to look at the names of existing plugins, use the ``--traceconfig`` option. + +.. _`builtin plugins`: + +py.test default plugin reference +==================================== + +.. autosummary:: + + pytest.plugin.assertion + pytest.plugin.capture + pytest.plugin.config + pytest.plugin.doctest + pytest.plugin.genscript + pytest.plugin.helpconfig + pytest.plugin.junitxml + pytest.plugin.mark + pytest.plugin.monkeypatch + pytest.plugin.nose + pytest.plugin.pastebin + pytest.plugin.pdb + pytest.plugin.pytester + pytest.plugin.python + pytest.plugin.recwarn + pytest.plugin.resultlog + pytest.plugin.runner + pytest.plugin.session + pytest.plugin.skipping + pytest.plugin.terminal + pytest.plugin.tmpdir + pytest.plugin.unittest + .. _`well specified hooks`: py.test hook reference @@ -183,7 +215,7 @@ py.test calls hook functions to implement initialization, running, test execution and reporting. When py.test loads a plugin it validates that all hook functions conform to their respective hook specification. Each hook function name and its argument names need to match a hook -specification exactly but it is allowed for a hook function to accept +specification exactly but it is allowed for a hook function to accept *less* parameters than specified. If you mistype argument names or the hook name itself you get useful errors. @@ -261,7 +293,7 @@ Reference of important objects involved in hooks .. autoclass:: pytest.plugin.session.Node(name, parent) :members: -.. +.. .. autoclass:: pytest.plugin.session.File(fspath, parent) :members: diff --git a/doc/tmpdir.txt b/doc/tmpdir.txt index d71142efc..68d7b3f39 100644 --- a/doc/tmpdir.txt +++ b/doc/tmpdir.txt @@ -20,15 +20,15 @@ and more. Here is an example test usage:: p = tmpdir.mkdir("sub").join("hello.txt") p.write("content") assert p.read() == "content" - assert tmpdir.listdir() == 1 + assert len(tmpdir.listdir()) == 1 assert 0 -Running this would result in a passed test except for the last +Running this would result in a passed test except for the last ``assert 0`` line which we use to look at values:: - + $ py.test test_tmpdir.py =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_tmpdir.py test_tmpdir.py F @@ -36,13 +36,15 @@ Running this would result in a passed test except for the last ================================= FAILURES ================================= _____________________________ test_create_file _____________________________ - tmpdir = local('/tmp/pytest-1248/test_create_file0') + tmpdir = local('/tmp/pytest-243/test_create_file0') def test_create_file(tmpdir): p = tmpdir.mkdir("sub").join("hello.txt") p.write("content") assert p.read() == "content" - assert len(os.listdir(str(tmpdir))) == 1 + assert len(tmpdir.listdir()) == 1 + > assert 0 + E assert 0 test_tmpdir.py:7: AssertionError ========================= 1 failed in 0.04 seconds ========================= @@ -52,7 +54,7 @@ Running this would result in a passed test except for the last the default base temporary directory ----------------------------------------------- -.. +.. You can create directories by calling one of two methods on the config object: - ``config.mktemp(basename)``: create and return a new tempdir @@ -61,14 +63,14 @@ the default base temporary directory Temporary directories are by default created as sub directories of the system temporary directory. The name will be ``pytest-NUM`` where ``NUM`` will be incremenated with each test run. Moreover, entries older -than 3 temporary directories will be removed. +than 3 temporary directories will be removed. You can override the default temporary directory logic and set it like this:: py.test --basetemp=mydir -When distributing tests on the local machine, ``py.test`` takes care to -configure a basetemp directory for the sub processes such that all +When distributing tests on the local machine, ``py.test`` takes care to +configure a basetemp directory for the sub processes such that all temporary data lands below below a single per-test run basetemp directory. .. _`py.path.local`: http://pylib.org/path.html diff --git a/doc/unittest.txt b/doc/unittest.txt index 8d8872178..23ef882bf 100644 --- a/doc/unittest.txt +++ b/doc/unittest.txt @@ -24,7 +24,7 @@ Running it yields:: $ py.test test_unittest.py =========================== test session starts ============================ - platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev17 + platform linux2 -- Python 2.6.5 -- pytest-2.0.0.dev19 test path 1: test_unittest.py test_unittest.py F @@ -32,7 +32,7 @@ Running it yields:: ================================= FAILURES ================================= ____________________________ MyTest.test_method ____________________________ - self = + self = def test_method(self): x = 1 @@ -41,7 +41,7 @@ Running it yields:: test_unittest.py:8: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ - self = , first = 1, second = 3 + self = , first = 1, second = 3 msg = None def failUnlessEqual(self, first, second, msg=None): diff --git a/pytest/plugin/assertion.py b/pytest/plugin/assertion.py index b433eb0a9..33e6a1706 100644 --- a/pytest/plugin/assertion.py +++ b/pytest/plugin/assertion.py @@ -1,3 +1,6 @@ +""" +support for presented detailed information in failing assertions. +""" import py import sys diff --git a/pytest/plugin/capture.py b/pytest/plugin/capture.py index 38a9d431a..013da9b81 100644 --- a/pytest/plugin/capture.py +++ b/pytest/plugin/capture.py @@ -1,6 +1,4 @@ -""" plugin for configurable per-test stdout/stderr capturing mechanisms and -``capsys`` and ``capfd`` function arguments. -""" +""" per-test stdout/stderr capturing mechanisms, ``capsys`` and ``capfd`` function arguments. """ import py import os diff --git a/pytest/plugin/config.py b/pytest/plugin/config.py index 365c73e81..756afec71 100644 --- a/pytest/plugin/config.py +++ b/pytest/plugin/config.py @@ -1,10 +1,10 @@ +""" command line configuration, ini-file and conftest.py processing. """ import py import sys, os from pytest.main import PluginManager import pytest - def pytest_cmdline_parse(pluginmanager, args): config = Config(pluginmanager) config.parse(args) diff --git a/pytest/plugin/doctest.py b/pytest/plugin/doctest.py index 43033d6b9..092b55b75 100644 --- a/pytest/plugin/doctest.py +++ b/pytest/plugin/doctest.py @@ -1,4 +1,4 @@ -""" collect and execute doctests from modules and test files.""" +""" discover and run doctests in modules and test files.""" import py from py._code.code import TerminalRepr, ReprFileLocation diff --git a/pytest/plugin/genscript.py b/pytest/plugin/genscript.py index a9188add9..6814610a5 100755 --- a/pytest/plugin/genscript.py +++ b/pytest/plugin/genscript.py @@ -1,3 +1,4 @@ +""" generate a single-file self-contained version of py.test """ import py import pickle import zlib diff --git a/pytest/plugin/helpconfig.py b/pytest/plugin/helpconfig.py index ba813b759..4b632cf56 100644 --- a/pytest/plugin/helpconfig.py +++ b/pytest/plugin/helpconfig.py @@ -1,5 +1,4 @@ -""" provide version info, conftest/environment config names. -""" +""" version info, help messages, tracing configuration. """ import py import pytest import inspect, sys diff --git a/pytest/plugin/junitxml.py b/pytest/plugin/junitxml.py index d50056c1e..795dea03a 100644 --- a/pytest/plugin/junitxml.py +++ b/pytest/plugin/junitxml.py @@ -1,5 +1,6 @@ -""" logging of test results in JUnit-XML format, for use with Hudson - and build integration servers. Based on initial code from Ross Lawley. +""" report test results in JUnit-XML format, for use with Hudson and build integration servers. + +Based on initial code from Ross Lawley. """ import py diff --git a/pytest/plugin/mark.py b/pytest/plugin/mark.py index 5267cab72..d9f40d59d 100644 --- a/pytest/plugin/mark.py +++ b/pytest/plugin/mark.py @@ -70,7 +70,7 @@ def matchonekeyword(key, itemkeywords): return True class MarkGenerator: - """ Factory for :class:`MarkDecorator` objects - exposed as + """ Factory for :class:`MarkDecorator` objects - exposed as a ``py.test.mark`` singleton instance. Example:: import py @@ -88,8 +88,8 @@ class MarkGenerator: class MarkDecorator: """ A decorator for test functions and test classes. When applied - it will create :class:`MarkInfo` objects which may be - :ref:`retrieved by hooks as item keywords` MarkDecorator instances + it will create :class:`MarkInfo` objects which may be + :ref:`retrieved by hooks as item keywords` MarkDecorator instances are usually created by writing:: mark1 = py.test.mark.NAME # simple MarkDecorator diff --git a/pytest/plugin/monkeypatch.py b/pytest/plugin/monkeypatch.py index 83d1a7c7a..1ab0b382f 100644 --- a/pytest/plugin/monkeypatch.py +++ b/pytest/plugin/monkeypatch.py @@ -66,7 +66,7 @@ class monkeypatch: def setenv(self, name, value, prepend=None): """ set environment variable ``name`` to ``value``. if ``prepend`` - is a character, read the current environment variable value + is a character, read the current environment variable value and prepend the ``value`` adjoined with the ``prepend`` character.""" value = str(value) if prepend and name in os.environ: diff --git a/pytest/plugin/nose.py b/pytest/plugin/nose.py index a94a8a209..69cfc6cf2 100644 --- a/pytest/plugin/nose.py +++ b/pytest/plugin/nose.py @@ -1,42 +1,5 @@ -"""nose-compatibility plugin: allow to run nose test suites natively. +"""run test suites written for nose. """ -This is an experimental plugin for allowing to run tests written -in 'nosetests style with py.test. - -Usage -------------- - -type:: - - py.test # instead of 'nosetests' - -and you should be able to run nose style tests and at the same -time can make full use of py.test's capabilities. - -Supported nose Idioms ----------------------- - -* setup and teardown at module/class/method level -* SkipTest exceptions and markers -* setup/teardown decorators -* yield-based tests and their setup -* general usage of nose utilities - -Unsupported idioms / issues ----------------------------------- - -- nose-style doctests are not collected and executed correctly, - also fixtures don't work. - -- no nose-configuration is recognized - -If you find other issues or have suggestions please run:: - - py.test --pastebin=all - -and send the resulting URL to a py.test contact channel, -at best to the mailing list. -""" import py import inspect import sys diff --git a/pytest/plugin/pdb.py b/pytest/plugin/pdb.py index 1414586fc..2c4681e1f 100644 --- a/pytest/plugin/pdb.py +++ b/pytest/plugin/pdb.py @@ -1,6 +1,5 @@ -""" -interactive debugging with the Python Debugger. -""" +""" interactive debugging with PDB, the Python Debugger. """ + import py import sys diff --git a/pytest/plugin/pytester.py b/pytest/plugin/pytester.py index 7a67ea000..d3eb76d03 100644 --- a/pytest/plugin/pytester.py +++ b/pytest/plugin/pytester.py @@ -1,6 +1,4 @@ -""" -funcargs and support code for testing py.test's own functionality. -""" +""" (disabled by default) support for testing py.test and py.test plugins. """ import py, pytest import sys, os diff --git a/pytest/plugin/python.py b/pytest/plugin/python.py index c0bc4c557..de9db73c7 100644 --- a/pytest/plugin/python.py +++ b/pytest/plugin/python.py @@ -1,6 +1,4 @@ -""" -Python related collection nodes. -""" +""" Python test discovery, setup and run of test functions. """ import py import inspect import sys diff --git a/pytest/plugin/recwarn.py b/pytest/plugin/recwarn.py index d6a7b3ac6..41cf48c51 100644 --- a/pytest/plugin/recwarn.py +++ b/pytest/plugin/recwarn.py @@ -1,4 +1,4 @@ -""" record warnings to allow assertions about them. """ +""" recording warnings during test function execution. """ import py import sys, os diff --git a/pytest/plugin/resultlog.py b/pytest/plugin/resultlog.py index b3685f291..f4555860c 100644 --- a/pytest/plugin/resultlog.py +++ b/pytest/plugin/resultlog.py @@ -1,4 +1,4 @@ -""" create machine readable plain text file with results. """ +""" (disabled by default) create result information in a plain text file. """ import py from py.builtin import print_ diff --git a/pytest/plugin/runner.py b/pytest/plugin/runner.py index dd118b20a..6673ccf53 100644 --- a/pytest/plugin/runner.py +++ b/pytest/plugin/runner.py @@ -1,6 +1,4 @@ -""" -collect and run test items and create reports. -""" +""" basic collect and runtest protocol implementations """ import py, sys from py._code.code import TerminalRepr @@ -92,11 +90,12 @@ def call_runtest_hook(item, when): return CallInfo(lambda: ihook(item=item), when=when) class CallInfo: - """ Call Information about a hook call. """ + """ Result/Exception info a function invocation. """ #: None or ExceptionInfo object. excinfo = None def __init__(self, func, when): - #: one of "setup", "call", "teardown" specifying the runtest phase. + #: context of invocation: one of "setup", "call", + #: "teardown", "memocollect" self.when = when try: self.result = func() diff --git a/pytest/plugin/session.py b/pytest/plugin/session.py index ec3f94d57..8fa6442be 100644 --- a/pytest/plugin/session.py +++ b/pytest/plugin/session.py @@ -1,8 +1,4 @@ -""" basic test session implementation. - -* drives collection of tests -* triggers executions of tests -""" +""" core implementation of testing process: init, collection, runtest loop. """ import py import pytest @@ -174,10 +170,10 @@ class Node(object): #: the test config object self.config = config or parent.config - #: the collection this node is part of. + #: the collection this node is part of self.collection = collection or parent.collection - #: the file where this item is contained/collected from. + #: filesystem path where this node was collected from self.fspath = getattr(parent, 'fspath', None) self.ihook = self.collection.gethookproxy(self.fspath) self.keywords = {self.name: True} diff --git a/pytest/plugin/skipping.py b/pytest/plugin/skipping.py index 16ee811cd..c8044109d 100644 --- a/pytest/plugin/skipping.py +++ b/pytest/plugin/skipping.py @@ -1,6 +1,4 @@ -""" -plugin providing skip and xfail functionality. -""" +""" support for skip/xfail functions and markers. """ import py, pytest diff --git a/pytest/plugin/terminal.py b/pytest/plugin/terminal.py index ffc6070cc..da7414351 100644 --- a/pytest/plugin/terminal.py +++ b/pytest/plugin/terminal.py @@ -1,5 +1,4 @@ -""" -Implements terminal reporting of the full testing process. +""" terminal reporting of the full testing process. This is a good source for looking at the various reporting hooks. """ diff --git a/pytest/plugin/tmpdir.py b/pytest/plugin/tmpdir.py index 0dde811aa..738304442 100644 --- a/pytest/plugin/tmpdir.py +++ b/pytest/plugin/tmpdir.py @@ -1,13 +1,4 @@ -"""provide temporary directories to test functions. - -usage example:: - - def test_plugin(tmpdir): - tmpdir.join("hello").write("hello") - -.. _`py.path.local`: ../../path.html - -""" +""" support for providing temporary directories to test functions. """ import pytest, py def pytest_configure(config): diff --git a/pytest/plugin/unittest.py b/pytest/plugin/unittest.py index 9bf156e23..ce2d0efd0 100644 --- a/pytest/plugin/unittest.py +++ b/pytest/plugin/unittest.py @@ -1,6 +1,4 @@ -""" -automatically discover and run traditional "unittest.py" style tests. -""" +""" support discovery and running of traditional "unittest.py" style tests. """ import py import sys