diff --git a/CHANGELOG b/CHANGELOG index 5103b5bf6..fd49778f9 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -4,6 +4,9 @@ Changes between 2.2.4 and 2.2.5.dev - fix issue128: show captured output when capsys/capfd are used - pluginmanager.register(...) now raises ValueError if the plugin has been already registered or the name is taken +- fix issue129: improve http://pytest.org/latest/faq.html + especially with respect to the "magic" history, also mention + pytest-django, trial and unittest integration. Changes between 2.2.3 and 2.2.4 ----------------------------------- diff --git a/doc/en/assert.txt b/doc/en/assert.txt index 519a712a2..81b687b87 100644 --- a/doc/en/assert.txt +++ b/doc/en/assert.txt @@ -2,6 +2,7 @@ The writing and reporting of assertions in tests ================================================== +.. _`assertfeedback`: .. _`assert with the assert statement`: Asserting with the ``assert`` statement diff --git a/doc/en/conf.py b/doc/en/conf.py index a07687df1..58705744d 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -17,7 +17,7 @@ # # The full version, including alpha/beta/rc tags. # The short X.Y version. -version = release = "2.2.4.2" +version = release = "2.2.4.3" import sys, os diff --git a/doc/en/customize.txt b/doc/en/customize.txt index 7fee9b851..6719c01cb 100644 --- a/doc/en/customize.txt +++ b/doc/en/customize.txt @@ -23,8 +23,9 @@ It looks for file basenames in this order:: tox.ini setup.cfg -Searching stops when the first ``[pytest]`` section is found. -There is no merging of configuration values from multiple files. Example:: +Searching stops when the first ``[pytest]`` section is found in any of +these files. There is no merging of configuration values from multiple +files. Example:: py.test path/to/testdir diff --git a/doc/en/faq.txt b/doc/en/faq.txt index b27f3764a..83c2ba9b8 100644 --- a/doc/en/faq.txt +++ b/doc/en/faq.txt @@ -9,6 +9,75 @@ Some Issues and Questions On naming, nosetests, licensing and magic ------------------------------------------------ +How does py.test relate to nose and unittest? ++++++++++++++++++++++++++++++++++++++++++++++++++ + +py.test and nose_ share basic philosophy when it comes +to running and writing Python tests. In fact, you can run many tests +written for nose with py.test. nose_ was originally created +as a clone of ``py.test`` when py.test was in the ``0.8`` release +cycle. Note that starting with pytest-2.0 support for running unittest +test suites is majorly improved. + +how does py.test relate to twisted's trial? +++++++++++++++++++++++++++++++++++++++++++++++ + +Since some time py.test has builtin support for supporting tests +written using trial. It does not itself start a reactor, however, +and does not handle Deferreds returned from a test. Someone using +these features might eventually write a dedicated ``pytest-twisted`` +plugin which will surely see strong support from the pytest development +team. + +how does py.test work with Django? +++++++++++++++++++++++++++++++++++++++++++++++ + +In 2012, some work is going into the `pytest-django plugin `_. It substitutes the usage of Django's +``manage.py test`` and allows to use all pytest features_ most of which +are not available from Django directly. + +.. _features: test/features.html + + +What's this "magic" with py.test? (historic notes) +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Around 2007 (version ``0.8``) some people thought that py.test +was using too much "magic". It had been part of the `pylib`_ which +contains a lot of unreleated python library code. Around 2010 there +was a major cleanup refactoring, which removed unused or deprecated code +and resulted in the new ``pytest`` PyPI package which strictly contains +only test-related code. This relese also brought a complete pluginification +such that the core is around 300 lines of code and everything else is +implemented in plugins. Thus ``pytest`` today is a small, universally runnable +and customizable testing framework for Python. Note, however, that +``pytest`` uses metaprogramming techniques and reading its source is +thus likely not something for Python beginners. + +A second "magic" issue was the assert statement debugging feature. +Nowadays, py.test explicitely rewrites assert statements in test modules +in order to provide more useful :ref:`assert feedback `. +This completely avoids previous issues of confusing assertion-reporting. +It also means, that you can use Python's ``-O`` optimization without loosing +assertions in test modules. + +py.test contains a second assert debugging technique, invoked via +``--assert=reinterpret``, activated by default on Python-2.5: When an +``assert`` statement that was missed by the rewriter fails, py.test +re-interprets the expression to show intermediate values if a test +fails. This second technique suffers from a caveat that the rewriting +does not: If your expression has side effects (better to avoid them +anyway!) the intermediate values may not be the same, confusing the +reinterpreter and obfuscating the initial error (this is also explained +at the command line if it happens). + +You can also turn off all assertion interaction using the +``--assertmode=off`` option. + +.. _`py namespaces`: index.html +.. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py + + Why a ``py.test`` instead of a ``pytest`` command? ++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -20,48 +89,7 @@ you install ``pip install pycmd`` you get these tools from a separate package. These days the command line tool could be called ``pytest`` but since many people have gotten used to the old name and there is another tool named "pytest" we just decided to stick with -``py.test``. - -How does py.test relate to nose and unittest? -+++++++++++++++++++++++++++++++++++++++++++++++++ - -py.test and nose_ share basic philosophy when it comes -to running and writing Python tests. In fact, you can run many tests -written for nose with py.test. nose_ was originally created -as a clone of ``py.test`` when py.test was in the ``0.8`` release -cycle. Note that starting with pytest-2.0 support for running unittest -test suites is majorly improved and you should be able to run -many Django and Twisted test suites without modification. - -.. _features: test/features.html - - -What's this "magic" with py.test? -++++++++++++++++++++++++++++++++++++++++++ - -Around 2007 (version ``0.8``) some people claimed that py.test -was using too much "magic". Partly this has been fixed by removing -unused, deprecated or complicated code. It is today probably one -of the smallest, most universally runnable and most -customizable testing frameworks for Python. However, -``py.test`` still uses many metaprogramming techniques and -reading its source is thus likely not something for Python beginners. - -A second "magic" issue is arguably the assert statement debugging feature. When -loading test modules py.test rewrites the source code of assert statements. When -a rewritten assert statement fails, its error message has more information than -the original. py.test also has a second assert debugging technique. When an -``assert`` statement that was missed by the rewriter fails, py.test -re-interprets the expression to show intermediate values if a test fails. This -second technique suffers from a caveat that the rewriting does not: If your -expression has side effects (better to avoid them anyway!) the intermediate -values may not be the same, confusing the reinterpreter and obfuscating the -initial error (this is also explained at the command line if it happens). -You can turn off all assertion debugging with ``py.test --assertmode=off``. - -.. _`py namespaces`: index.html -.. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py - +``py.test`` for now. Function arguments, parametrized tests and setup ------------------------------------------------------- diff --git a/doc/en/links.inc b/doc/en/links.inc index e627f780d..90e29eb3c 100644 --- a/doc/en/links.inc +++ b/doc/en/links.inc @@ -18,3 +18,4 @@ .. _hudson: http://hudson-ci.org/ .. _jenkins: http://jenkins-ci.org/ .. _tox: http://codespeak.net/tox +.. _pylib: http://pylib.org