largely improve and reshuffle docs, heading strongly towards a 1.1.0
--HG-- branch : trunk
This commit is contained in:
holger krekel
+44
-40
@@ -13,75 +13,79 @@ On naming, nosetests, licensing and magic
|
||||
Why the ``py`` naming? what is it?
|
||||
------------------------------------
|
||||
|
||||
Because the name was kind of available and there was the
|
||||
Because the name was available and there was the
|
||||
idea to have the package evolve into a "standard" library
|
||||
kind of thing that works cross-python versions and is
|
||||
not tied to a particular CPython revision or its release
|
||||
cycle. Clearly, this was ambitious and the naming
|
||||
has maybe haunted the project rather than helping it.
|
||||
There may be a project name change and possibly a
|
||||
split up into different projects sometime.
|
||||
|
||||
Why the ``py.test`` naming?
|
||||
------------------------------------
|
||||
|
||||
the py lib contains other command line tools that
|
||||
all share the ``py.`` prefix which makes it easy
|
||||
to use TAB-completion on the shell. Another motivation
|
||||
was to make it obvious where testing functionality
|
||||
for the ``py.test`` command line tool is: in the
|
||||
``py.test`` package name space.
|
||||
because of TAB-completion under Bash/Shells. If you hit
|
||||
``py.<TAB>`` you'll get a list of available development
|
||||
tools that all share the ``py.`` prefix. Another motivation
|
||||
was to unify the package ("py.test") and tool filename.
|
||||
|
||||
What's py.test's relation to ``nosetests``?
|
||||
---------------------------------------------
|
||||
|
||||
py.test and nose_ share basic philosophy when it comes
|
||||
to running Python tests. In fact,
|
||||
with py.test-1.0.1 it is easy to run many test suites
|
||||
with py.test-1.1.0 it is ever easier to run many test suites
|
||||
that currently work with ``nosetests``. nose_ was created
|
||||
as a clone of ``py.test`` when it was in the ``0.8`` release
|
||||
as a clone of ``py.test`` when py.test was in the ``0.8`` release
|
||||
cycle so some of the newer features_ introduced with py.test-1.0
|
||||
have no counterpart in nose_.
|
||||
and py.test-1.1 have no counterpart in nose_.
|
||||
|
||||
.. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/
|
||||
.. _features: test/features.html
|
||||
.. _apipkg: http://pypi.python.org/pypi/apipkg
|
||||
|
||||
What's all this "magic" with py.test?
|
||||
|
||||
What's this "magic" with py.test?
|
||||
----------------------------------------
|
||||
|
||||
"All this magic" usually boils down to two issues:
|
||||
issues where people have used the term "magic" in the past:
|
||||
|
||||
* There is a special tweak to importing: `py/__init__.py`_ contains
|
||||
a dictionary which maps the importable ``py.*`` namespaces to
|
||||
objects in files. When looking at the project source code
|
||||
you see imports like ``from py.__.test.session import Session``. The
|
||||
the double ``__`` underscore indicates the "normal" python
|
||||
filesystem/namespace coupled import, i.e. it points to
|
||||
``py/test/session.py``'s ``Session`` object. However,
|
||||
from the outside you use the "non-underscore" `py namespaces`_
|
||||
so this distinction usually only shows up if you hack
|
||||
on internal code or see internal tracebacks.
|
||||
* `py/__init__.py`_ uses the apipkg_ mechanism for lazy-importing
|
||||
and full control on what API you get when importing "import py".
|
||||
|
||||
* when an ``assert`` fails, py.test re-interprets the expression
|
||||
to show intermediate values. This allows to use the plain ``assert``
|
||||
statement instead of the many methods that you otherwise need
|
||||
to mimick this behaviour. This means that in case of a failing
|
||||
assert, your expressions gets evaluated *twice*. If your expression
|
||||
has side effects the outcome may be different. If the test suddenly
|
||||
passes you will get a detailed message. It is good practise, anyway,
|
||||
to not have asserts with side effects. ``py.test --nomagic`` turns
|
||||
off assert re-intepretation.
|
||||
* when an ``assert`` statement fails, py.test re-interprets the expression
|
||||
to show intermediate values if a test fails. If your expression
|
||||
has side effects the intermediate values may not be the same, obfuscating
|
||||
the initial error (this is also explained at the command line if it happens).
|
||||
``py.test --no-assert`` turns off assert re-intepretation.
|
||||
Sidenote: it is good practise to avoid asserts with side effects.
|
||||
|
||||
Other than that, ``py.test`` has bugs or quirks like any other computer
|
||||
software. In fact, it has a *strong* focus on running robustly and has
|
||||
over a thousand automated tests for its own code base.
|
||||
|
||||
.. _`py namespaces`: index.html
|
||||
.. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/1.0.x/py/__init__.py
|
||||
.. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py
|
||||
|
||||
|
||||
function arguments and parametrized tests
|
||||
===============================================
|
||||
function arguments, parametrized tests and setup
|
||||
====================================================
|
||||
|
||||
.. _funcargs: test/funcargs.html
|
||||
|
||||
Is using funcarg- versus xUnit-based setup a style question?
|
||||
---------------------------------------------------------------
|
||||
|
||||
It depends. For simple applications or for people experienced
|
||||
with nose_ or unittest-style test setup using `xUnit style setup`_
|
||||
make some sense. For larger test suites, parametrized testing
|
||||
or setup of complex test resources using funcargs_ is recommended.
|
||||
Moreover, funcargs are ideal for writing advanced test support
|
||||
code (like e.g. the monkeypatch_, the tmpdir_ or capture_ funcargs)
|
||||
because the support code can register setup/teardown functions
|
||||
in a managed class/module/function scope.
|
||||
|
||||
.. _monkeypatch: test/plugin/monkeypatch.html
|
||||
.. _tmpdir: test/plugin/tmpdir.html
|
||||
.. _capture: test/plugin/capture.html
|
||||
.. _`xUnit style setup`: test/xunit_setup.html
|
||||
.. _`pytest_nose`: test/plugin/nose.html
|
||||
|
||||
.. _`why pytest_pyfuncarg__ methods?`:
|
||||
|
||||
@@ -94,7 +98,7 @@ flexibility we decided to go for `Convention over Configuration`_ and
|
||||
allow to directly specify the factory. Besides removing the need
|
||||
for an indirection it allows to "grep" for ``pytest_funcarg__MYARG``
|
||||
and will safely find all factory functions for the ``MYARG`` function
|
||||
argument. It helps to alleviates the de-coupling of function
|
||||
argument. It helps to alleviate the de-coupling of function
|
||||
argument usage and creation.
|
||||
|
||||
.. _`Convention over Configuration`: http://en.wikipedia.org/wiki/Convention_over_Configuration
|
||||
|
||||
Reference in New Issue
Block a user