fix py31 compat, amend setup.py long description

- python/collect.py cotaining the core collection nodes
- python/fixture.py containing funcargs/fixture code
- python/metafunc.py generate_tests and metafunc usage
- python/raises.py the pytest.raises implementation

.hgignore

@@ -15,7 +15,7 @@ syntax:glob
 *.orig
 *~
 
-doc/_build
+doc/*/_build
 build/
 dist/
 *.egg-info
@@ -23,3 +23,5 @@ issue/
 env/
 3rdparty/
 .tox
+.cache
+.coverage

.hgtags

@@ -48,3 +48,7 @@ e5e1746a197f0398356a43fbe2eebac9690f795d 2.1.0
 3da8cec6c5326ed27c144c9b6d7a64a648370005 2.2.1
 92b916483c1e65a80dc80e3f7816b39e84b36a4d 2.2.2
 3c11c5c9776f3c678719161e96cc0a08169c1cb8 2.2.3
+ad9fe504a371ad8eb613052d58f229aa66f53527 2.2.4
+c27a60097767c16a54ae56d9669a77925b213b9b 2.3.0
+acf0e1477fb19a1d35a4e40242b77fa6af32eb17 2.3.1
+8738b828dec53937765db71951ef955cca4c51f6 2.3.2

CHANGELOG

@@ -1,3 +1,160 @@
+Changes between 2.3.2 and 2.3.3
+-----------------------------------
+
+- fix issue214 - parse modules that contain special objects like e. g.
+  flask's request object which blows up on getattr access if no request
+  is active. thanks Thomas Waldmann.
+
+- fix issue213 - allow to parametrize with values like numpy arrays that
+  do not support an __eq__ operator
+
+- fix issue215 - split test_python.org into multiple files
+
+- fix issue148 - @unittest.skip on classes is now recognized and avoids
+  calling setUpClass/tearDownClass, thanks Pavel Repin
+
+- fix issue209 - reintroduce python2.4 support by depending on newer
+  pylib which re-introduced statement-finding for pre-AST interpreters
+
+- nose support: only call setup if its a callable, thanks Andrew
+  Taumoefolau
+
+- fix issue219 - add py2.4-3.3 classifiers to TROVE list
+
+- in tracebacks *,** arg values are now shown next to normal arguments
+  (thanks Manuel Jacob)
+
+- fix issue217 - support mock.patch with pytest's fixtures - note that
+  you need either mock-1.0.1 or the python3.3 builtin unittest.mock.
+
+- fix issue127 - improve documentation for pytest_addoption() and
+  add a ``config.getoption(name)`` helper function for consistency.
+
+Changes between 2.3.1 and 2.3.2
+-----------------------------------
+
+- fix issue208 and fix issue29 use new py version to avoid long pauses 
+  when printing tracebacks in long modules
+
+- fix issue205 - conftests in subdirs customizing
+  pytest_pycollect_makemodule and pytest_pycollect_makeitem
+  now work properly
+
+- fix teardown-ordering for parametrized setups
+
+- fix issue127 - better documentation for pytest_addoption
+  and related objects.
+
+- fix unittest behaviour: TestCase.runtest only called if there are
+  test methods defined
+
+- improve trial support: don't collect its empty
+  unittest.TestCase.runTest() method
+
+- "python setup.py test" now works with pytest itself
+
+- fix/improve internal/packaging related bits:
+
+  - exception message check of test_nose.py now passes on python33 as well
+
+  - issue206 - fix test_assertrewrite.py to work when a global
+    PYTHONDONTWRITEBYTECODE=1 is present
+
+  - add tox.ini to pytest distribution so that ignore-dirs and others config
+    bits are properly distributed for maintainers who run pytest-own tests
+
+Changes between 2.3.0 and 2.3.1
+-----------------------------------
+
+- fix issue202 - fix regression: using "self" from fixture functions now
+  works as expected (it's the same "self" instance that a test method
+  which uses the fixture sees)
+
+- skip pexpect using tests (test_pdb.py mostly) on freebsd* systems
+  due to pexpect not supporting it properly (hanging)
+
+- link to web pages from --markers output which provides help for
+  pytest.mark.* usage.
+
+Changes between 2.2.4 and 2.3.0
+-----------------------------------
+
+- fix issue202 - better automatic names for parametrized test functions
+- fix issue139 - introduce @pytest.fixture which allows direct scoping
+  and parametrization of funcarg factories. 
+- fix issue198 - conftest fixtures were not found on windows32 in some
+  circumstances with nested directory structures due to path manipulation issues
+- fix issue193 skip test functions with were parametrized with empty
+  parameter sets
+- fix python3.3 compat, mostly reporting bits that previously depended
+  on dict ordering
+- introduce re-ordering of tests by resource and parametrization setup
+  which takes precedence to the usual file-ordering
+- fix issue185 monkeypatching time.time does not cause pytest to fail
+- fix issue172 duplicate call of pytest.fixture decoratored setup_module
+  functions
+- fix junitxml=path construction so that if tests change the
+  current working directory and the path is a relative path
+  it is constructed correctly from the original current working dir.
+- fix "python setup.py test" example to cause a proper "errno" return
+- fix issue165 - fix broken doc links and mention stackoverflow for FAQ
+- catch unicode-issues when writing failure representations
+  to terminal to prevent the whole session from crashing
+- fix xfail/skip confusion: a skip-mark or an imperative pytest.skip
+  will now take precedence before xfail-markers because we
+  can't determine xfail/xpass status in case of a skip. see also:
+  http://stackoverflow.com/questions/11105828/in-py-test-when-i-explicitly-skip-a-test-that-is-marked-as-xfail-how-can-i-get
+
+- always report installed 3rd party plugins in the header of a test run
+
+- fix issue160: a failing setup of an xfail-marked tests should
+  be reported as xfail (not xpass)
+
+- fix issue128: show captured output when capsys/capfd are used
+
+- fix issue179: propperly show the dependency chain of factories
+
+- pluginmanager.register(...) now raises ValueError if the
+  plugin has been already registered or the name is taken
+
+- fix issue159: improve http://pytest.org/latest/faq.html 
+  especially with respect to the "magic" history, also mention
+  pytest-django, trial and unittest integration.
+
+- make request.keywords and node.keywords writable.  All descendant
+  collection nodes will see keyword values.  Keywords are dictionaries
+  containing markers and other info.
+
+- fix issue 178: xml binary escapes are now wrapped in py.xml.raw
+
+- fix issue 176: correctly catch the builtin AssertionError
+  even when we replaced AssertionError with a subclass on the
+  python level
+
+- factory discovery no longer fails with magic global callables
+  that provide no sane __code__ object (mock.call for example)
+
+- fix issue 182: testdir.inprocess_run now considers passed plugins
+
+- fix issue 188: ensure sys.exc_info is clear on python2
+                 before calling into a test
+
+- fix issue 191: add unittest TestCase runTest method support
+- fix issue 156: monkeypatch correctly handles class level descriptors
+
+- reporting refinements:
+
+  - pytest_report_header now receives a "startdir" so that
+    you can use startdir.bestrelpath(yourpath) to show
+    nice relative path
+
+  - allow plugins to implement both pytest_report_header and 
+    pytest_sessionstart (sessionstart is invoked first).
+
+  - don't show deselected reason line if there is none
+
+  - py.test -vv will show all of assert comparisations instead of truncating
+
 Changes between 2.2.3 and 2.2.4
 -----------------------------------
 

ISSUES.txt

@@ -48,59 +48,6 @@ if the signature of a decorated function does not match. XXX is it
 not sufficient to always allow non-matches?
 
 
-unify item/request classes, generalize items
----------------------------------------------------------------
-tags: 2.4 wish
-
-in lieu of extended parametrization and the new way to specify resource
-factories in terms of the parametrize decorator, consider unification
-of the item and request class.  This also is connected with allowing
-funcargs in setup functions.  Example of new item API:
-
-    item.getresource("db")  # alias for request.getfuncargvalue
-    item.addfinalizer(...)
-    item.cached_setup(...)
-    item.applymarker(...)
-
-test classes/modules could then use this api via::
-
-    def pytest_runtest_setup(item):
-        use item API ...
-
-introduction of this new method needs to be _fully_ backward compatible -
-and the documentation needs to change along to mention this new way of
-doing things. 
-
-impl note: probably Request._fillfuncargs would be called from the
-python plugins own pytest_runtest_setup(item) and would call
-item.getresource(X) for all X in the funcargs of a function.
-
-XXX is it possible to even put the above item API to Nodes, i.e. also
-to Directorty/module/file/class collectors?  Problem is that current
-funcarg factories presume they are called with a per-function (even
-per-funcarg-per-function) scope.  Could there be small tweaks to the new
-API that lift this restriction?
-
-consider::
-
-    def setup_class(cls, tmpdir):
-        # would get a per-class tmpdir because tmpdir parametrization
-        # would know that it is called with a class scope
-        #
-        #
-        #
-this looks very difficult because those setup functions are also used
-by nose etc. Rather consider introduction of a new setup hook:
-
-    def setup_test(self, item):
-        self.db = item.cached_setup(..., scope='class')
-        self.tmpdir = item.getresource("tmpdir")
-
-this should be compatible to unittest/nose and provide much of what
-"testresources" provide.  XXX This would not allow full parametrization
-such that test function could be run multiple times with different
-values. See "parametrized attributes" issue.
-
 allow parametrized attributes on classes
 -------------------------------------------------- 
 
@@ -355,3 +302,31 @@ def test_run(pytester, fslayout):
     result = pytester.runpytest(p)
     assert result.ret == 0
     assert result.passed == 1
+
+Another idea is to allow to define a full scenario including the run
+in one content string::
+
+    runscenario("""
+        test_{TESTNAME}.py:
+            import pytest
+            @pytest.mark.xfail
+            def test_that_fails():
+                assert 0
+
+            @pytest.mark.skipif("True")
+            def test_hello():
+                pass
+
+        conftest.py:
+            import pytest
+            def pytest_runsetup_setup(item):
+                pytest.skip("abc")
+
+        runpytest -rsxX
+        *SKIP*{TESTNAME}*
+        *1 skipped* 
+    """)
+
+This could be run with at least three different ways to invoke pytest:
+through the shell, through "python -m pytest" and inlined. As inlined
+would be the fastest it could be run first (or "--fast" mode).

MANIFEST.in

@@ -2,6 +2,7 @@ include CHANGELOG
 include README.txt
 include setup.py
 include distribute_setup.py
+include tox.ini
 include LICENSE
 graft doc
 graft testing

_pytest/__init__.py

@@ -1,2 +1,2 @@
 #
-__version__ = '2.2.4'
+__version__ = '2.3.3'

_pytest/assertion/__init__.py

@@ -73,8 +73,12 @@ def pytest_runtest_setup(item):
     def callbinrepr(op, left, right):
         hook_result = item.ihook.pytest_assertrepr_compare(
             config=item.config, op=op, left=left, right=right)
+
         for new_expl in hook_result:
             if new_expl:
+                # Don't include pageloads of data unless we are very verbose (-vv)
+                if len(''.join(new_expl[1:])) > 80*8 and item.config.option.verbose < 2:
+                    new_expl[1:] = ['Detailed information too verbose, truncated']
                 res = '\n~'.join(new_expl)
                 if item.config.getvalue("assertmode") == "rewrite":
                     # The result will be fed back a python % formatting

_pytest/assertion/oldinterpret.py

@@ -526,10 +526,13 @@ if __name__ == '__main__':
     # example:
     def f():
         return 5
+
     def g():
         return 3
+
     def h(x):
         return 'never'
+
     check("f() * g() == 5")
     check("not f()")
     check("not (f() and g() or 0)")

_pytest/assertion/reinterpret.py

@@ -44,4 +44,3 @@ if sys.version_info >= (2, 6) or (sys.platform.startswith("java")):
     from _pytest.assertion.newinterpret import interpret as reinterpret
 else:
     reinterpret = reinterpret_old
-

_pytest/assertion/rewrite.py

@@ -34,13 +34,13 @@ else:
     PYTEST_TAG = "%s-%s%s-PYTEST" % (impl, ver[0], ver[1])
     del ver, impl
 
-PYC_EXT = ".py" + "c" if __debug__ else "o"
+PYC_EXT = ".py" + (__debug__ and "c" or "o")
 PYC_TAIL = "." + PYTEST_TAG + PYC_EXT
 
 REWRITE_NEWLINES = sys.version_info[:2] != (2, 7) and sys.version_info < (3, 2)
 
 class AssertionRewritingHook(object):
-    """Import hook which rewrites asserts."""
+    """PEP302 Import hook which rewrites asserts."""
 
     def __init__(self):
         self.session = None
@@ -95,7 +95,8 @@ class AssertionRewritingHook(object):
             finally:
                 self.session = sess
         else:
-            state.trace("matched test file (was specified on cmdline): %r" % (fn,))
+            state.trace("matched test file (was specified on cmdline): %r" %
+                        (fn,))
         # The requested module looks like a test file, so rewrite it. This is
         # the most magical part of the process: load the source, rewrite the
         # asserts, and load the rewritten source. We also cache the rewritten
@@ -121,14 +122,14 @@ class AssertionRewritingHook(object):
                     # because we're in a zip file.
                     write = False
                 elif e == errno.EACCES:
-                    state.trace("read only directory: %r" % (fn_pypath.dirname,))
+                    state.trace("read only directory: %r" % fn_pypath.dirname)
                     write = False
                 else:
                     raise
         cache_name = fn_pypath.basename[:-3] + PYC_TAIL
         pyc = os.path.join(cache_dir, cache_name)
-        # Notice that even if we're in a read-only directory, I'm going to check
-        # for a cached pyc. This may not be optimal...
+        # Notice that even if we're in a read-only directory, I'm going
+        # to check for a cached pyc. This may not be optimal...
         co = _read_pyc(fn_pypath, pyc)
         if co is None:
             state.trace("rewriting %r" % (fn,))
@@ -160,10 +161,11 @@ class AssertionRewritingHook(object):
         return sys.modules[name]
 
 def _write_pyc(co, source_path, pyc):
-    # Technically, we don't have to have the same pyc format as (C)Python, since
-    # these "pycs" should never be seen by builtin import. However, there's
-    # little reason deviate, and I hope sometime to be able to use
-    # imp.load_compiled to load them. (See the comment in load_module above.)
+    # Technically, we don't have to have the same pyc format as
+    # (C)Python, since these "pycs" should never be seen by builtin
+    # import. However, there's little reason deviate, and I hope
+    # sometime to be able to use imp.load_compiled to load them. (See
+    # the comment in load_module above.)
     mtime = int(source_path.mtime())
     try:
         fp = open(pyc, "wb")
@@ -240,9 +242,8 @@ def _read_pyc(source, pyc):
         except EnvironmentError:
             return None
         # Check for invalid or out of date pyc file.
-        if (len(data) != 8 or
-            data[:4] != imp.get_magic() or
-            struct.unpack("<l", data[4:])[0] != mtime):
+        if (len(data) != 8 or data[:4] != imp.get_magic() or
+                struct.unpack("<l", data[4:])[0] != mtime):
             return None
         co = marshal.load(fp)
         if not isinstance(co, types.CodeType):
@@ -280,35 +281,35 @@ def _call_reprcompare(ops, results, expls, each_obj):
 
 
 unary_map = {
-    ast.Not : "not %s",
-    ast.Invert : "~%s",
-    ast.USub : "-%s",
-    ast.UAdd : "+%s"
+    ast.Not: "not %s",
+    ast.Invert: "~%s",
+    ast.USub: "-%s",
+    ast.UAdd: "+%s"
 }
 
 binop_map = {
-    ast.BitOr : "|",
-    ast.BitXor : "^",
-    ast.BitAnd : "&",
-    ast.LShift : "<<",
-    ast.RShift : ">>",
-    ast.Add : "+",
-    ast.Sub : "-",
-    ast.Mult : "*",
-    ast.Div : "/",
-    ast.FloorDiv : "//",
-    ast.Mod : "%%", # escaped for string formatting
-    ast.Eq : "==",
-    ast.NotEq : "!=",
-    ast.Lt : "<",
-    ast.LtE : "<=",
-    ast.Gt : ">",
-    ast.GtE : ">=",
-    ast.Pow : "**",
-    ast.Is : "is",
-    ast.IsNot : "is not",
-    ast.In : "in",
-    ast.NotIn : "not in"
+    ast.BitOr: "|",
+    ast.BitXor: "^",
+    ast.BitAnd: "&",
+    ast.LShift: "<<",
+    ast.RShift: ">>",
+    ast.Add: "+",
+    ast.Sub: "-",
+    ast.Mult: "*",
+    ast.Div: "/",
+    ast.FloorDiv: "//",
+    ast.Mod: "%%", # escaped for string formatting
+    ast.Eq: "==",
+    ast.NotEq: "!=",
+    ast.Lt: "<",
+    ast.LtE: "<=",
+    ast.Gt: ">",
+    ast.GtE: ">=",
+    ast.Pow: "**",
+    ast.Is: "is",
+    ast.IsNot: "is not",
+    ast.In: "in",
+    ast.NotIn: "not in"
 }
 
 
@@ -341,7 +342,7 @@ class AssertionRewriter(ast.NodeVisitor):
         lineno = 0
         for item in mod.body:
             if (expect_docstring and isinstance(item, ast.Expr) and
-                isinstance(item.value, ast.Str)):
+                    isinstance(item.value, ast.Str)):
                 doc = item.value.s
                 if "PYTEST_DONT_REWRITE" in doc:
                     # The module has disabled assertion rewriting.
@@ -462,7 +463,8 @@ class AssertionRewriter(ast.NodeVisitor):
         body.append(raise_)
         # Clear temporary variables by setting them to None.
         if self.variables:
-            variables = [ast.Name(name, ast.Store()) for name in self.variables]
+            variables = [ast.Name(name, ast.Store())
+                         for name in self.variables]
             clear = ast.Assign(variables, ast.Name("None", ast.Load()))
             self.statements.append(clear)
         # Fix line numbers.
@@ -548,7 +550,8 @@ class AssertionRewriter(ast.NodeVisitor):
             new_kwarg, expl = self.visit(call.kwargs)
             arg_expls.append("**" + expl)
         expl = "%s(%s)" % (func_expl, ', '.join(arg_expls))
-        new_call = ast.Call(new_func, new_args, new_kwargs, new_star, new_kwarg)
+        new_call = ast.Call(new_func, new_args, new_kwargs,
+                            new_star, new_kwarg)
         res = self.assign(new_call)
         res_expl = self.explanation_param(self.display(res))
         outer_expl = "%s\n{%s = %s\n}" % (res_expl, res_expl, expl)

_pytest/assertion/util.py

@@ -116,16 +116,11 @@ def assertrepr_compare(op, left, right):
         excinfo = py.code.ExceptionInfo()
         explanation = ['(pytest_assertion plugin: representation of '
             'details failed. Probably an object has a faulty __repr__.)',
-            str(excinfo)
-            ]
-
+            str(excinfo)]
 
     if not explanation:
         return None
 
-    # Don't include pageloads of data, should be configurable
-    if len(''.join(explanation)) > 80*8:
-        explanation = ['Detailed information too verbose, truncated']
 
     return [summary] + explanation
 

_pytest/capture.py

@@ -119,22 +119,20 @@ class CaptureManager:
         return "", ""
 
     def activate_funcargs(self, pyfuncitem):
-        if not hasattr(pyfuncitem, 'funcargs'):
-            return
-        assert not hasattr(self, '_capturing_funcargs')
-        self._capturing_funcargs = capturing_funcargs = []
-        for name, capfuncarg in pyfuncitem.funcargs.items():
-            if name in ('capsys', 'capfd'):
-                capturing_funcargs.append(capfuncarg)
-                capfuncarg._start()
+        funcargs = getattr(pyfuncitem, "funcargs", None)
+        if funcargs is not None:
+            for name, capfuncarg in funcargs.items():
+                if name in ('capsys', 'capfd'):
+                    assert not hasattr(self, '_capturing_funcarg')
+                    self._capturing_funcarg = capfuncarg
+                    capfuncarg._start()
 
     def deactivate_funcargs(self):
-        capturing_funcargs = getattr(self, '_capturing_funcargs', None)
-        if capturing_funcargs is not None:
-            while capturing_funcargs:
-                capfuncarg = capturing_funcargs.pop()
-                capfuncarg._finalize()
-            del self._capturing_funcargs
+        capturing_funcarg = getattr(self, '_capturing_funcarg', None)
+        if capturing_funcarg:
+            outerr = capturing_funcarg._finalize()
+            del self._capturing_funcarg
+            return outerr
 
     def pytest_make_collect_report(self, __multicall__, collector):
         method = self._getmethod(collector.config, collector.fspath)
@@ -169,9 +167,12 @@ class CaptureManager:
 
     @pytest.mark.tryfirst
     def pytest_runtest_makereport(self, __multicall__, item, call):
-        self.deactivate_funcargs()
+        funcarg_outerr = self.deactivate_funcargs()
         rep = __multicall__.execute()
         outerr = self.suspendcapture(item)
+        if funcarg_outerr is not None:
+            outerr = (outerr[0] + funcarg_outerr[0],
+                      outerr[1] + funcarg_outerr[1])
         if not rep.passed:
             addouterr(rep, outerr)
         if not rep.passed or rep.when == "teardown":
@@ -179,23 +180,29 @@ class CaptureManager:
         item.outerr = outerr
         return rep
 
+error_capsysfderror = "cannot use capsys and capfd at the same time"
+
 def pytest_funcarg__capsys(request):
     """enables capturing of writes to sys.stdout/sys.stderr and makes
     captured output available via ``capsys.readouterr()`` method calls
     which return a ``(out, err)`` tuple.
     """
-    return CaptureFuncarg(py.io.StdCapture)
+    if "capfd" in request._funcargs:
+        raise request.raiseerror(error_capsysfderror)
+    return CaptureFixture(py.io.StdCapture)
 
 def pytest_funcarg__capfd(request):
     """enables capturing of writes to file descriptors 1 and 2 and makes
     captured output available via ``capsys.readouterr()`` method calls
     which return a ``(out, err)`` tuple.
     """
+    if "capsys" in request._funcargs:
+        request.raiseerror(error_capsysfderror)
     if not hasattr(os, 'dup'):
-        py.test.skip("capfd funcarg needs os.dup")
-    return CaptureFuncarg(py.io.StdCaptureFD)
+        pytest.skip("capfd funcarg needs os.dup")
+    return CaptureFixture(py.io.StdCaptureFD)
 
-class CaptureFuncarg:
+class CaptureFixture:
     def __init__(self, captureclass):
         self.capture = captureclass(now=False)
 
@@ -204,8 +211,9 @@ class CaptureFuncarg:
 
     def _finalize(self):
         if hasattr(self, 'capture'):
-            self.capture.reset()
+            outerr = self.capture.reset()
             del self.capture
+            return outerr
 
     def readouterr(self):
         return self.capture.readouterr()

_pytest/config.py

@@ -19,7 +19,7 @@ def pytest_unconfigure(config):
         fin()
 
 class Parser:
-    """ Parser for command line arguments. """
+    """ Parser for command line arguments and ini-file values.  """
 
     def __init__(self, usage=None, processopt=None):
         self._anonymous = OptionGroup("custom options", parser=self)
@@ -35,15 +35,17 @@ class Parser:
             if option.dest:
                 self._processopt(option)
 
-    def addnote(self, note):
-        self._notes.append(note)
-
     def getgroup(self, name, description="", after=None):
         """ get (or create) a named option Group.
 
-        :name: unique name of the option group.
+        :name: name of the option group.
         :description: long description for --help output.
         :after: name of other group, used for ordering --help output.
+
+        The returned group object has an ``addoption`` method with the same
+        signature as :py:func:`parser.addoption
+        <_pytest.config.Parser.addoption>` but will be shown in the
+        respective group in the output of ``pytest. --help``.
         """
         for group in self._groups:
             if group.name == name:
@@ -57,7 +59,19 @@ class Parser:
         return group
 
     def addoption(self, *opts, **attrs):
-        """ add an optparse-style option. """
+        """ register a command line option.
+
+        :opts: option names, can be short or long options.
+        :attrs: same attributes which the ``add_option()`` function of the
+           `optparse library
+           <http://docs.python.org/library/optparse.html#module-optparse>`_
+           accepts.
+
+        After command line parsing options are available on the pytest config
+        object via ``config.option.NAME`` where ``NAME`` is usually set
+        by passing a ``dest`` attribute, for example
+        ``addoption("--long", dest="NAME", ...)``.
+        """
         self._anonymous.addoption(*opts, **attrs)
 
     def parse(self, args):
@@ -78,7 +92,15 @@ class Parser:
         return args
 
     def addini(self, name, help, type=None, default=None):
-        """ add an ini-file option with the given name and description. """
+        """ register an ini-file option.
+
+        :name: name of the ini-variable
+        :type: type of the variable, can be ``pathlist``, ``args`` or ``linelist``.
+        :default: default value if no ini-file option exists but is queried.
+
+        The value of ini-variables can be retrieved via a call to
+        :py:func:`config.getini(name) <_pytest.config.Config.getini>`.
+        """
         assert type in (None, "pathlist", "args", "linelist")
         self._inidict[name] = (help, type, default)
         self._ininames.append(name)
@@ -154,20 +176,24 @@ class Conftest(object):
                     p = current.join(opt1[len(opt)+1:], abs=1)
                 self._confcutdir = p
                 break
-        for arg in args + [current]:
+        foundanchor = False
+        for arg in args:
             if hasattr(arg, 'startswith') and arg.startswith("--"):
                 continue
             anchor = current.join(arg, abs=1)
             if anchor.check(): # we found some file object
-                self._path2confmods[None] = self.getconftestmodules(anchor)
-                # let's also consider test* dirs
-                if anchor.check(dir=1):
-                    for x in anchor.listdir("test*"):
-                        if x.check(dir=1):
-                            self.getconftestmodules(x)
-                break
-        else:
-            assert 0, "no root of filesystem?"
+                self._try_load_conftest(anchor)
+                foundanchor = True
+        if not foundanchor:
+            self._try_load_conftest(current)
+
+    def _try_load_conftest(self, anchor):
+        self._path2confmods[None] = self.getconftestmodules(anchor)
+        # let's also consider test* subdirs
+        if anchor.check(dir=1):
+            for x in anchor.listdir("test*"):
+                if x.check(dir=1):
+                    self.getconftestmodules(x)
 
     def getconftestmodules(self, path):
         """ return a list of imported conftest modules for the given path.  """
@@ -245,8 +271,8 @@ class CmdOptions(object):
 class Config(object):
     """ access to configuration values, pluginmanager and plugin hooks.  """
     def __init__(self, pluginmanager=None):
-        #: command line option values, usually added via parser.addoption(...)
-        #: or parser.getgroup(...).addoption(...) calls
+        #: access to command line option as attributes.
+        #: (deprecated), use :py:func:`getoption() <_pytest.config.Config.getoption>` instead
         self.option = CmdOptions()
         self._parser = Parser(
             usage="usage: %prog [options] [file_or_dir] [file_or_dir] [...]",
@@ -258,6 +284,7 @@ class Config(object):
         self._conftest = Conftest(onimport=self._onimportconftest)
         self.hook = self.pluginmanager.hook
         self._inicache = {}
+        self._opt2dest = {}
         self._cleanup = []
 
     @classmethod
@@ -278,6 +305,9 @@ class Config(object):
         self.pluginmanager.consider_conftest(conftestmodule)
 
     def _processopt(self, opt):
+        for name in opt._short_opts + opt._long_opts:
+            self._opt2dest[name] = opt.dest
+
         if hasattr(opt, 'default') and opt.dest:
             if not hasattr(self.option, opt.dest):
                 setattr(self.option, opt.dest, opt.default)
@@ -356,8 +386,9 @@ class Config(object):
         x.append(line) # modifies the cached list inline
 
     def getini(self, name):
-        """ return configuration value from an ini file. If the
-        specified name hasn't been registered through a prior ``parse.addini``
+        """ return configuration value from an :ref:`ini file <inifiles>`. If the
+        specified name hasn't been registered through a prior
+        :py:func:`parser.addini <pytest.config.Parser.addini>`
         call (usually from a plugin), a ValueError is raised. """
         try:
             return self._inicache[name]
@@ -411,8 +442,22 @@ class Config(object):
             self._checkconftest(name)
         return self._conftest.rget(name, path)
 
+    def getoption(self, name):
+        """ return command line option value.
+
+        :arg name: name of the option.  You may also specify
+            the literal ``--OPT`` option instead of the "dest" option name.
+        """
+        name = self._opt2dest.get(name, name)
+        try:
+            return getattr(self.option, name)
+        except AttributeError:
+            raise ValueError("no option named %r" % (name,))
+
     def getvalue(self, name, path=None):
-        """ return ``name`` value looked set from command line options.
+        """ return command line option value.
+
+        :arg name: name of the command line option
 
         (deprecated) if we can't find the option also lookup
         the name in a matching conftest file.
@@ -450,14 +495,3 @@ def getcfg(args, inibasenames):
                         return iniconfig['pytest']
     return {}
 
-def findupwards(current, basename):
-    current = py.path.local(current)
-    while 1:
-        p = current.join(basename)
-        if p.check():
-            return p
-        p = current.dirpath()
-        if p == current:
-            return
-        current = p
-

_pytest/core.py

@@ -79,10 +79,11 @@ class PluginManager(object):
                 self.import_plugin(spec)
 
     def register(self, plugin, name=None, prepend=False):
-        assert not self.isregistered(plugin), plugin
+        if self._name2plugin.get(name, None) == -1:
+            return
         name = name or getattr(plugin, '__name__', str(id(plugin)))
-        if name in self._name2plugin:
-            return False
+        if self.isregistered(plugin, name):
+            raise ValueError("Plugin already registered: %s=%s" %(name, plugin))
         #self.trace("registering", name, plugin)
         self._name2plugin[name] = plugin
         self.call_plugin(plugin, "pytest_addhooks", {'pluginmanager': self})
@@ -462,9 +463,13 @@ def _prepareconfig(args=None, plugins=None):
             pluginmanager=_pluginmanager, args=args)
 
 def main(args=None, plugins=None):
-    """ returned exit code integer, after an in-process testing run
-    with the given command line arguments, preloading an optional list
-    of passed in plugin objects. """
+    """ return exit code, after performing an in-process test run.
+
+    :arg args: list of command line arguments.
+
+    :arg plugins: list of plugin objects to be auto-registered during
+                  initialization.
+    """
     config = _prepareconfig(args, plugins)
     exitstatus = config.hook.pytest_cmdline_main(config=config)
     return exitstatus

_pytest/helpconfig.py

@@ -79,6 +79,8 @@ def showhelp(config):
 
     tw.line() ; tw.line()
     #tw.sep("=")
+    tw.line("to see available markers type: py.test --markers")
+    tw.line("to see available fixtures type: py.test --fixtures")
     return
 
     tw.line("conftest.py options:")

_pytest/hookspec.py

@@ -23,8 +23,28 @@ def pytest_cmdline_preparse(config, args):
     """modify command line arguments before option parsing. """
 
 def pytest_addoption(parser):
-    """add optparse-style options and ini-style config values via calls
-    to ``parser.addoption`` and ``parser.addini(...)``.
+    """register optparse-style options and ini-style config values.
+
+    This function must be implemented in a :ref:`plugin <pluginorder>` and is
+    called once at the beginning of a test run.
+
+    :arg parser: To add command line options, call
+        :py:func:`parser.addoption(...) <_pytest.config.Parser.addoption>`.
+        To add ini-file values call :py:func:`parser.addini(...)
+        <_pytest.config.Parser.addini>`.
+
+    Options can later be accessed through the
+    :py:class:`config <_pytest.config.Config>` object, respectively:
+
+    - :py:func:`config.getoption(name) <_pytest.config.Config.getoption>` to
+      retrieve the value of a command line option.
+
+    - :py:func:`config.getini(name) <_pytest.config.Config.getini>` to retrieve
+      a value read from an ini-style file.
+
+    The config object is passed around on many internal objects via the ``.config``
+    attribute or can be retrieved as the ``pytestconfig`` fixture or accessed
+    via (deprecated) ``pytest.config``.
     """
 
 def pytest_cmdline_main(config):
@@ -33,7 +53,7 @@ def pytest_cmdline_main(config):
 pytest_cmdline_main.firstresult = True
 
 def pytest_configure(config):
-    """ called after command line options have been parsed.
+    """ called after command line options have been parsed
         and all plugins and initial conftest files been loaded.
     """
 
@@ -193,7 +213,7 @@ def pytest_assertrepr_compare(config, op, left, right):
 # hooks for influencing reporting (invoked from _pytest_terminal)
 # -------------------------------------------------------------------------
 
-def pytest_report_header(config):
+def pytest_report_header(config, startdir):
     """ return a string to be displayed as header info for terminal reporting."""
 
 def pytest_report_teststatus(report):

_pytest/impl

@@ -0,0 +1,254 @@
+Sorting per-resource
+-----------------------------
+
+for any given set of items:
+
+- collect items per session-scoped parametrized funcarg
+- re-order until items no parametrizations are mixed
+
+  examples:
+
+        test()
+        test1(s1)
+        test1(s2)     
+        test2()
+        test3(s1)
+        test3(s2)
+
+  gets sorted to:
+
+        test()
+        test2()
+        test1(s1)
+        test3(s1)
+        test1(s2)
+        test3(s2)
+ 
+
+the new @setup functions 
+--------------------------------------
+
+Consider a given @setup-marked function::
+
+    @pytest.mark.setup(maxscope=SCOPE)
+    def mysetup(request, arg1, arg2, ...)
+        ...
+        request.addfinalizer(fin)
+        ...
+
+then FUNCARGSET denotes the set of (arg1, arg2, ...) funcargs and
+all of its dependent funcargs.  The mysetup function will execute
+for any matching test item once per scope.  
+
+The scope is determined as the minimum scope of all scopes of the args
+in FUNCARGSET and the given "maxscope". 
+
+If mysetup has been called and no finalizers have been called it is
+called "active".
+
+Furthermore the following rules apply:
+
+- if an arg value in FUNCARGSET is about to be torn down, the 
+  mysetup-registered finalizers will execute as well.
+
+- There will never be two active mysetup invocations.
+
+Example 1, session scope::
+
+    @pytest.mark.funcarg(scope="session", params=[1,2])
+    def db(request):
+        request.addfinalizer(db_finalize)
+
+    @pytest.mark.setup
+    def mysetup(request, db):
+        request.addfinalizer(mysetup_finalize)
+        ...
+
+And a given test module:
+
+    def test_something():
+        ...
+    def test_otherthing():
+        pass
+
+Here is what happens::
+
+    db(request) executes with request.param == 1
+        mysetup(request, db) executes
+            test_something() executes
+            test_otherthing() executes
+            mysetup_finalize() executes
+    db_finalize() executes
+    db(request) executes with request.param == 2
+        mysetup(request, db) executes
+            test_something() executes
+            test_otherthing() executes
+        mysetup_finalize() executes
+    db_finalize() executes
+
+Example 2, session/function scope::
+
+    @pytest.mark.funcarg(scope="session", params=[1,2])
+    def db(request):
+        request.addfinalizer(db_finalize)
+
+    @pytest.mark.setup(scope="function")
+    def mysetup(request, db):
+        ...
+        request.addfinalizer(mysetup_finalize)
+        ...
+
+And a given test module:
+
+    def test_something():
+        ...
+    def test_otherthing():
+        pass
+
+Here is what happens::
+
+    db(request) executes with request.param == 1
+        mysetup(request, db) executes
+            test_something() executes
+        mysetup_finalize() executes
+        mysetup(request, db) executes
+            test_otherthing() executes
+        mysetup_finalize() executes
+    db_finalize() executes
+    db(request) executes with request.param == 2
+        mysetup(request, db) executes
+            test_something() executes
+        mysetup_finalize() executes
+        mysetup(request, db) executes
+            test_otherthing() executes
+        mysetup_finalize() executes
+    db_finalize() executes
+
+
+Example 3 - funcargs session-mix
+----------------------------------------
+
+Similar with funcargs, an example::
+
+    @pytest.mark.funcarg(scope="session", params=[1,2])
+    def db(request):
+        request.addfinalizer(db_finalize)
+
+    @pytest.mark.funcarg(scope="function")
+    def table(request, db):
+        ...
+        request.addfinalizer(table_finalize)
+        ...
+
+And a given test module:
+
+    def test_something(table):
+        ...
+    def test_otherthing(table):
+        pass
+    def test_thirdthing():
+        pass
+
+Here is what happens::
+
+    db(request) executes with param == 1
+        table(request, db)
+            test_something(table)
+        table_finalize()
+        table(request, db)
+            test_otherthing(table)
+        table_finalize()
+    db_finalize
+    db(request) executes with param == 2
+        table(request, db)
+            test_something(table)
+        table_finalize()
+        table(request, db)
+            test_otherthing(table)
+        table_finalize()
+    db_finalize
+    test_thirdthing()
+    
+Data structures
+--------------------
+
+pytest internally maintains a dict of active funcargs with cache, param,
+finalizer, (scopeitem?) information:
+
+    active_funcargs = dict()
+
+if a parametrized "db" is activated:
+    
+    active_funcargs["db"] = FuncargInfo(dbvalue, paramindex, 
+                                        FuncargFinalize(...), scopeitem)
+
+if a test is torn down and the next test requires a differently 
+parametrized "db":
+
+    for argname in item.callspec.params:
+        if argname in active_funcargs:
+            funcarginfo = active_funcargs[argname]
+            if funcarginfo.param != item.callspec.params[argname]:
+                funcarginfo.callfinalizer()
+                del node2funcarg[funcarginfo.scopeitem]
+                del active_funcargs[argname]
+    nodes_to_be_torn_down = ...
+    for node in nodes_to_be_torn_down:
+        if node in node2funcarg:
+            argname = node2funcarg[node]
+            active_funcargs[argname].callfinalizer()
+            del node2funcarg[node]
+            del active_funcargs[argname]
+
+if a test is setup requiring a "db" funcarg:
+
+    if "db" in active_funcargs:
+        return active_funcargs["db"][0]
+    funcarginfo = setup_funcarg()
+    active_funcargs["db"] = funcarginfo
+    node2funcarg[funcarginfo.scopeitem] = "db"
+
+Implementation plan for resources
+------------------------------------------
+
+1. Revert FuncargRequest to the old form, unmerge item/request
+   (done)
+2. make funcarg factories be discovered at collection time
+3. Introduce funcarg marker
+4. Introduce funcarg scope parameter
+5. Introduce funcarg parametrize parameter
+6. make setup functions be discovered at collection time
+7. (Introduce a pytest_fixture_protocol/setup_funcargs hook)
+
+methods and data structures
+--------------------------------
+
+A FuncarcManager holds all information about funcarg definitions
+including parametrization and scope definitions.  It implements
+a pytest_generate_tests hook which performs parametrization as appropriate.
+
+as a simple example, let's consider a tree where a test function requires
+a "abc" funcarg and its factory defines it as parametrized and scoped
+for Modules.  When collections hits the function item, it creates
+the metafunc object, and calls funcargdb.pytest_generate_tests(metafunc)
+which looks up available funcarg factories and their scope and parametrization.
+This information is equivalent to what can be provided today directly
+at the function site and it should thus be relatively straight forward
+to implement the additional way of defining parametrization/scoping.
+
+conftest loading:
+    each funcarg-factory will populate the session.funcargmanager
+
+When a test item is collected, it grows a dictionary 
+(funcargname2factorycalllist).  A factory lookup is performed 
+for each required funcarg.  The resulting factory call is stored 
+with the item.  If a function is parametrized multiple items are 
+created with respective factory calls. Else if a factory is parametrized
+multiple items and calls to the factory function are created as well.
+
+At setup time, an item populates a funcargs mapping, mapping names
+to values.  If a value is funcarg factories are queried for a given item
+test functions and setup functions are put in a class
+which looks up required funcarg factories.
+
+

_pytest/junitxml.py

@@ -57,7 +57,7 @@ def bin_xml_escape(arg):
             return unicode('#x%02X') % i
         else:
             return unicode('#x%04X') % i
-    return illegal_xml_re.sub(repl, py.xml.escape(arg))
+    return py.xml.raw(illegal_xml_re.sub(repl, py.xml.escape(arg)))
 
 def pytest_addoption(parser):
     group = parser.getgroup("terminal reporting")
@@ -89,7 +89,7 @@ def mangle_testnames(names):
 class LogXML(object):
     def __init__(self, logfile, prefix):
         logfile = os.path.expanduser(os.path.expandvars(logfile))
-        self.logfile = os.path.normpath(logfile)
+        self.logfile = os.path.normpath(os.path.abspath(logfile))
         self.prefix = prefix
         self.tests = []
         self.passed = self.skipped = 0
@@ -114,7 +114,7 @@ class LogXML(object):
 
     def append_failure(self, report):
         #msg = str(report.longrepr.reprtraceback.extraline)
-        if "xfail" in report.keywords:
+        if hasattr(report, "wasxfail"):
             self.append(
                 Junit.skipped(message="xfail-marked test passes unexpectedly"))
             self.skipped += 1
@@ -148,8 +148,8 @@ class LogXML(object):
         self.errors += 1
 
     def append_skipped(self, report):
-        if "xfail" in report.keywords:
-            self.append(Junit.skipped(str(report.keywords['xfail']),
+        if hasattr(report, "wasxfail"):
+            self.append(Junit.skipped(str(report.wasxfail),
                                       message="expected test failure"))
         else:
             filename, lineno, skipreason = report.longrepr

_pytest/main.py

@@ -2,7 +2,15 @@
 
 import py
 import pytest, _pytest
+import inspect
 import os, sys, imp
+try:
+    from collections import MutableMapping as MappingMixin
+except ImportError:
+    from UserDict import DictMixin as MappingMixin
+
+from _pytest.mark import MarkInfo
+
 tracebackcutdir = py.path.local(_pytest.__file__).dirpath()
 
 # exitcodes for the command line
@@ -29,7 +37,6 @@ def pytest_addoption(parser):
     group._addoption('--maxfail', metavar="num",
                action="store", type="int", dest="maxfail", default=0,
                help="exit after first num failures or errors.")
-
     group._addoption('--strict', action="store_true",
                help="run pytest in strict mode, warnings become errors.")
 
@@ -111,11 +118,18 @@ def pytest_collection(session):
 def pytest_runtestloop(session):
     if session.config.option.collectonly:
         return True
-    for i, item in enumerate(session.items):
+
+    def getnextitem(i):
+        # this is a function to avoid python2
+        # keeping sys.exc_info set when calling into a test
+        # python2 keeps sys.exc_info till the frame is left
         try:
-            nextitem = session.items[i+1]
+            return session.items[i+1]
         except IndexError:
-            nextitem = None
+            return None
+
+    for i, item in enumerate(session.items):
+        nextitem = getnextitem(i)
         item.config.hook.pytest_runtest_protocol(item=item, nextitem=nextitem)
         if session.shouldstop:
             raise session.Interrupted(session.shouldstop)
@@ -134,8 +148,10 @@ class HookProxy:
     def __init__(self, fspath, config):
         self.fspath = fspath
         self.config = config
+
     def __getattr__(self, name):
         hookmethod = getattr(self.config.hook, name)
+
         def call_matching_hooks(**kwargs):
             plugins = self.config._getmatchingplugins(self.fspath)
             return hookmethod.pcall(plugins, **kwargs)
@@ -143,31 +159,71 @@ class HookProxy:
 
 def compatproperty(name):
     def fget(self):
+        # deprecated - use pytest.name
         return getattr(pytest, name)
-    return property(fget, None, None,
-        "deprecated attribute %r, use pytest.%s" % (name,name))
+
+    return property(fget)
+
+class NodeKeywords(MappingMixin):
+    def __init__(self, node):
+        parent = node.parent
+        bases = parent and (parent.keywords._markers,) or ()
+        self._markers = type("dynmarker", bases, {node.name: True})
+
+    def __getitem__(self, key):
+        try:
+            return getattr(self._markers, key)
+        except AttributeError:
+            raise KeyError(key)
+
+    def __setitem__(self, key, value):
+        setattr(self._markers, key, value)
+
+    def __delitem__(self, key):
+        delattr(self._markers, key)
+
+    def __iter__(self):
+        return iter(self.keys())
+
+    def __len__(self):
+        return len(self.keys())
+
+    def keys(self):
+        return dir(self._markers)
 
 class Node(object):
-    """ base class for all Nodes in the collection tree.
+    """ base class for Collector and Item the test collection tree.
     Collector subclasses have children, Items are terminal nodes."""
 
     def __init__(self, name, parent=None, config=None, session=None):
-        #: a unique name with the scope of the parent
+        #: a unique name within the scope of the parent node
         self.name = name
 
         #: the parent collector node.
         self.parent = parent
 
-        #: the test config object
+        #: the pytest config object
         self.config = config or parent.config
 
-        #: the collection this node is part of
+        #: the session this node is part of
         self.session = session or parent.session
 
-        #: filesystem path where this node was collected from
+        #: filesystem path where this node was collected from (can be None)
         self.fspath = getattr(parent, 'fspath', None)
-        self.ihook = self.session.gethookproxy(self.fspath)
-        self.keywords = {self.name: True}
+
+        #: keywords/markers collected from all scopes
+        self.keywords = NodeKeywords(self)
+
+        #self.extrainit()
+
+    @property
+    def ihook(self):
+        """ fspath sensitive hook proxy used to call pytest hooks"""
+        return self.session.gethookproxy(self.fspath)
+
+    #def extrainit(self):
+    #    """"extra initialization after Node is initialized.  Implemented
+    #    by some subclasses. """
 
     Module = compatproperty("Module")
     Class = compatproperty("Class")
@@ -185,25 +241,28 @@ class Node(object):
         return cls
 
     def __repr__(self):
-        return "<%s %r>" %(self.__class__.__name__, getattr(self, 'name', None))
+        return "<%s %r>" %(self.__class__.__name__,
+                           getattr(self, 'name', None))
 
     # methods for ordering nodes
     @property
     def nodeid(self):
+        """ a ::-separated string denoting its collection tree address. """
         try:
             return self._nodeid
         except AttributeError:
             self._nodeid = x = self._makeid()
             return x
 
+
     def _makeid(self):
         return self.parent.nodeid + "::" + self.name
 
     def __eq__(self, other):
         if not isinstance(other, Node):
             return False
-        return self.__class__ == other.__class__ and \
-               self.name == other.name and self.parent == other.parent
+        return (self.__class__ == other.__class__ and
+                self.name == other.name and self.parent == other.parent)
 
     def __ne__(self, other):
         return not self == other
@@ -262,6 +321,9 @@ class Node(object):
         pass
 
     def _repr_failure_py(self, excinfo, style=None):
+        fm = self.session._fixturemanager
+        if excinfo.errisinstance(fm.FixtureLookupError):
+            return excinfo.value.formatrepr()
         if self.config.option.fulltrace:
             style="long"
         else:
@@ -370,9 +432,9 @@ class Session(FSCollector):
         __module__ = 'builtins' # for py3
 
     def __init__(self, config):
-        super(Session, self).__init__(py.path.local(), parent=None,
-            config=config, session=self)
-        assert self.config.pluginmanager.register(self, name="session", prepend=True)
+        FSCollector.__init__(self, py.path.local(), parent=None,
+                             config=config, session=self)
+        self.config.pluginmanager.register(self, name="session", prepend=True)
         self._testsfailed = 0
         self.shouldstop = False
         self.trace = config.trace.root.get("collection")
@@ -383,7 +445,7 @@ class Session(FSCollector):
             raise self.Interrupted(self.shouldstop)
 
     def pytest_runtest_logreport(self, report):
-        if report.failed and 'xfail' not in getattr(report, 'keywords', []):
+        if report.failed and not hasattr(report, 'wasxfail'):
             self._testsfailed += 1
             maxfail = self.config.getvalue("maxfail")
             if maxfail and self._testsfailed >= maxfail:
@@ -458,7 +520,7 @@ class Session(FSCollector):
         if path.check(dir=1):
             assert not names, "invalid arg %r" %(arg,)
             for path in path.visit(fil=lambda x: x.check(file=1),
-                rec=self._recurse, bf=True, sort=True):
+                                   rec=self._recurse, bf=True, sort=True):
                 for x in self._collectfile(path):
                     yield x
         else:
@@ -470,13 +532,13 @@ class Session(FSCollector):
         ihook = self.gethookproxy(path)
         if not self.isinitpath(path):
             if ihook.pytest_ignore_collect(path=path, config=self.config):
-               return ()
+                return ()
         return ihook.pytest_collect_file(path=path, parent=self)
 
     def _recurse(self, path):
         ihook = self.gethookproxy(path.dirpath())
         if ihook.pytest_ignore_collect(path=path, config=self.config):
-           return
+            return
         for pat in self._norecursepatterns:
             if path.check(fnmatch=pat):
                 return False
@@ -579,3 +641,12 @@ class Session(FSCollector):
                     for x in self.genitems(subnode):
                         yield x
             node.ihook.pytest_collectreport(report=rep)
+
+def getfslineno(obj):
+    # xxx let decorators etc specify a sane ordering
+    if hasattr(obj, 'place_as'):
+        obj = obj.place_as
+    fslineno = py.code.getfslineno(obj)
+    assert isinstance(fslineno[1], int), obj
+    return fslineno
+

_pytest/mark.py

@@ -86,7 +86,7 @@ def skipbykeyword(colitem, keywordexpr):
     if not keywordexpr:
         return
 
-    itemkeywords = getkeywords(colitem)
+    itemkeywords = colitem.keywords
     for key in filter(None, keywordexpr.split()):
         eor = key[:1] == '-'
         if eor:
@@ -94,14 +94,6 @@ def skipbykeyword(colitem, keywordexpr):
         if not (eor ^ matchonekeyword(key, itemkeywords)):
             return True
 
-def getkeywords(node):
-    keywords = {}
-    while node is not None:
-        keywords.update(node.keywords)
-        node = node.parent
-    return keywords
-
-
 def matchonekeyword(key, itemkeywords):
     for elem in key.split("."):
         for kw in itemkeywords:

_pytest/monkeypatch.py

@@ -1,6 +1,6 @@
 """ monkeypatching and mocking functionality.  """
 
-import os, sys
+import os, sys, inspect
 
 def pytest_funcarg__monkeypatch(request):
     """The returned ``monkeypatch`` funcarg provides these
@@ -39,6 +39,10 @@ class monkeypatch:
         oldval = getattr(obj, name, notset)
         if raising and oldval is notset:
             raise AttributeError("%r has no attribute %r" %(obj, name))
+
+        # avoid class descriptors like staticmethod/classmethod
+        if inspect.isclass(obj):
+            oldval = obj.__dict__.get(name, notset)
         self._setattr.insert(0, (obj, name, oldval))
         setattr(obj, name, value)
 

_pytest/nose.py

@@ -41,7 +41,7 @@ def pytest_make_collect_report(collector):
 
 def call_optional(obj, name):
     method = getattr(obj, name, None)
-    if method:
+    if method is not None and not hasattr(method, "_pytestfixturefunction") and py.builtin.callable(method):
         # If there's any problems allow the exception to raise rather than
         # silently ignoring them
         method()

_pytest/pdb.py

@@ -50,7 +50,7 @@ def pytest_make_collect_report(__multicall__, collector):
 
 def pytest_runtest_makereport():
     pytestPDB.item = None
-    
+
 class PdbInvoke:
     @pytest.mark.tryfirst
     def pytest_runtest_makereport(self, item, call, __multicall__):
@@ -59,7 +59,7 @@ class PdbInvoke:
             call.excinfo.errisinstance(pytest.skip.Exception) or \
             call.excinfo.errisinstance(py.std.bdb.BdbQuit):
             return rep
-        if "xfail" in rep.keywords:
+        if hasattr(rep, "wasxfail"):
             return rep
         # we assume that the above execute() suspended capturing
         # XXX we re-use the TerminalReporter's terminalwriter

_pytest/pytester.py

@@ -2,6 +2,7 @@
 
 import py, pytest
 import sys, os
+import codecs
 import re
 import inspect
 import time
@@ -244,8 +245,10 @@ class TmpTestdir:
         ret = None
         for name, value in items:
             p = self.tmpdir.join(name).new(ext=ext)
-            source = py.builtin._totext(py.code.Source(value)).lstrip()
-            p.write(source.encode("utf-8"), "wb")
+            source = py.builtin._totext(py.code.Source(value)).strip()
+            content = source.encode("utf-8") # + "\n"
+            #content = content.rstrip() + "\n"
+            p.write(content, "wb")
             if ret is None:
                 ret = p
         return ret
@@ -318,7 +321,7 @@ class TmpTestdir:
         # used from runner functional tests
         item = self.getitem(source)
         # the test class where we are called from wants to provide the runner
-        testclassinstance = py.builtin._getimself(self.request.function)
+        testclassinstance = self.request.instance
         runner = testclassinstance.getrunner()
         return runner(item)
 
@@ -355,7 +358,7 @@ class TmpTestdir:
         if not plugins:
             plugins = []
         plugins.append(Collect())
-        ret = self.pytestmain(list(args), plugins=[Collect()])
+        ret = self.pytestmain(list(args), plugins=plugins)
         reprec = rec[0]
         reprec.ret = ret
         assert len(rec) == 1
@@ -388,10 +391,12 @@ class TmpTestdir:
         return config
 
     def getitem(self,  source, funcname="test_func"):
-        for item in self.getitems(source):
+        items = self.getitems(source)
+        for item in items:
             if item.name == funcname:
                 return item
-        assert 0, "%r item not found in module:\n%s" %(funcname, source)
+        assert 0, "%r item not found in module:\n%s\nitems: %s" %(
+                  funcname, source, items)
 
     def getitems(self,  source):
         modcol = self.getmodulecol(source)
@@ -438,28 +443,35 @@ class TmpTestdir:
         p1 = self.tmpdir.join("stdout")
         p2 = self.tmpdir.join("stderr")
         print_("running", cmdargs, "curdir=", py.path.local())
-        f1 = p1.open("wb")
-        f2 = p2.open("wb")
-        now = time.time()
-        popen = self.popen(cmdargs, stdout=f1, stderr=f2,
-            close_fds=(sys.platform != "win32"))
-        ret = popen.wait()
-        f1.close()
-        f2.close()
-        out = p1.read("rb")
-        out = getdecoded(out).splitlines()
-        err = p2.read("rb")
-        err = getdecoded(err).splitlines()
-        def dump_lines(lines, fp):
-            try:
-                for line in lines:
-                    py.builtin.print_(line, file=fp)
-            except UnicodeEncodeError:
-                print("couldn't print to %s because of encoding" % (fp,))
-        dump_lines(out, sys.stdout)
-        dump_lines(err, sys.stderr)
+        f1 = codecs.open(str(p1), "w", encoding="utf8")
+        f2 = codecs.open(str(p2), "w", encoding="utf8")
+        try:
+            now = time.time()
+            popen = self.popen(cmdargs, stdout=f1, stderr=f2,
+                close_fds=(sys.platform != "win32"))
+            ret = popen.wait()
+        finally:
+            f1.close()
+            f2.close()
+        f1 = codecs.open(str(p1), "r", encoding="utf8")
+        f2 = codecs.open(str(p2), "r", encoding="utf8")
+        try:
+            out = f1.read().splitlines()
+            err = f2.read().splitlines()
+        finally:
+            f1.close()
+            f2.close()
+        self._dump_lines(out, sys.stdout)
+        self._dump_lines(err, sys.stderr)
         return RunResult(ret, out, err, time.time()-now)
 
+    def _dump_lines(self, lines, fp):
+        try:
+            for line in lines:
+                py.builtin.print_(line, file=fp)
+        except UnicodeEncodeError:
+            print("couldn't print to %s because of encoding" % (fp,))
+
     def runpybin(self, scriptname, *args):
         fullargs = self._getpybinargs(scriptname) + args
         return self.run(*fullargs)
@@ -520,6 +532,8 @@ class TmpTestdir:
             pytest.skip("pypy-64 bit not supported")
         if sys.platform == "darwin":
             pytest.xfail("pexpect does not work reliably on darwin?!")
+        if sys.platform.startswith("freebsd"):
+            pytest.xfail("pexpect does not work reliably on freebsd")
         logfile = self.tmpdir.join("spawn.out")
         child = pexpect.spawn(cmd, logfile=logfile.open("w"))
         child.timeout = expect_timeout

_pytest/resultlog.py

@@ -1,4 +1,6 @@
-""" (disabled by default) create result information in a plain text file. """
+""" log machine-parseable test session result information in a plain
+text file.
+"""
 
 import py
 

_pytest/runner.py

@@ -1,6 +1,7 @@
 """ basic collect and runtest protocol implementations """
 
-import py, sys, time
+import py, sys
+from time import time
 from py._code.code import TerminalRepr
 
 def pytest_namespace():
@@ -114,7 +115,7 @@ class CallInfo:
         #: context of invocation: one of "setup", "call",
         #: "teardown", "memocollect"
         self.when = when
-        self.start = time.time()
+        self.start = time()
         try:
             try:
                 self.result = func()
@@ -123,7 +124,7 @@ class CallInfo:
             except:
                 self.excinfo = py.code.ExceptionInfo()
         finally:
-            self.stop = time.time()
+            self.stop = time()
 
     def __repr__(self):
         if self.excinfo:
@@ -154,7 +155,10 @@ class BaseReport(object):
         if hasattr(longrepr, 'toterminal'):
             longrepr.toterminal(out)
         else:
-            out.line(str(longrepr))
+            try:
+                out.line(longrepr)
+            except UnicodeEncodeError:
+                out.line("<unprintable longrepr>")
 
     passed = property(lambda x: x.outcome == "passed")
     failed = property(lambda x: x.outcome == "failed")
@@ -279,7 +283,7 @@ class CollectErrorRepr(TerminalRepr):
     def __init__(self, msg):
         self.longrepr = msg
     def toterminal(self, out):
-        out.line(str(self.longrepr), red=True)
+        out.line(self.longrepr, red=True)
 
 class SetupState(object):
     """ shared state for setting up/tearing down test items or collectors. """
@@ -291,6 +295,8 @@ class SetupState(object):
         """ attach a finalizer to the given colitem.
         if colitem is None, this will add a finalizer that
         is called at the end of teardown_all().
+        if colitem is a tuple, it will be used as a key
+        and needs an explicit call to _callfinalizers(key) later on.
         """
         assert hasattr(finalizer, '__call__')
         #assert colitem in self.stack
@@ -308,15 +314,17 @@ class SetupState(object):
 
     def _teardown_with_finalization(self, colitem):
         self._callfinalizers(colitem)
-        if colitem:
+        if hasattr(colitem, "teardown"):
             colitem.teardown()
         for colitem in self._finalizers:
-            assert colitem is None or colitem in self.stack
+            assert colitem is None or colitem in self.stack \
+             or isinstance(colitem, tuple)
 
     def teardown_all(self):
         while self.stack:
             self._pop_and_teardown()
-        self._teardown_with_finalization(None)
+        for key in list(self._finalizers):
+            self._teardown_with_finalization(key)
         assert not self._finalizers
 
     def teardown_exact(self, item, nextitem):
@@ -401,7 +409,9 @@ skip.Exception = Skipped
 
 def fail(msg="", pytrace=True):
     """ explicitely fail an currently-executing test with the given Message.
-    if @pytrace is not True the msg represents the full failure information.
+
+    :arg pytrace: if false the msg represents the full failure information
+                  and no python traceback will be reported.
     """
     __tracebackhide__ = True
     raise Failed(msg=msg, pytrace=pytrace)

_pytest/skipping.py

@@ -11,17 +11,18 @@ def pytest_addoption(parser):
 
 def pytest_configure(config):
     config.addinivalue_line("markers",
-        "skipif(*conditions): skip the given test function if evaluation "
-        "of all conditions has a True value.  Evaluation happens within the "
+        "skipif(condition): skip the given test function if eval(condition) "
+        "results in a True value.  Evaluation happens within the "
         "module global context. Example: skipif('sys.platform == \"win32\"') "
-        "skips the test if we are on the win32 platform. "
+        "skips the test if we are on the win32 platform. see "
+        "http://pytest.org/latest/skipping.html"
     )
     config.addinivalue_line("markers",
-        "xfail(*conditions, reason=None, run=True): mark the the test function "
-        "as an expected failure. Optionally specify a reason and run=False "
-        "if you don't even want to execute the test function. Any positional "
-        "condition strings will be evaluated (like with skipif) and if one is "
-        "False the marker will not be applied."
+        "xfail(condition, reason=None, run=True): mark the the test function "
+        "as an expected failure if eval(condition) has a True value. "
+        "Optionally specify a reason for better reporting and run=False if "
+        "you don't even want to execute the test function. See "
+        "http://pytest.org/latest/skipping.html"
     )
 
 def pytest_namespace():
@@ -110,6 +111,7 @@ class MarkEvaluator:
         return expl
 
 
+@pytest.mark.tryfirst
 def pytest_runtest_setup(item):
     if not isinstance(item, pytest.Function):
         return
@@ -137,7 +139,7 @@ def pytest_runtest_makereport(__multicall__, item, call):
         rep = __multicall__.execute()
         if rep.when == "call":
             # we need to translate into how py.test encodes xpass
-            rep.keywords['xfail'] = "reason: " + repr(item._unexpectedsuccess)
+            rep.wasxfail = "reason: " + repr(item._unexpectedsuccess)
             rep.outcome = "failed"
         return rep
     if not (call.excinfo and
@@ -148,27 +150,27 @@ def pytest_runtest_makereport(__multicall__, item, call):
     if call.excinfo and call.excinfo.errisinstance(py.test.xfail.Exception):
         if not item.config.getvalue("runxfail"):
             rep = __multicall__.execute()
-            rep.keywords['xfail'] = "reason: " + call.excinfo.value.msg
+            rep.wasxfail = "reason: " + call.excinfo.value.msg
             rep.outcome = "skipped"
             return rep
     rep = __multicall__.execute()
     evalxfail = item._evalxfail
-    if not item.config.option.runxfail:
-        if evalxfail.wasvalid() and evalxfail.istrue():
-            if call.excinfo:
-                rep.outcome = "skipped"
-                rep.keywords['xfail'] = evalxfail.getexplanation()
-            elif call.when == "call":
-                rep.outcome = "failed"
-                rep.keywords['xfail'] = evalxfail.getexplanation()
-            return rep
-    if 'xfail' in rep.keywords:
-        del rep.keywords['xfail']
+    if not rep.skipped:
+        if not item.config.option.runxfail:
+            if evalxfail.wasvalid() and evalxfail.istrue():
+                if call.excinfo:
+                    rep.outcome = "skipped"
+                elif call.when == "call":
+                    rep.outcome = "failed"
+                else:
+                    return rep
+                rep.wasxfail = evalxfail.getexplanation()
+                return rep
     return rep
 
 # called by terminalreporter progress reporting
 def pytest_report_teststatus(report):
-    if 'xfail' in report.keywords:
+    if hasattr(report, "wasxfail"):
         if report.skipped:
             return "xfailed", "x", "xfail"
         elif report.failed:
@@ -215,7 +217,7 @@ def show_xfailed(terminalreporter, lines):
     if xfailed:
         for rep in xfailed:
             pos = rep.nodeid
-            reason = rep.keywords['xfail']
+            reason = rep.wasxfail
             lines.append("XFAIL %s" % (pos,))
             if reason:
                 lines.append("  " + str(reason))
@@ -225,7 +227,7 @@ def show_xpassed(terminalreporter, lines):
     if xpassed:
         for rep in xpassed:
             pos = rep.nodeid
-            reason = rep.keywords['xfail']
+            reason = rep.wasxfail
             lines.append("XPASS %s %s" %(pos, reason))
 
 def cached_eval(config, expr, d):

_pytest/terminal.py

@@ -2,7 +2,8 @@
 
 This is a good source for looking at the various reporting hooks.
 """
-import pytest, py
+import pytest
+import py
 import sys
 import os
 
@@ -11,7 +12,7 @@ def pytest_addoption(parser):
     group._addoption('-v', '--verbose', action="count",
                dest="verbose", default=0, help="increase verbosity."),
     group._addoption('-q', '--quiet', action="count",
-               dest="quiet", default=0, help="decreate verbosity."),
+               dest="quiet", default=0, help="decrease verbosity."),
     group._addoption('-r',
          action="store", dest="reportchars", default=None, metavar="chars",
          help="show extra test summary info as specified by chars (f)ailed, "
@@ -37,13 +38,14 @@ def pytest_configure(config):
     stdout = py.std.sys.stdout
     if hasattr(os, 'dup') and hasattr(stdout, 'fileno'):
         try:
-            newfd = os.dup(stdout.fileno())
-            #print "got newfd", newfd
+            newstdout = py.io.dupfile(stdout, buffering=1,
+                                      encoding=stdout.encoding)
         except ValueError:
             pass
         else:
-            stdout = os.fdopen(newfd, stdout.mode, 1)
-            config._cleanup.append(lambda: stdout.close())
+            config._cleanup.append(lambda: newstdout.close())
+            assert stdout.encoding  == newstdout.encoding
+            stdout = newstdout
 
     reporter = TerminalReporter(config, stdout)
     config.pluginmanager.register(reporter, 'terminalreporter')
@@ -94,7 +96,7 @@ class TerminalReporter:
         self._numcollected = 0
 
         self.stats = {}
-        self.curdir = py.path.local()
+        self.startdir = self.curdir = py.path.local()
         if file is None:
             file = py.std.sys.stdout
         self._tw = py.io.TerminalWriter(file)
@@ -109,9 +111,9 @@ class TerminalReporter:
     def write_fspath_result(self, fspath, res):
         if fspath != self.currentfspath:
             self.currentfspath = fspath
-            #fspath = self.curdir.bestrelpath(fspath)
+            #fspath = self.startdir.bestrelpath(fspath)
             self._tw.line()
-            #relpath = self.curdir.bestrelpath(fspath)
+            #relpath = self.startdir.bestrelpath(fspath)
             self._tw.write(fspath + " ")
         self._tw.write(res)
 
@@ -207,7 +209,7 @@ class TerminalReporter:
                 self.currentfspath = -2
 
     def pytest_collection(self):
-        if not self.hasmarkup:
+        if not self.hasmarkup and self.config.option.verbose >=1:
             self.write("collecting ... ", bold=True)
 
     def pytest_collectreport(self, report):
@@ -222,6 +224,9 @@ class TerminalReporter:
             self.report_collect()
 
     def report_collect(self, final=False):
+        if self.config.option.verbose < 0:
+            return
+
         errors = len(self.stats.get('error', []))
         skipped = len(self.stats.get('skipped', []))
         if final:
@@ -243,6 +248,7 @@ class TerminalReporter:
     def pytest_collection_modifyitems(self):
         self.report_collect(True)
 
+    @pytest.mark.trylast
     def pytest_sessionstart(self, session):
         self._sessionstarttime = py.std.time.time()
         if not self.showheader:
@@ -258,11 +264,23 @@ class TerminalReporter:
            getattr(self.config.option, 'pastebin', None):
             msg += " -- " + str(sys.executable)
         self.write_line(msg)
-        lines = self.config.hook.pytest_report_header(config=self.config)
+        lines = self.config.hook.pytest_report_header(
+            config=self.config, startdir=self.startdir)
         lines.reverse()
         for line in flatten(lines):
             self.write_line(line)
 
+    def pytest_report_header(self, config):
+        plugininfo = config.pluginmanager._plugin_distinfo
+        if plugininfo:
+            l = []
+            for dist, plugin in plugininfo:
+                name = dist.project_name
+                if name.startswith("pytest-"):
+                    name = name[7:]
+                l.append(name)
+            return "plugins: %s" % ", ".join(l)
+
     def pytest_collection_finish(self, session):
         if self.config.option.collectonly:
             self._printcollecteditems(session.items)
@@ -425,7 +443,7 @@ class TerminalReporter:
     def summary_stats(self):
         session_duration = py.std.time.time() - self._sessionstarttime
 
-        keys = "failed passed skipped deselected".split()
+        keys = "failed passed skipped deselected xfailed xpassed".split()
         for key in self.stats.keys():
             if key not in keys:
                 keys.append(key)
@@ -440,8 +458,8 @@ class TerminalReporter:
         msg = "%s in %.2f seconds" %(line, session_duration)
         if self.verbosity >= 0:
             self.write_sep("=", msg, bold=True)
-        else:
-            self.write_line(msg, bold=True)
+        #else:
+        #    self.write_line(msg, bold=True)
 
     def summary_deselected(self):
         if 'deselected' in self.stats:
@@ -452,8 +470,9 @@ class TerminalReporter:
             m = self.config.option.markexpr
             if m:
                 l.append("-m %r" % m)
-            self.write_sep("=", "%d tests deselected by %r" %(
-                len(self.stats['deselected']), " ".join(l)), bold=True)
+            if l:
+                self.write_sep("=", "%d tests deselected by %r" %(
+                    len(self.stats['deselected']), " ".join(l)), bold=True)
 
 def repr_pythonversion(v=None):
     if v is None:

_pytest/tmpdir.py

@@ -40,7 +40,7 @@ class TempdirHandler:
                 basetemp.mkdir()
             else:
                 basetemp = py.path.local.make_numbered_dir(prefix='pytest-')
-            self._basetemp = t = basetemp
+            self._basetemp = t = basetemp.realpath()
             self.trace("new basetemp", t)
             return t
 

_pytest/unittest.py

@@ -20,10 +20,15 @@ def pytest_pycollect_makeitem(collector, name, obj):
             return UnitTestCase(name, parent=collector)
 
 class UnitTestCase(pytest.Class):
+    nofuncargs = True  # marker for fixturemanger.getfixtureinfo()
+                       # to declare that our children do not support funcargs
+
     def collect(self):
+        self.session._fixturemanager.parsefactories(self, unittest=True)
         loader = py.std.unittest.TestLoader()
         module = self.getparent(pytest.Module).obj
         cls = self.obj
+        foundsomething = False
         for name in loader.getTestCaseNames(self.obj):
             x = getattr(self.obj, name)
             funcobj = getattr(x, 'im_func', x)
@@ -31,14 +36,26 @@ class UnitTestCase(pytest.Class):
             if hasattr(funcobj, 'todo'):
                 pytest.mark.xfail(reason=str(funcobj.todo))(funcobj)
             yield TestCaseFunction(name, parent=self)
+            foundsomething = True
+
+        if not foundsomething:
+            runtest = getattr(self.obj, 'runTest', None)
+            if runtest is not None:
+                ut = sys.modules.get("twisted.trial.unittest", None)
+                if ut is None or runtest != ut.TestCase.runTest:
+                    yield TestCaseFunction('runTest', parent=self)
 
     def setup(self):
+        if getattr(self.obj, '__unittest_skip__', False):
+            return
         meth = getattr(self.obj, 'setUpClass', None)
         if meth is not None:
             meth()
         super(UnitTestCase, self).setup()
 
     def teardown(self):
+        if getattr(self.obj, '__unittest_skip__', False):
+            return
         meth = getattr(self.obj, 'tearDownClass', None)
         if meth is not None:
             meth()
@@ -56,6 +73,8 @@ class TestCaseFunction(pytest.Function):
             pytest.skip(self._obj.skip)
         if hasattr(self._testcase, 'setup_method'):
             self._testcase.setup_method(self._obj)
+        if hasattr(self, "_request"):
+            self._request._fillfixtures()
 
     def teardown(self):
         if hasattr(self._testcase, 'teardown_method'):

doc/en/Makefile

@@ -0,0 +1,144 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+SITETARGET=latest
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+regen:
+	PYTHONDONTWRITEBYTECODE=1 COLUMNS=76 regendoc --update *.txt */*.txt
+    
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+install: html
+	 rsync -avz _build/html/ pytest.org:/www/pytest.org/$(SITETARGET)
+
+installpdf: latexpdf
+	@scp $(BUILDDIR)/latex/pytest.pdf pytest.org:/www/pytest.org/$(SITETARGET)
+
+installall: clean install installpdf
+	@echo "done"
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pytest.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pytest.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/pytest"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pytest"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

doc/en/announce/index.txt

@@ -5,6 +5,11 @@ Release announcements
 .. toctree::
    :maxdepth: 2
 
+   release-2.3.3
+   release-2.3.2
+   release-2.3.1
+   release-2.3.0
+   release-2.2.4
    release-2.2.2
    release-2.2.1
    release-2.2.0

doc/en/announce/release-2.0.1.txt

@@ -0,0 +1,67 @@
+py.test 2.0.1: bug fixes
+===========================================================================
+
+Welcome to pytest-2.0.1, a maintenance and bug fix release of pytest,
+a mature testing tool for Python, supporting CPython 2.4-3.2, Jython
+and latest PyPy interpreters.  See extensive docs with tested examples here:
+
+    http://pytest.org/
+
+If you want to install or upgrade pytest, just type one of::
+
+    pip install -U pytest # or
+    easy_install -U pytest
+
+Many thanks to all issue reporters and people asking questions or
+complaining.  Particular thanks to Floris Bruynooghe and Ronny Pfannschmidt
+for their great coding contributions and many others for feedback and help.
+
+best,
+holger krekel
+
+Changes between 2.0.0 and 2.0.1
+----------------------------------------------
+
+- refine and unify initial capturing so that it works nicely
+  even if the logging module is used on an early-loaded conftest.py
+  file or plugin.
+- fix issue12 - show plugin versions with "--version" and
+  "--traceconfig" and also document how to add extra information
+  to reporting test header
+- fix issue17 (import-* reporting issue on python3) by
+  requiring py>1.4.0 (1.4.1 is going to include it)
+- fix issue10 (numpy arrays truth checking) by refining
+  assertion interpretation in py lib
+- fix issue15: make nose compatibility tests compatible
+  with python3 (now that nose-1.0 supports python3)
+- remove somewhat surprising "same-conftest" detection because
+  it ignores conftest.py when they appear in several subdirs.
+- improve assertions ("not in"), thanks Floris Bruynooghe
+- improve behaviour/warnings when running on top of "python -OO"
+  (assertions and docstrings are turned off, leading to potential
+  false positives)
+- introduce a pytest_cmdline_processargs(args) hook
+  to allow dynamic computation of command line arguments.
+  This fixes a regression because py.test prior to 2.0
+  allowed to set command line options from conftest.py
+  files which so far pytest-2.0 only allowed from ini-files now.
+- fix issue7: assert failures in doctest modules.
+  unexpected failures in doctests will not generally
+  show nicer, i.e. within the doctest failing context.
+- fix issue9: setup/teardown functions for an xfail-marked
+  test will report as xfail if they fail but report as normally
+  passing (not xpassing) if they succeed.  This only is true
+  for "direct" setup/teardown invocations because teardown_class/
+  teardown_module cannot closely relate to a single test.
+- fix issue14: no logging errors at process exit
+- refinements to "collecting" output on non-ttys
+- refine internal plugin registration and --traceconfig output
+- introduce a mechanism to prevent/unregister plugins from the
+  command line, see http://pytest.org/latest/plugins.html#cmdunregister
+- activate resultlog plugin by default
+- fix regression wrt yielded tests which due to the
+  collection-before-running semantics were not
+  setup as with pytest 1.3.4.  Note, however, that
+  the recommended and much cleaner way to do test
+  parametrization remains the "pytest_generate_tests"
+  mechanism, see the docs.

doc/en/announce/release-2.3.0.txt

@@ -0,0 +1,134 @@
+pytest-2.3: improved fixtures / better unittest integration
+=============================================================================
+
+pytest-2.3 comes with many major improvements for fixture/funcarg management 
+and parametrized testing in Python.  It is now easier, more efficient and
+more predicatable to re-run the same tests with different fixture
+instances.  Also, you can directly declare the caching "scope" of
+fixtures so that dependent tests throughout your whole test suite can
+re-use database or other expensive fixture objects with ease.  Lastly,
+it's possible for fixture functions (formerly known as funcarg
+factories) to use other fixtures, allowing for a completely modular and
+re-useable fixture design. 
+
+For detailed info and tutorial-style examples, see:
+
+    http://pytest.org/latest/fixture.html
+
+Moreover, there is now support for using pytest fixtures/funcargs with
+unittest-style suites, see here for examples:
+
+    http://pytest.org/latest/unittest.html
+
+Besides, more unittest-test suites are now expected to "simply work"
+with pytest.
+
+All changes are backward compatible and you should be able to continue
+to run your test suites and 3rd party plugins that worked with
+pytest-2.2.4.
+
+If you are interested in the precise reasoning (including examples) of the 
+pytest-2.3 fixture evolution, please consult
+http://pytest.org/latest/funcarg_compare.html
+
+For general info on installation and getting started:
+
+    http://pytest.org/latest/getting-started.html
+
+Docs and PDF access as usual at:
+
+    http://pytest.org
+
+and more details for those already in the knowing of pytest can be found
+in the CHANGELOG below.
+
+Particular thanks for this release go to Floris Bruynooghe, Alex Okrushko
+Carl Meyer, Ronny Pfannschmidt, Benjamin Peterson and Alex Gaynor for helping 
+to get the new features right and well integrated.  Ronny and Floris
+also helped to fix a number of bugs and yet more people helped by
+providing bug reports.
+
+have fun,
+holger krekel
+
+
+Changes between 2.2.4 and 2.3.0
+-----------------------------------
+
+- fix issue202 - better automatic names for parametrized test functions
+- fix issue139 - introduce @pytest.fixture which allows direct scoping
+  and parametrization of funcarg factories.  Introduce new @pytest.setup
+  marker to allow the writing of setup functions which accept funcargs.
+- fix issue198 - conftest fixtures were not found on windows32 in some
+  circumstances with nested directory structures due to path manipulation issues
+- fix issue193 skip test functions with were parametrized with empty
+  parameter sets
+- fix python3.3 compat, mostly reporting bits that previously depended
+  on dict ordering
+- introduce re-ordering of tests by resource and parametrization setup
+  which takes precedence to the usual file-ordering
+- fix issue185 monkeypatching time.time does not cause pytest to fail
+- fix issue172 duplicate call of pytest.setup-decoratored setup_module
+  functions
+- fix junitxml=path construction so that if tests change the
+  current working directory and the path is a relative path
+  it is constructed correctly from the original current working dir.
+- fix "python setup.py test" example to cause a proper "errno" return
+- fix issue165 - fix broken doc links and mention stackoverflow for FAQ
+- catch unicode-issues when writing failure representations
+  to terminal to prevent the whole session from crashing
+- fix xfail/skip confusion: a skip-mark or an imperative pytest.skip
+  will now take precedence before xfail-markers because we
+  can't determine xfail/xpass status in case of a skip. see also:
+  http://stackoverflow.com/questions/11105828/in-py-test-when-i-explicitly-skip-a-test-that-is-marked-as-xfail-how-can-i-get
+
+- always report installed 3rd party plugins in the header of a test run
+
+- fix issue160: a failing setup of an xfail-marked tests should
+  be reported as xfail (not xpass)
+
+- fix issue128: show captured output when capsys/capfd are used
+
+- fix issue179: propperly show the dependency chain of factories
+
+- pluginmanager.register(...) now raises ValueError if the
+  plugin has been already registered or the name is taken
+
+- fix issue159: improve http://pytest.org/latest/faq.html 
+  especially with respect to the "magic" history, also mention
+  pytest-django, trial and unittest integration.
+
+- make request.keywords and node.keywords writable.  All descendant
+  collection nodes will see keyword values.  Keywords are dictionaries
+  containing markers and other info.
+
+- fix issue 178: xml binary escapes are now wrapped in py.xml.raw
+
+- fix issue 176: correctly catch the builtin AssertionError
+  even when we replaced AssertionError with a subclass on the
+  python level
+
+- factory discovery no longer fails with magic global callables
+  that provide no sane __code__ object (mock.call for example)
+
+- fix issue 182: testdir.inprocess_run now considers passed plugins
+
+- fix issue 188: ensure sys.exc_info is clear on python2
+                 before calling into a test
+
+- fix issue 191: add unittest TestCase runTest method support
+- fix issue 156: monkeypatch correctly handles class level descriptors
+
+- reporting refinements:
+
+  - pytest_report_header now receives a "startdir" so that
+    you can use startdir.bestrelpath(yourpath) to show
+    nice relative path
+
+  - allow plugins to implement both pytest_report_header and 
+    pytest_sessionstart (sessionstart is invoked first).
+
+  - don't show deselected reason line if there is none
+
+  - py.test -vv will show all of assert comparisations instead of truncating
+

doc/en/announce/release-2.3.1.txt

@@ -0,0 +1,39 @@
+pytest-2.3.1: fix regression with factory functions
+===========================================================================
+
+pytest-2.3.1 is a quick follow-up release:
+
+- fix issue202 - regression with fixture functions/funcarg factories:  
+  using "self" is now safe again and works as in 2.2.4.  Thanks 
+  to Eduard Schettino for the quick bug report.
+
+- disable pexpect pytest self tests on Freebsd - thanks Koob for the 
+  quick reporting
+
+- fix/improve interactive docs with --markers
+
+See 
+
+     http://pytest.org/
+
+for general information.  To install or upgrade pytest:
+
+    pip install -U pytest # or
+    easy_install -U pytest
+
+best,
+holger krekel
+
+
+Changes between 2.3.0 and 2.3.1
+-----------------------------------
+
+- fix issue202 - fix regression: using "self" from fixture functions now
+  works as expected (it's the same "self" instance that a test method
+  which uses the fixture sees)
+
+- skip pexpect using tests (test_pdb.py mostly) on freebsd* systems
+  due to pexpect not supporting it properly (hanging)
+
+- link to web pages from --markers output which provides help for
+  pytest.mark.* usage.

doc/en/announce/release-2.3.2.txt

@@ -0,0 +1,57 @@
+pytest-2.3.2: some fixes and more traceback-printing speed
+===========================================================================
+
+pytest-2.3.2 is a another stabilization release:
+
+- issue 205: fixes a regression with conftest detection
+- issue 208/29: fixes traceback-printing speed in some bad cases
+- fix teardown-ordering for parametrized setups
+- fix unittest and trial compat behaviour with respect  to runTest() methods
+- issue 206 and others: some improvements to packaging
+- fix issue127 and others: improve some docs 
+
+See 
+
+     http://pytest.org/
+
+for general information.  To install or upgrade pytest:
+
+    pip install -U pytest # or
+    easy_install -U pytest
+
+best,
+holger krekel
+
+
+Changes between 2.3.1 and 2.3.2
+-----------------------------------
+
+- fix issue208 and fix issue29 use new py version to avoid long pauses 
+  when printing tracebacks in long modules
+
+- fix issue205 - conftests in subdirs customizing
+  pytest_pycollect_makemodule and pytest_pycollect_makeitem
+  now work properly
+
+- fix teardown-ordering for parametrized setups
+
+- fix issue127 - better documentation for pytest_addoption
+  and related objects.
+
+- fix unittest behaviour: TestCase.runtest only called if there are
+  test methods defined
+
+- improve trial support: don't collect its empty
+  unittest.TestCase.runTest() method
+
+- "python setup.py test" now works with pytest itself
+
+- fix/improve internal/packaging related bits:
+
+  - exception message check of test_nose.py now passes on python33 as well
+
+  - issue206 - fix test_assertrewrite.py to work when a global
+    PYTHONDONTWRITEBYTECODE=1 is present
+
+  - add tox.ini to pytest distribution so that ignore-dirs and others config
+    bits are properly distributed for maintainers who run pytest-own tests

doc/en/apiref.txt

@@ -10,14 +10,15 @@ py.test reference documentation
    builtin.txt
    customize.txt
    assert.txt
-   funcargs.txt
+   fixture.txt
+   parametrize.txt
    xunit_setup.txt
    capture.txt
    monkeypatch.txt
    xdist.txt
    tmpdir.txt
-   skipping.txt
    mark.txt
+   skipping.txt
    recwarn.txt
    unittest.txt
    nose.txt

doc/en/assert.txt

@@ -2,7 +2,10 @@
 The writing and reporting of assertions in tests
 ==================================================
 
+.. _`assertfeedback`:
 .. _`assert with the assert statement`:
+.. _`assert`:
+
 
 Asserting with the ``assert`` statement
 ---------------------------------------------------------
@@ -23,8 +26,8 @@ you will see the return value of the function call::
 
     $ py.test test_assert1.py
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 1 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 1 items
     
     test_assert1.py F
     
@@ -37,7 +40,7 @@ you will see the return value of the function call::
     E        +  where 3 = f()
     
     test_assert1.py:5: AssertionError
-    ========================= 1 failed in 0.02 seconds =========================
+    ========================= 1 failed in 0.01 seconds =========================
 
 py.test has support for showing the values of the most common subexpressions
 including calls, attributes, comparisons, and binary and unary
@@ -54,6 +57,8 @@ will be simply shown in the traceback.
 
 See :ref:`assert-details` for more information on assertion introspection.
 
+.. _`assertraises`:
+
 Assertions about expected exceptions
 ------------------------------------------
 
@@ -105,8 +110,8 @@ if you run this module::
 
     $ py.test test_assert2.py
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 1 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 1 items
     
     test_assert2.py F
     
@@ -124,7 +129,7 @@ if you run this module::
     E         '5'
     
     test_assert2.py:5: AssertionError
-    ========================= 1 failed in 0.03 seconds =========================
+    ========================= 1 failed in 0.01 seconds =========================
 
 Special comparisons are done for a number of cases:
 
@@ -168,7 +173,6 @@ you can run the test module and get the custom output defined in
 the conftest file::
 
    $ py.test -q test_foocompare.py
-   collecting ... collected 1 items
    F
    ================================= FAILURES =================================
    _______________________________ test_compare _______________________________
@@ -181,7 +185,6 @@ the conftest file::
    E            vals: 1 != 2
    
    test_foocompare.py:8: AssertionError
-   1 failed in 0.02 seconds
 
 .. _assert-details:
 .. _`assert introspection`:

doc/en/attic_fixtures.txt

@@ -0,0 +1,186 @@
+
+**Test classes, modules or whole projects can make use of
+one or more fixtures**.  All required fixture functions will execute 
+before a test from the specifying context executes.  As You can use this
+to make tests operate from a pre-initialized directory or with
+certain environment variables or with pre-configured global application
+settings.
+
+For example, the Django_ project requires database 
+initialization to be able to import from and use its model objects.  
+For that, the `pytest-django`_ plugin provides fixtures which your 
+project can then easily depend or extend on, simply by referencing the
+name of the particular fixture. 
+
+Fixture functions have limited visilibity which depends on where they
+are defined.  If they are defined on a test class, only its test methods 
+may use it. A fixture defined in a module can only be used
+from that test module.  A fixture defined in a conftest.py file
+can only be used by the tests below the directory of that file.
+Lastly, plugins can define fixtures which are available across all
+projects.
+
+
+
+
+
+Python, Java and many other languages support a so called xUnit_ style 
+for providing a fixed state, `test fixtures`_, for running tests.  It
+typically involves calling a autouse function ahead and a teardown
+function after test execute.  In 2005 pytest introduced a scope-specific
+model of automatically detecting and calling autouse and teardown
+functions on a per-module, class or function basis.  The Python unittest
+package and nose have subsequently incorporated them.  This model
+remains supported by pytest as :ref:`classic xunit`.  
+
+One property of xunit fixture functions is that they work implicitely
+by preparing global state or setting attributes on TestCase objects.
+By contrast, pytest provides :ref:`funcargs` which allow to 
+dependency-inject application test state into test functions or 
+methods as function arguments.  If your application is sufficiently modular
+or if you are creating a new project, we recommend you now rather head over to
+:ref:`funcargs` instead because many pytest users agree that using this
+paradigm leads to better application and test organisation.
+
+However, not all programs and frameworks work and can be tested in
+a fully modular way.  They rather require preparation of global state
+like database autouse on which further fixtures like preparing application
+specific tables or wrapping tests in transactions can take place.  For those 
+needs, pytest-2.3 now supports new **fixture functions** which come with
+a ton of improvements over classic xunit fixture writing.  Fixture functions:
+
+- allow to separate different autouse concerns into multiple modular functions
+
+- can receive and fully interoperate with :ref:`funcargs <resources>`,
+
+- are called multiple times if its funcargs are parametrized,
+
+- don't need to be defined directly in your test classes or modules,
+  they can also be defined in a plugin or :ref:`conftest.py <conftest.py>` files and get called 
+
+- are called on a per-session, per-module, per-class or per-function basis
+  by means of a simple "scope" declaration.
+
+- can access the :ref:`request <request>` object which allows to
+  introspect and interact with the (scoped) testcontext.
+
+- can add cleanup functions which will be invoked when the last test
+  of the fixture test context has finished executing.
+
+All of these features are now demonstrated by little examples.
+
+
+
+
+
+test modules accessing a global resource
+-------------------------------------------------------
+
+.. note::
+
+    Relying on `global state is considered bad programming practise <http://en.wikipedia.org/wiki/Global_variable>`_ but when you work with an application
+    that relies on it you often have no choice.
+
+If you want test modules to access a global resource,
+you can stick the resource to the module globals in
+a per-module autouse function.  We use a :ref:`resource factory
+<@pytest.fixture>` to create our global resource::
+
+    # content of conftest.py
+    import pytest
+
+    class GlobalResource:
+        def __init__(self):
+            pass
+
+    @pytest.fixture(scope="session")
+    def globresource():
+        return GlobalResource()
+
+    @pytest.fixture(scope="module")
+    def setresource(request, globresource):
+        request.module.globresource = globresource
+       
+Now any test module can access ``globresource`` as a module global::
+
+    # content of test_glob.py
+
+    def test_1():
+        print ("test_1 %s" % globresource)
+    def test_2():
+        print ("test_2 %s" % globresource)
+
+Let's run this module without output-capturing::
+
+    $ py.test -qs test_glob.py
+    FF
+    ================================= FAILURES =================================
+    __________________________________ test_1 __________________________________
+    
+        def test_1():
+    >       print ("test_1 %s" % globresource)
+    E       NameError: global name 'globresource' is not defined
+    
+    test_glob.py:3: NameError
+    __________________________________ test_2 __________________________________
+    
+        def test_2():
+    >       print ("test_2 %s" % globresource)
+    E       NameError: global name 'globresource' is not defined
+    
+    test_glob.py:5: NameError
+
+The two tests see the same global ``globresource`` object.
+
+Parametrizing the global resource
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+We extend the previous example and add parametrization to the globresource 
+factory and also add a finalizer::
+
+    # content of conftest.py
+
+    import pytest
+
+    class GlobalResource:
+        def __init__(self, param):
+            self.param = param
+
+    @pytest.fixture(scope="session", params=[1,2])
+    def globresource(request):
+        g = GlobalResource(request.param)
+        def fin():
+            print "finalizing", g
+        request.addfinalizer(fin)
+        return g
+
+    @pytest.fixture(scope="module")
+    def setresource(request, globresource):
+        request.module.globresource = globresource
+
+And then re-run our test module::
+
+    $ py.test -qs test_glob.py
+    FF
+    ================================= FAILURES =================================
+    __________________________________ test_1 __________________________________
+    
+        def test_1():
+    >       print ("test_1 %s" % globresource)
+    E       NameError: global name 'globresource' is not defined
+    
+    test_glob.py:3: NameError
+    __________________________________ test_2 __________________________________
+    
+        def test_2():
+    >       print ("test_2 %s" % globresource)
+    E       NameError: global name 'globresource' is not defined
+    
+    test_glob.py:5: NameError
+
+We are now running the two tests twice with two different global resource
+instances.  Note that the tests are ordered such that only
+one instance is active at any given time: the finalizer of 
+the first globresource instance is called before the second
+instance is created and sent to the autouse functions.
+

doc/en/builtin.txt

@@ -1,37 +1,78 @@
 
 .. _`pytest helpers`:
 
-Pytest builtin helpers
+Pytest API and builtin fixtures
 ================================================
 
-builtin pytest.* functions and helping objects
------------------------------------------------------
+This is a list of ``pytest.*`` API functions and fixtures.
 
-You can always use an interactive Python prompt and type::
+For information on plugin hooks and objects, see :ref:`plugins`.
+
+For information on the ``pytest.mark`` mechanism, see :ref:`mark`.
+
+For the below objects, you can also interactively ask for help, e.g. by
+typing on the Python interactive prompt something like::
 
     import pytest
     help(pytest)
 
-to get an overview on the globally available helpers.
+.. currentmodule:: pytest
 
-.. automodule:: pytest
+Invoking pytest interactively
+---------------------------------------------------
+
+.. autofunction:: main
+
+More examples at :ref:`pytest.main-usage`
+
+
+Helpers for assertions about Exceptions/Warnings
+--------------------------------------------------------
+
+.. autofunction:: raises
+
+Examples at :ref:`assertraises`.
+
+.. autofunction:: deprecated_call
+
+Raising a specific test outcome
+--------------------------------------
+
+You can use the following functions in your test, fixture or setup
+functions to force a certain test outcome.  Note that most often
+you can rather use declarative marks, see :ref:`skipping`.
+
+.. autofunction:: _pytest.runner.fail
+.. autofunction:: _pytest.runner.skip
+.. autofunction:: _pytest.runner.importorskip
+.. autofunction:: _pytest.skipping.xfail
+.. autofunction:: _pytest.runner.exit
+
+fixtures and requests
+-----------------------------------------------------
+
+To mark a fixture function:
+
+.. autofunction:: _pytest.python.fixture
+
+Tutorial at :ref:`fixtures`.
+
+The ``request`` object that can be used from fixture functions.
+
+.. autoclass:: _pytest.python.FixtureRequest()
     :members:
 
 
+.. _builtinfixtures:
 .. _builtinfuncargs:
 
-Builtin function arguments
------------------------------------------------------
+Builtin fixtures/function arguments
+-----------------------------------------
 
 You can ask for available builtin or project-custom
-:ref:`function arguments <funcargs>` by typing::
+:ref:`fixtures <fixtures>` by typing::
 
-    $ py.test --funcargs
-    =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collected 0 items
-    pytestconfig
-        the pytest config object with access to command line opts.
+    $ py.test -q --fixtures
     capsys
         enables capturing of writes to sys.stdout/sys.stderr and makes
         captured output available via ``capsys.readouterr()`` method calls
@@ -42,13 +83,6 @@ You can ask for available builtin or project-custom
         captured output available via ``capsys.readouterr()`` method calls
         which return a ``(out, err)`` tuple.
         
-    tmpdir
-        return a temporary directory path object
-        which is 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::
@@ -67,6 +101,8 @@ You can ask for available builtin or project-custom
         parameter determines if a KeyError or AttributeError
         will be raised if the set/deletion operation has no target.
         
+    pytestconfig
+        the pytest config object with access to command line opts.
     recwarn
         Return a WarningsRecorder instance that provides these methods:
         
@@ -76,7 +112,11 @@ You can ask for available builtin or project-custom
         See http://docs.python.org/library/warnings.html for information
         on warning categories.
         
-    cov
-        A pytest funcarg that provides access to the underlying coverage object.
+    tmpdir
+        return a temporary directory path object
+        which is 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.
+        
     
-    =============================  in 0.01 seconds =============================

doc/en/capture.txt

@@ -64,8 +64,8 @@ of the failing function and hide the other one::
 
     $ py.test
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
     
     test_module.py .F
     
@@ -78,8 +78,8 @@ of the failing function and hide the other one::
     
     test_module.py:9: AssertionError
     ----------------------------- Captured stdout ------------------------------
-    setting up <function test_func2 at 0x1013230c8>
-    ==================== 1 failed, 1 passed in 0.03 seconds ====================
+    setting up <function test_func2 at 0x2d63d70>
+    ==================== 1 failed, 1 passed in 0.01 seconds ====================
 
 Accessing captured output from a test function
 ---------------------------------------------------

doc/en/changelog.txt

@@ -4,4 +4,4 @@
 Changelog history
 =================================
 
-.. include:: ../CHANGELOG
+.. include:: ../../CHANGELOG

doc/en/conf.py

@@ -0,0 +1,287 @@
+# -*- coding: utf-8 -*-
+#
+# pytest documentation build configuration file, created by
+# sphinx-quickstart on Fri Oct  8 17:54:28 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The full version, including alpha/beta/rc tags.
+# The short X.Y version.
+version = release = "2.3.3"
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+autodoc_member_order = "bysource"
+todo_include_todos = 1
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# 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', 'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx', 'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'contents'
+
+# General information about the project.
+project = u'pytest'
+copyright = u'2012, holger krekel'
+
+
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['links.inc', '_build', 'naming20.txt', 'test/*',
+    "old_*",
+    '*attic*',
+    '*/attic*',
+    'funcargs.txt',
+    'setup.txt',
+    'example/remoteinterp.txt',
+    ]
+
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinxdoc'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+html_short_title = "pytest-%s" % release
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+#html_sidebars = {'index': 'indexsidebar.html'}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+#html_additional_pages = {'index': 'index.html'}
+
+
+# If false, no module index is generated.
+html_domain_indices = True
+
+# If false, no index is generated.
+html_use_index = False
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pytestdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('contents', 'pytest.tex', u'pytest Documentation',
+   u'holger krekel, http://merlinux.eu', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+latex_domain_indices = False
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('usage', 'pytest', u'pytest usage',
+     [u'holger krekel at merlinux eu'], 1)
+]
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'pytest'
+epub_author = u'holger krekel at merlinux eu'
+epub_publisher = u'holger krekel at merlinux eu'
+epub_copyright = u'2012, holger krekel et alii'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'python': ('http://docs.python.org/', None),
+#                       'lib': ("http://docs.python.org/2.7library/", None),
+                    }
+
+
+def setup(app):
+    #from sphinx.ext.autodoc import cut_lines
+    #app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+    app.add_description_unit('confval', 'confval',
+                             objname='configuration value',
+                             indextemplate='pair: %s; configuration value')

doc/en/contact.txt

@@ -9,6 +9,10 @@ Contact channels
   2.0 and above).  You may also peek at the `old issue tracker`_ but please
   don't submit bugs there anymore.
 
+- `pytest on stackoverflow.com <http://stackoverflow.com/search?q=pytest>`_ 
+  to post questions with the tag ``pytest``.  New Questions will usually 
+  be seen by pytest users or developers. 
+
 - `Testing In Python`_: a mailing list for Python testing tools and discussion.
 
 - `py-dev developers list`_ pytest specific announcements and discussions.

doc/en/contents.txt

@@ -12,11 +12,12 @@ Full pytest documentation
    :maxdepth: 2
 
    overview
-   example/index
    apiref
    plugins
+   example/index
    talks
    develop
+   funcarg_compare.txt
    announce/index
 
 .. toctree::

doc/en/customize.txt

@@ -12,6 +12,8 @@ configurations files by using the general help option::
 This will display command line and configuration file settings
 which were registered by installed plugins.
 
+.. _inifiles:
+
 How test configuration is read from configuration INI-files
 -------------------------------------------------------------
 
@@ -23,8 +25,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
 

doc/en/doctest.txt

@@ -44,10 +44,9 @@ then you can just invoke ``py.test`` without command line options::
 
     $ py.test
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 1 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 1 items
     
     mymodule.py .
     
-    ========================= 1 passed in 0.51 seconds =========================
-    [?1034h
+    ========================= 1 passed in 0.02 seconds =========================

doc/en/example/assertion/failure_demo.py

@@ -15,7 +15,7 @@ def test_generative(param1, param2):
     assert param1 * 2 < param2
 
 def pytest_generate_tests(metafunc):
-    if 'param1' in metafunc.funcargnames:
+    if 'param1' in metafunc.fixturenames:
         metafunc.addcall(funcargs=dict(param1=3, param2=6))
 
 class TestFailing(object):

doc/en/example/attic.txt

@@ -13,9 +13,9 @@ example: specifying and selecting acceptance tests
             help="run (slow) acceptance tests")
 
     def pytest_funcarg__accept(request):
-        return AcceptFuncarg(request)
+        return AcceptFixture(request)
 
-    class AcceptFuncarg:
+    class AcceptFixture:
         def __init__(self, request):
             if not request.config.option.acceptance:
                 pytest.skip("specify -A to run acceptance tests")
@@ -39,7 +39,7 @@ and the actual test function example:
 If you run this test without specifying a command line option
 the test will get skipped with an appropriate message. Otherwise
 you can start to add convenience and test support methods
-to your AcceptFuncarg and drive running of tools or
+to your AcceptFixture and drive running of tools or
 applications and provide ways to do assertions about
 the output.
 

doc/en/example/costlysetup/conftest.py

@@ -0,0 +1,18 @@
+
+import pytest
+
+@pytest.fixture("session")
+def setup(request):
+    setup = CostlySetup()
+    request.addfinalizer(setup.finalize)
+    return setup
+
+class CostlySetup:
+    def __init__(self):
+        import time
+        print ("performing costly setup")
+        time.sleep(5)
+        self.timecostly = 1
+
+    def finalize(self):
+        del self.timecostly

doc/en/example/index.txt

@@ -0,0 +1,33 @@
+
+.. _examples:
+
+Usages and Examples
+===========================================
+
+Here is a (growing) list of examples. :ref:`Contact <contact>` us if you
+need more examples or have questions. Also take a look at the
+:ref:`comprehensive documentation <toc>` which contains many example
+snippets as well.  Also, `pytest on stackoverflow.com
+<http://stackoverflow.com/search?q=pytest>`_ often comes with example
+answers.
+
+For basic examples, see
+
+- :doc:`../getting-started` for basic introductory examples
+- :ref:`assert` for basic assertion examples
+- :ref:`fixtures` for basic fixture/setup examples
+- :ref:`parametrize` for basic test function parametrization
+- :doc:`../unittest` for basic unittest integration
+- :doc:`../nose` for basic nosetests integration
+
+The following examples aim at various use cases you might encounter.
+
+.. toctree::
+   :maxdepth: 2
+
+   reportingdemo.txt
+   simple.txt
+   parametrize.txt
+   markers.txt
+   pythoncollection.txt
+   nonpython.txt

doc/en/example/markers.txt

@@ -26,25 +26,25 @@ You can then restrict a test run to only run tests marked with ``webtest``::
 
     $ py.test -v -m webtest
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2 -- /Users/hpk/venv/0/bin/python
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3 -- /home/hpk/p/pytest/.tox/regen/bin/python
     collecting ... collected 2 items
     
     test_server.py:3: test_send_http PASSED
     
     =================== 1 tests deselected by "-m 'webtest'" ===================
-    ================== 1 passed, 1 deselected in 0.01 seconds ==================
+    ================== 1 passed, 1 deselected in 0.02 seconds ==================
 
 Or the inverse, running all tests except the webtest ones::
     
     $ py.test -v -m "not webtest"
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2 -- /Users/hpk/venv/0/bin/python
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3 -- /home/hpk/p/pytest/.tox/regen/bin/python
     collecting ... collected 2 items
     
     test_server.py:6: test_something_quick PASSED
     
     ================= 1 tests deselected by "-m 'not webtest'" =================
-    ================== 1 passed, 1 deselected in 0.02 seconds ==================
+    ================== 1 passed, 1 deselected in 0.01 seconds ==================
 
 Registering markers
 -------------------------------------
@@ -65,11 +65,13 @@ You can ask which markers exist for your test suite - the list includes our just
     $ py.test --markers
     @pytest.mark.webtest: mark a test as a webtest.
     
-    @pytest.mark.skipif(*conditions): skip the given test function if evaluation of all conditions has a True value.  Evaluation happens within the module global context. Example: skipif('sys.platform == "win32"') skips the test if we are on the win32 platform. 
+    @pytest.mark.skipif(condition): skip the given test function if eval(condition) results in a True value.  Evaluation happens within the module global context. Example: skipif('sys.platform == "win32"') skips the test if we are on the win32 platform. see http://pytest.org/latest/skipping.html
     
-    @pytest.mark.xfail(*conditions, reason=None, run=True): mark the the test function as an expected failure. Optionally specify a reason and run=False if you don't even want to execute the test function. Any positional condition strings will be evaluated (like with skipif) and if one is False the marker will not be applied.
+    @pytest.mark.xfail(condition, reason=None, run=True): mark the the test function as an expected failure if eval(condition) has a True value. Optionally specify a reason for better reporting and run=False if you don't even want to execute the test function. See http://pytest.org/latest/skipping.html
     
-    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in multiple different argument value sets. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.
+    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in multiple different argument value sets. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2. see http://pytest.org/latest/parametrize.html for more info and examples.
+    
+    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see http://pytest.org/latest/fixture.html#usefixtures 
     
     @pytest.mark.tryfirst: mark a hook implementation function such that the plugin machinery will try to call it first/as early as possible.
     
@@ -143,38 +145,38 @@ the given argument::
 
     $ py.test -k send_http  # running with the above defined examples
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 4 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
     
     test_server.py .
     
     =================== 3 tests deselected by '-ksend_http' ====================
-    ================== 1 passed, 3 deselected in 0.02 seconds ==================
+    ================== 1 passed, 3 deselected in 0.01 seconds ==================
 
 And you can also run all tests except the ones that match the keyword::
 
     $ py.test -k-send_http
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 4 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
     
     test_mark_classlevel.py ..
     test_server.py .
     
     =================== 1 tests deselected by '-k-send_http' ===================
-    ================== 3 passed, 1 deselected in 0.03 seconds ==================
+    ================== 3 passed, 1 deselected in 0.01 seconds ==================
 
 Or to only select the class::
 
     $ py.test -kTestClass
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 4 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
     
     test_mark_classlevel.py ..
     
     =================== 2 tests deselected by '-kTestClass' ====================
-    ================== 2 passed, 2 deselected in 0.03 seconds ==================
+    ================== 2 passed, 2 deselected in 0.01 seconds ==================
 
 .. _`adding a custom marker from a plugin`:
 
@@ -192,7 +194,7 @@ specifies via named environments::
 
     import pytest
     def pytest_addoption(parser):
-        parser.addoption("-E", dest="env", action="store", metavar="NAME",
+        parser.addoption("-E", action="store", metavar="NAME",
             help="only run tests matching the environment NAME.")
 
     def pytest_configure(config):
@@ -201,12 +203,10 @@ specifies via named environments::
             "env(name): mark test to run only on named environment")
 
     def pytest_runtest_setup(item):
-        if not isinstance(item, item.Function):
-            return
-        if hasattr(item.obj, 'env'):
-            envmarker = getattr(item.obj, 'env')
+        envmarker = item.keywords.get("env", None)
+        if envmarker is not None:
             envname = envmarker.args[0]
-            if envname != item.config.option.env:
+            if envname != item.config.getoption("-E"):
                 pytest.skip("test requires env %r" % envname)
 
 A test file using this local plugin::
@@ -223,45 +223,49 @@ the test needs::
 
     $ py.test -E stage2
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 1 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 1 items
     
     test_someenv.py s
     
-    ======================== 1 skipped in 0.02 seconds =========================
+    ======================== 1 skipped in 0.01 seconds =========================
   
 and here is one that specifies exactly the environment needed::
 
     $ py.test -E stage1
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 1 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 1 items
     
     test_someenv.py .
     
-    ========================= 1 passed in 0.02 seconds =========================
+    ========================= 1 passed in 0.01 seconds =========================
 
 The ``--markers`` option always gives you a list of available markers::
 
     $ py.test --markers
     @pytest.mark.env(name): mark test to run only on named environment
     
-    @pytest.mark.skipif(*conditions): skip the given test function if evaluation of all conditions has a True value.  Evaluation happens within the module global context. Example: skipif('sys.platform == "win32"') skips the test if we are on the win32 platform. 
+    @pytest.mark.skipif(condition): skip the given test function if eval(condition) results in a True value.  Evaluation happens within the module global context. Example: skipif('sys.platform == "win32"') skips the test if we are on the win32 platform. see http://pytest.org/latest/skipping.html
     
-    @pytest.mark.xfail(*conditions, reason=None, run=True): mark the the test function as an expected failure. Optionally specify a reason and run=False if you don't even want to execute the test function. Any positional condition strings will be evaluated (like with skipif) and if one is False the marker will not be applied.
+    @pytest.mark.xfail(condition, reason=None, run=True): mark the the test function as an expected failure if eval(condition) has a True value. Optionally specify a reason for better reporting and run=False if you don't even want to execute the test function. See http://pytest.org/latest/skipping.html
     
-    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in multiple different argument value sets. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.
+    @pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in multiple different argument value sets. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2. see http://pytest.org/latest/parametrize.html for more info and examples.
+    
+    @pytest.mark.usefixtures(fixturename1, fixturename2, ...): mark tests as needing all of the specified fixtures. see http://pytest.org/latest/fixture.html#usefixtures 
     
     @pytest.mark.tryfirst: mark a hook implementation function such that the plugin machinery will try to call it first/as early as possible.
     
     @pytest.mark.trylast: mark a hook implementation function such that the plugin machinery will try to call it last/as late as possible.
-
+    
     
 Reading markers which were set from multiple places
 ----------------------------------------------------
 
 .. versionadded: 2.2.2
 
+.. regendoc:wipe
+
 If you are heavily using markers in your test suite you may encounter the case where a marker is applied several times to a test function.  From plugin
 code you can read over all such settings.  Example::
 
@@ -279,19 +283,93 @@ Here we have the marker "glob" applied three times to the same
 test function.  From a conftest file we can read it like this::
 
     # content of conftest.py
+    import sys
 
     def pytest_runtest_setup(item):
-        g = getattr(item.obj, 'glob', None)
+        g = item.keywords.get("glob", None)
         if g is not None:
             for info in g:
                 print ("glob args=%s kwargs=%s" %(info.args, info.kwargs))
+                sys.stdout.flush()
 
 Let's run this without capturing output and see what we get::
 
     $ py.test -q -s 
-    collecting ... collected 2 items
-    ..
-    2 passed in 0.02 seconds
     glob args=('function',) kwargs={'x': 3}
     glob args=('class',) kwargs={'x': 2}
     glob args=('module',) kwargs={'x': 1}
+    .
+
+marking platform specific tests with pytest
+--------------------------------------------------------------
+
+.. regendoc:wipe
+
+Consider you have a test suite which marks tests for particular platforms,
+namely ``pytest.mark.osx``, ``pytest.mark.win32`` etc. and you
+also have tests that run on all platforms and have no specific
+marker.  If you now want to have a way to only run the tests 
+for your particular platform, you could use the following plugin::
+
+    # content of conftest.py
+    #
+    import sys
+    import pytest
+
+    ALL = set("osx linux2 win32".split())
+
+    def pytest_runtest_setup(item):
+        if isinstance(item, item.Function):
+            plat = sys.platform
+            if plat not in item.keywords:
+                if ALL.intersection(item.keywords):
+                    pytest.skip("cannot run on platform %s" %(plat))
+
+then tests will be skipped if they were specified for a different platform.
+Let's do a little test file to show how this looks like::
+
+    # content of test_plat.py
+
+    import pytest
+
+    @pytest.mark.osx
+    def test_if_apple_is_evil():
+        pass
+
+    @pytest.mark.linux2
+    def test_if_linux_works():
+        pass
+
+    @pytest.mark.win32
+    def test_if_win32_crashes():
+        pass
+
+    def test_runs_everywhere():
+        pass
+
+then you will see two test skipped and two executed tests as expected::
+
+    $ py.test -rs # this option reports skip reasons
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
+    
+    test_plat.py s.s.
+    ========================= short test summary info ==========================
+    SKIP [2] /tmp/doc-exec-57/conftest.py:12: cannot run on platform linux2
+    
+    =================== 2 passed, 2 skipped in 0.01 seconds ====================
+
+Note that if you specify a platform via the marker-command line option like this::
+
+    $ py.test -m linux2
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
+    
+    test_plat.py .
+    
+    =================== 3 tests deselected by "-m 'linux2'" ====================
+    ================== 1 passed, 3 deselected in 0.01 seconds ==================
+
+then the unmarked-tests will not be run.  It is thus a way to restrict the run to the specific tests.   

doc/en/example/multipython.py

@@ -0,0 +1,50 @@
+"""
+module containing a parametrized tests testing cross-python
+serialization via the pickle module.
+"""
+import py, pytest
+
+pythonlist = ['python2.4', 'python2.5', 'python2.6', 'python2.7', 'python2.8']
+@pytest.fixture(params=pythonlist)
+def python1(request, tmpdir):
+    picklefile = tmpdir.join("data.pickle")
+    return Python(request.param, picklefile)
+
+@pytest.fixture(params=pythonlist)
+def python2(request, python1):
+    return Python(request.param, python1.picklefile)
+
+class Python:
+    def __init__(self, version, picklefile):
+        self.pythonpath = py.path.local.sysfind(version)
+        if not self.pythonpath:
+            py.test.skip("%r not found" %(version,))
+        self.picklefile = picklefile
+    def dumps(self, obj):
+        dumpfile = self.picklefile.dirpath("dump.py")
+        dumpfile.write(py.code.Source("""
+            import pickle
+            f = open(%r, 'wb')
+            s = pickle.dump(%r, f)
+            f.close()
+        """ % (str(self.picklefile), obj)))
+        py.process.cmdexec("%s %s" %(self.pythonpath, dumpfile))
+
+    def load_and_is_true(self, expression):
+        loadfile = self.picklefile.dirpath("load.py")
+        loadfile.write(py.code.Source("""
+            import pickle
+            f = open(%r, 'rb')
+            obj = pickle.load(f)
+            f.close()
+            res = eval(%r)
+            if not res:
+                raise SystemExit(1)
+        """ % (str(self.picklefile), expression)))
+        print (loadfile)
+        py.process.cmdexec("%s %s" %(self.pythonpath, loadfile))
+
+@pytest.mark.parametrize("obj", [42, {}, {1:3},])
+def test_basic_objects(python1, python2, obj):
+    python1.dumps(obj)
+    python2.load_and_is_true("obj == %s" % obj)

doc/en/example/nonpython.txt

@@ -27,8 +27,8 @@ now execute the test specification::
 
     nonpython $ py.test test_simple.yml
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
     
     test_simple.yml .F
     
@@ -37,7 +37,7 @@ now execute the test specification::
     usecase execution failed
        spec failed: 'some': 'other'
        no further details known at this point.
-    ==================== 1 failed, 1 passed in 0.48 seconds ====================
+    ==================== 1 failed, 1 passed in 0.04 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
@@ -56,7 +56,7 @@ consulted when reporting in ``verbose`` mode::
 
     nonpython $ py.test -v
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2 -- /Users/hpk/venv/0/bin/python
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3 -- /home/hpk/p/pytest/.tox/regen/bin/python
     collecting ... collected 2 items
     
     test_simple.yml:1: usecase: ok PASSED
@@ -67,17 +67,17 @@ consulted when reporting in ``verbose`` mode::
     usecase execution failed
        spec failed: 'some': 'other'
        no further details known at this point.
-    ==================== 1 failed, 1 passed in 0.10 seconds ====================
+    ==================== 1 failed, 1 passed in 0.04 seconds ====================
 
 While developing your custom test collection and execution it's also
 interesting to just look at the collection tree::
 
     nonpython $ py.test --collectonly
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
     <YamlFile 'test_simple.yml'>
       <YamlItem 'ok'>
       <YamlItem 'hello'>
     
-    =============================  in 0.18 seconds =============================
+    =============================  in 0.04 seconds =============================

doc/en/example/nonpython/conftest.py

@@ -0,0 +1,40 @@
+# content of conftest.py
+
+import pytest
+
+def pytest_collect_file(parent, path):
+    if path.ext == ".yml" and path.basename.startswith("test"):
+        return YamlFile(path, parent)
+
+class YamlFile(pytest.File):
+    def collect(self):
+        import yaml # we need a yaml parser, e.g. PyYAML
+        raw = yaml.load(self.fspath.open())
+        for name, spec in raw.items():
+            yield YamlItem(name, self, spec)
+
+class YamlItem(pytest.Item):
+    def __init__(self, name, parent, spec):
+        super(YamlItem, self).__init__(name, parent)
+        self.spec = spec
+
+    def runtest(self):
+        for name, value in self.spec.items():
+            # some custom test execution (dumb example follows)
+            if name != value:
+                raise YamlException(self, name, value)
+
+    def repr_failure(self, excinfo):
+        """ called when self.runtest() raises an exception. """
+        if isinstance(excinfo.value, YamlException):
+            return "\n".join([
+                "usecase execution failed",
+                "   spec failed: %r: %r" % excinfo.value.args[1:3],
+                "   no further details known at this point."
+            ])
+
+    def reportinfo(self):
+        return self.fspath, 0, "usecase: %s" % self.name
+
+class YamlException(Exception):
+    """ custom exception for error reporting. """

doc/en/example/parametrize.txt

@@ -7,60 +7,11 @@ Parametrizing tests
 .. currentmodule:: _pytest.python
 
 py.test allows to easily parametrize test functions.
+For basic docs, see :ref:`parametrize-basics`.
+
 In the following we provide some examples using
 the builtin mechanisms.
 
-.. _parametrizemark:
-
-Simple "decorator" parametrization of a test function
-----------------------------------------------------------------------------
-
-.. versionadded:: 2.2
-
-The builtin ``pytest.mark.parametrize`` decorator directly enables
-parametrization of arguments for a test function.  Here is an example
-of a test function that wants to compare that processing some input
-results in expected output::
-
-    # content of test_expectation.py
-    import pytest
-    @pytest.mark.parametrize(("input", "expected"), [
-        ("3+5", 8),
-        ("2+4", 6),
-        ("6*9", 42),
-    ])
-    def test_eval(input, expected):
-        assert eval(input) == expected
-
-we parametrize two arguments of the test function so that the test
-function is called three times.  Let's run it::
-
-    $ py.test -q 
-    collecting ... collected 3 items
-    ..F
-    ================================= FAILURES =================================
-    ____________________________ test_eval[6*9-42] _____________________________
-    
-    input = '6*9', expected = 42
-    
-        @pytest.mark.parametrize(("input", "expected"), [
-            ("3+5", 8),
-            ("2+4", 6),
-            ("6*9", 42),
-        ])
-        def test_eval(input, expected):
-    >       assert eval(input) == expected
-    E       assert 54 == 42
-    E        +  where 54 = eval('6*9')
-    
-    test_expectation.py:8: AssertionError
-    1 failed, 2 passed in 0.03 seconds
-
-As expected only one pair of input/output values fails the simple test function.
-
-Note that there are various ways how you can mark groups of functions,
-see :ref:`mark`.
-
 Generating parameters combinations, depending on command line
 ----------------------------------------------------------------------------
 
@@ -84,7 +35,7 @@ Now we add a test configuration like this::
             help="run all combinations")
 
     def pytest_generate_tests(metafunc):
-        if 'param1' in metafunc.funcargnames:
+        if 'param1' in metafunc.fixturenames:
             if metafunc.config.option.all:
                 end = 5
             else:
@@ -94,15 +45,12 @@ Now we add a test configuration like this::
 This means that we only run 2 tests if we do not pass ``--all``::
 
     $ py.test -q test_compute.py
-    collecting ... collected 2 items
     ..
-    2 passed in 0.03 seconds
 
 We run only two computations, so we see two dots.
 let's run the full monty::
 
     $ py.test -q --all
-    collecting ... collected 5 items
     ....F
     ================================= FAILURES =================================
     _____________________________ test_compute[4] ______________________________
@@ -114,7 +62,6 @@ let's run the full monty::
     E       assert 4 < 4
     
     test_compute.py:3: AssertionError
-    1 failed, 4 passed in 0.05 seconds
 
 As expected when running the full range of ``param1`` values
 we'll get an error on the last one.
@@ -122,7 +69,7 @@ we'll get an error on the last one.
 A quick port of "testscenarios"
 ------------------------------------
 
-.. _`test scenarios`: http://bazaar.launchpad.net/~lifeless/testscenarios/trunk/annotate/head%3A/doc/example.py
+.. _`test scenarios`: http://pypi.python.org/pypi/testscenarios/
 
 Here is a quick port to run tests configured with `test scenarios`_,
 an add-on from Robert Collins for the standard unittest framework. We
@@ -139,7 +86,7 @@ only have to work a bit to construct the correct arguments for pytest's
             items = scenario[1].items()
             argnames = [x[0] for x in items]
             argvalues.append(([x[1] for x in items]))
-        metafunc.parametrize(argnames, argvalues, ids=idlist)
+        metafunc.parametrize(argnames, argvalues, ids=idlist, scope="class")
 
     scenario1 = ('basic', {'attribute': 'value'})
     scenario2 = ('advanced', {'attribute': 'value2'})
@@ -147,34 +94,43 @@ only have to work a bit to construct the correct arguments for pytest's
     class TestSampleWithScenarios:
         scenarios = [scenario1, scenario2]
 
-        def test_demo(self, attribute):
+        def test_demo1(self, attribute):
+            assert isinstance(attribute, str)
+
+        def test_demo2(self, attribute):
             assert isinstance(attribute, str)
 
 this is a fully self-contained example which you can run with::
 
     $ py.test test_scenarios.py
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
     
-    test_scenarios.py ..
+    test_scenarios.py ....
     
-    ========================= 2 passed in 0.02 seconds =========================
+    ========================= 4 passed in 0.01 seconds =========================
 
 If you just collect tests you'll also nicely see 'advanced' and 'basic' as variants for the test function::
 
 
     $ py.test --collectonly test_scenarios.py
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
     <Module 'test_scenarios.py'>
       <Class 'TestSampleWithScenarios'>
         <Instance '()'>
-          <Function 'test_demo[basic]'>
-          <Function 'test_demo[advanced]'>
+          <Function 'test_demo1[basic]'>
+          <Function 'test_demo2[basic]'>
+          <Function 'test_demo1[advanced]'>
+          <Function 'test_demo2[advanced]'>
     
-    =============================  in 0.05 seconds =============================
+    =============================  in 0.01 seconds =============================
+
+Note that we told ``metafunc.parametrize()`` that your scenario values
+should be considered class-scoped.  With pytest-2.3 this leads to a
+resource-based ordering.
 
 Deferring the setup of parametrized resources
 ---------------------------------------------------
@@ -200,9 +156,10 @@ the ``test_db_initialized`` function and also implements a factory that
 creates a database object for the actual test invocations::
 
     # content of conftest.py
+    import pytest
 
     def pytest_generate_tests(metafunc):
-        if 'db' in metafunc.funcargnames:
+        if 'db' in metafunc.fixturenames:
             metafunc.parametrize("db", ['d1', 'd2'], indirect=True)
 
     class DB1:
@@ -210,7 +167,8 @@ creates a database object for the actual test invocations::
     class DB2:
         "alternative database object"
 
-    def pytest_funcarg__db(request):
+    @pytest.fixture
+    def db(request):
         if request.param == "d1":
             return DB1()
         elif request.param == "d2":
@@ -222,23 +180,22 @@ Let's first see how it looks like at collection time::
 
     $ py.test test_backends.py --collectonly
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
     <Module 'test_backends.py'>
       <Function 'test_db_initialized[d1]'>
       <Function 'test_db_initialized[d2]'>
     
-    =============================  in 0.01 seconds =============================
+    =============================  in 0.00 seconds =============================
 
 And then when we run the test::
 
     $ py.test -q test_backends.py
-    collecting ... collected 2 items
     .F
     ================================= FAILURES =================================
     _________________________ test_db_initialized[d2] __________________________
     
-    db = <conftest.DB2 instance at 0x101323710>
+    db = <conftest.DB2 instance at 0x1d8aef0>
     
         def test_db_initialized(db):
             # a dummy test
@@ -247,9 +204,8 @@ And then when we run the test::
     E           Failed: deliberately failing for demo purposes
     
     test_backends.py:6: Failed
-    1 failed, 1 passed in 0.03 seconds
 
-The first invocation with ``db == "DB1"`` passed while the second with ``db == "DB2"`` failed.  Our ``pytest_funcarg__db`` factory has instantiated each of the DB values during the setup phase while the ``pytest_generate_tests`` generated two according calls to the ``test_db_initialized`` during the collection phase.
+The first invocation with ``db == "DB1"`` passed while the second with ``db == "DB2"`` failed.  Our ``db`` fixture function has instantiated each of the DB values during the setup phase while the ``pytest_generate_tests`` generated two according calls to the ``test_db_initialized`` during the collection phase.
 
 .. regendoc:wipe
 
@@ -290,27 +246,25 @@ Our test generator looks up a class-level definition which specifies which
 argument sets to use for each test function.  Let's run it::
 
     $ py.test -q
-    collecting ... collected 3 items
     F..
     ================================= FAILURES =================================
     ________________________ TestClass.test_equals[1-2] ________________________
     
-    self = <test_parametrize.TestClass instance at 0x101326368>, a = 1, b = 2
+    self = <test_parametrize.TestClass instance at 0x1628cb0>, a = 1, b = 2
     
         def test_equals(self, a, b):
     >       assert a == b
     E       assert 1 == 2
     
     test_parametrize.py:18: AssertionError
-    1 failed, 2 passed in 0.03 seconds
 
-Indirect parametrization with multiple resources
+Indirect parametrization with multiple fixtures
 --------------------------------------------------------------
 
 Here is a stripped down real-life example of using parametrized
-testing for testing serialization, invoking different python interpreters.
-We define a ``test_basic_objects`` function which is to be run
-with different sets of arguments for its three arguments:
+testing for testing serialization of objects between different python
+interpreters.  We define a ``test_basic_objects`` function which
+is to be run with different sets of arguments for its three arguments:
 
 * ``python1``: first python interpreter, run to pickle-dump an object to a file
 * ``python2``: second interpreter, run to pickle-load an object from a file
@@ -321,9 +275,6 @@ with different sets of arguments for its three arguments:
 Running it results in some skips if we don't have all the python interpreters installed and otherwise runs all combinations (5 interpreters times 5 interpreters times 3 objects to serialize/deserialize)::
 
    . $ py.test -rs -q multipython.py
-   collecting ... collected 75 items
-   ssssssssssssssssss.........ssssss.........ssssss.........ssssssssssssssssss
+   ............sss............sss............sss............ssssssssssssssssss
    ========================= short test summary info ==========================
-   SKIP [24] /Users/hpk/p/pytest/doc/example/multipython.py:36: 'python2.8' not found
-   SKIP [24] /Users/hpk/p/pytest/doc/example/multipython.py:36: 'python2.4' not found
-   27 passed, 48 skipped in 7.76 seconds
+   SKIP [27] /home/hpk/p/pytest/doc/en/example/multipython.py:21: 'python2.8' not found

doc/en/example/py2py3/conftest.py

@@ -0,0 +1,16 @@
+import sys
+import pytest
+
+py3 = sys.version_info[0] >= 3
+
+class DummyCollector(pytest.collect.File):
+    def collect(self):
+        return []
+
+def pytest_pycollect_makemodule(path, parent):
+    bn = path.basename
+    if "py3" in bn and not py3 or ("py2" in bn and py3):
+        return DummyCollector(path, parent=parent)
+
+
+

doc/en/example/py2py3/test_py2.py

@@ -0,0 +1,7 @@
+
+def test_exception_syntax():
+    try:
+        0/0
+    except ZeroDivisionError, e:
+        pass
+

doc/en/example/py2py3/test_py3.py

@@ -0,0 +1,7 @@
+
+def test_exception_syntax():
+    try:
+        0/0
+    except ZeroDivisionError as e:
+        pass
+

doc/en/example/pythoncollection.txt

@@ -43,8 +43,8 @@ then the test collection looks like this::
 
     $ py.test --collectonly
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
     <Module 'check_myapp.py'>
       <Class 'CheckMyApp'>
         <Instance '()'>
@@ -82,8 +82,8 @@ You can always peek at the collection tree without running tests like this::
 
     . $ py.test --collectonly pythoncollection.py
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 3 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 3 items
     <Module 'pythoncollection.py'>
       <Function 'test_function'>
       <Class 'TestClass'>
@@ -92,3 +92,55 @@ You can always peek at the collection tree without running tests like this::
           <Function 'test_anothermethod'>
     
     =============================  in 0.01 seconds =============================
+
+customizing test collection to find all .py files
+---------------------------------------------------------
+
+.. regendoc:wipe
+
+You can easily instruct py.test to discover tests from every python file::
+
+
+    # content of pytest.ini
+    [pytest]
+    python_files = *.py
+
+However, many projects will have a ``setup.py`` which they don't want to be imported. Moreover, there may files only importable by a specific python version.
+For such cases you can dynamically define files to be ignored by listing 
+them in a ``conftest.py`` file:: 
+
+    # content of conftest.py
+    import sys
+
+    collect_ignore = ["setup.py"]
+    if sys.version_info[0] > 2:
+        collect_ignore.append("pkg/module_py2.py")
+
+And then if you have a module file like this::
+
+    # content of pkg/module_py2.py
+    def test_only_on_python2():
+        try:
+            assert 0
+        except Exception, e:
+            pass
+
+and a setup.py dummy file like this::
+
+    # content of setup.py
+    0/0  # will raise exeption if imported
+
+then a pytest run on python2 will find the one test when run with a python2 
+interpreters and will leave out the setup.py file::
+    
+    $ py.test --collectonly
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 1 items
+    <Module 'pkg/module_py2.py'>
+      <Function 'test_only_on_python2'>
+    
+    =============================  in 0.01 seconds =============================
+
+If you run with a Python3 interpreter the moduled added through the conftest.py file will not be considered for test collection.
+

doc/en/example/reportingdemo.txt

@@ -13,8 +13,8 @@ get on the terminal - we are working on that):
 
     assertion $ py.test failure_demo.py
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 39 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 39 items
     
     failure_demo.py FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
     
@@ -30,7 +30,7 @@ get on the terminal - we are working on that):
     failure_demo.py:15: AssertionError
     _________________________ TestFailing.test_simple __________________________
     
-    self = <failure_demo.TestFailing object at 0x101490690>
+    self = <failure_demo.TestFailing object at 0x1136710>
     
         def test_simple(self):
             def f():
@@ -40,13 +40,13 @@ get on the terminal - we are working on that):
         
     >       assert f() == g()
     E       assert 42 == 43
-    E        +  where 42 = <function f at 0x101462b90>()
-    E        +  and   43 = <function g at 0x101462c08>()
+    E        +  where 42 = <function f at 0x1146410>()
+    E        +  and   43 = <function g at 0x1146488>()
     
     failure_demo.py:28: AssertionError
     ____________________ TestFailing.test_simple_multiline _____________________
     
-    self = <failure_demo.TestFailing object at 0x101490b10>
+    self = <failure_demo.TestFailing object at 0x11329d0>
     
         def test_simple_multiline(self):
             otherfunc_multi(
@@ -66,19 +66,19 @@ get on the terminal - we are working on that):
     failure_demo.py:11: AssertionError
     ___________________________ TestFailing.test_not ___________________________
     
-    self = <failure_demo.TestFailing object at 0x101490210>
+    self = <failure_demo.TestFailing object at 0x10d09d0>
     
         def test_not(self):
             def f():
                 return 42
     >       assert not f()
     E       assert not 42
-    E        +  where 42 = <function f at 0x101462aa0>()
+    E        +  where 42 = <function f at 0x1146848>()
     
     failure_demo.py:38: AssertionError
     _________________ TestSpecialisedExplanations.test_eq_text _________________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x101490a10>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x10ca210>
     
         def test_eq_text(self):
     >       assert 'spam' == 'eggs'
@@ -89,7 +89,7 @@ get on the terminal - we are working on that):
     failure_demo.py:42: AssertionError
     _____________ TestSpecialisedExplanations.test_eq_similar_text _____________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148d9d0>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x11368d0>
     
         def test_eq_similar_text(self):
     >       assert 'foo 1 bar' == 'foo 2 bar'
@@ -102,7 +102,7 @@ get on the terminal - we are working on that):
     failure_demo.py:45: AssertionError
     ____________ TestSpecialisedExplanations.test_eq_multiline_text ____________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148d590>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x11340d0>
     
         def test_eq_multiline_text(self):
     >       assert 'foo\nspam\nbar' == 'foo\neggs\nbar'
@@ -115,7 +115,7 @@ get on the terminal - we are working on that):
     failure_demo.py:48: AssertionError
     ______________ TestSpecialisedExplanations.test_eq_long_text _______________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148dc90>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x10cfd90>
     
         def test_eq_long_text(self):
             a = '1'*100 + 'a' + '2'*100
@@ -132,7 +132,7 @@ get on the terminal - we are working on that):
     failure_demo.py:53: AssertionError
     _________ TestSpecialisedExplanations.test_eq_long_text_multiline __________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148d910>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x10d0b10>
     
         def test_eq_long_text_multiline(self):
             a = '1\n'*100 + 'a' + '2\n'*100
@@ -156,7 +156,7 @@ get on the terminal - we are working on that):
     failure_demo.py:58: AssertionError
     _________________ TestSpecialisedExplanations.test_eq_list _________________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148b9d0>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x1142dd0>
     
         def test_eq_list(self):
     >       assert [0, 1, 2] == [0, 1, 3]
@@ -166,7 +166,7 @@ get on the terminal - we are working on that):
     failure_demo.py:61: AssertionError
     ______________ TestSpecialisedExplanations.test_eq_list_long _______________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148b750>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x1136850>
     
         def test_eq_list_long(self):
             a = [0]*100 + [1] + [3]*100
@@ -178,7 +178,7 @@ get on the terminal - we are working on that):
     failure_demo.py:66: AssertionError
     _________________ TestSpecialisedExplanations.test_eq_dict _________________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148bdd0>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x1134e10>
     
         def test_eq_dict(self):
     >       assert {'a': 0, 'b': 1} == {'a': 0, 'b': 2}
@@ -191,7 +191,7 @@ get on the terminal - we are working on that):
     failure_demo.py:69: AssertionError
     _________________ TestSpecialisedExplanations.test_eq_set __________________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148b1d0>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x1169c90>
     
         def test_eq_set(self):
     >       assert set([0, 10, 11, 12]) == set([0, 20, 21])
@@ -207,7 +207,7 @@ get on the terminal - we are working on that):
     failure_demo.py:72: AssertionError
     _____________ TestSpecialisedExplanations.test_eq_longer_list ______________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148bf10>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x1142c50>
     
         def test_eq_longer_list(self):
     >       assert [1,2] == [1,2,3]
@@ -217,7 +217,7 @@ get on the terminal - we are working on that):
     failure_demo.py:75: AssertionError
     _________________ TestSpecialisedExplanations.test_in_list _________________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x10148b390>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x10d0d90>
     
         def test_in_list(self):
     >       assert 1 in [0, 2, 3, 4, 5]
@@ -226,7 +226,7 @@ get on the terminal - we are working on that):
     failure_demo.py:78: AssertionError
     __________ TestSpecialisedExplanations.test_not_in_text_multiline __________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x101483e50>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x10e0110>
     
         def test_not_in_text_multiline(self):
             text = 'some multiline\ntext\nwhich\nincludes foo\nand a\ntail'
@@ -244,7 +244,7 @@ get on the terminal - we are working on that):
     failure_demo.py:82: AssertionError
     ___________ TestSpecialisedExplanations.test_not_in_text_single ____________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x101483c10>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x10ca7d0>
     
         def test_not_in_text_single(self):
             text = 'single foo line'
@@ -257,7 +257,7 @@ get on the terminal - we are working on that):
     failure_demo.py:86: AssertionError
     _________ TestSpecialisedExplanations.test_not_in_text_single_long _________
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x101483ed0>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x1142750>
     
         def test_not_in_text_single_long(self):
             text = 'head ' * 50 + 'foo ' + 'tail ' * 20
@@ -270,7 +270,7 @@ get on the terminal - we are working on that):
     failure_demo.py:90: AssertionError
     ______ TestSpecialisedExplanations.test_not_in_text_single_long_term _______
     
-    self = <failure_demo.TestSpecialisedExplanations object at 0x101483310>
+    self = <failure_demo.TestSpecialisedExplanations object at 0x1134410>
     
         def test_not_in_text_single_long_term(self):
             text = 'head ' * 50 + 'f'*70 + 'tail ' * 20
@@ -289,7 +289,7 @@ get on the terminal - we are working on that):
             i = Foo()
     >       assert i.b == 2
     E       assert 1 == 2
-    E        +  where 1 = <failure_demo.Foo object at 0x101483f50>.b
+    E        +  where 1 = <failure_demo.Foo object at 0x10e07d0>.b
     
     failure_demo.py:101: AssertionError
     _________________________ test_attribute_instance __________________________
@@ -299,8 +299,8 @@ get on the terminal - we are working on that):
                 b = 1
     >       assert Foo().b == 2
     E       assert 1 == 2
-    E        +  where 1 = <failure_demo.Foo object at 0x101483210>.b
-    E        +    where <failure_demo.Foo object at 0x101483210> = <class 'failure_demo.Foo'>()
+    E        +  where 1 = <failure_demo.Foo object at 0x1132390>.b
+    E        +    where <failure_demo.Foo object at 0x1132390> = <class 'failure_demo.Foo'>()
     
     failure_demo.py:107: AssertionError
     __________________________ test_attribute_failure __________________________
@@ -316,7 +316,7 @@ get on the terminal - we are working on that):
     failure_demo.py:116: 
     _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
     
-    self = <failure_demo.Foo object at 0x101483450>
+    self = <failure_demo.Foo object at 0x1136fd0>
     
         def _get_b(self):
     >       raise Exception('Failed to get attrib')
@@ -332,15 +332,15 @@ get on the terminal - we are working on that):
                 b = 2
     >       assert Foo().b == Bar().b
     E       assert 1 == 2
-    E        +  where 1 = <failure_demo.Foo object at 0x101483150>.b
-    E        +    where <failure_demo.Foo object at 0x101483150> = <class 'failure_demo.Foo'>()
-    E        +  and   2 = <failure_demo.Bar object at 0x101483350>.b
-    E        +    where <failure_demo.Bar object at 0x101483350> = <class 'failure_demo.Bar'>()
+    E        +  where 1 = <failure_demo.Foo object at 0x1134c50>.b
+    E        +    where <failure_demo.Foo object at 0x1134c50> = <class 'failure_demo.Foo'>()
+    E        +  and   2 = <failure_demo.Bar object at 0x1134790>.b
+    E        +    where <failure_demo.Bar object at 0x1134790> = <class 'failure_demo.Bar'>()
     
     failure_demo.py:124: AssertionError
     __________________________ TestRaises.test_raises __________________________
     
-    self = <failure_demo.TestRaises instance at 0x1014a6758>
+    self = <failure_demo.TestRaises instance at 0x10dc098>
     
         def test_raises(self):
             s = 'qwe'
@@ -352,10 +352,10 @@ get on the terminal - we are working on that):
     >   int(s)
     E   ValueError: invalid literal for int() with base 10: 'qwe'
     
-    <0-codegen /Users/hpk/p/pytest/_pytest/python.py:976>:1: ValueError
+    <0-codegen /home/hpk/p/pytest/.tox/regen/lib/python2.7/site-packages/_pytest/python.py:851>:1: ValueError
     ______________________ TestRaises.test_raises_doesnt _______________________
     
-    self = <failure_demo.TestRaises instance at 0x1014b03f8>
+    self = <failure_demo.TestRaises instance at 0x10d8320>
     
         def test_raises_doesnt(self):
     >       raises(IOError, "int('3')")
@@ -364,7 +364,7 @@ get on the terminal - we are working on that):
     failure_demo.py:136: Failed
     __________________________ TestRaises.test_raise ___________________________
     
-    self = <failure_demo.TestRaises instance at 0x1014a8998>
+    self = <failure_demo.TestRaises instance at 0x10c0680>
     
         def test_raise(self):
     >       raise ValueError("demo error")
@@ -373,7 +373,7 @@ get on the terminal - we are working on that):
     failure_demo.py:139: ValueError
     ________________________ TestRaises.test_tupleerror ________________________
     
-    self = <failure_demo.TestRaises instance at 0x1014a27a0>
+    self = <failure_demo.TestRaises instance at 0x11604d0>
     
         def test_tupleerror(self):
     >       a,b = [1]
@@ -382,7 +382,7 @@ get on the terminal - we are working on that):
     failure_demo.py:142: ValueError
     ______ TestRaises.test_reinterpret_fails_with_print_for_the_fun_of_it ______
     
-    self = <failure_demo.TestRaises instance at 0x1014a5518>
+    self = <failure_demo.TestRaises instance at 0x10e2290>
     
         def test_reinterpret_fails_with_print_for_the_fun_of_it(self):
             l = [1,2,3]
@@ -395,11 +395,11 @@ get on the terminal - we are working on that):
     l is [1, 2, 3]
     ________________________ TestRaises.test_some_error ________________________
     
-    self = <failure_demo.TestRaises instance at 0x1014a1320>
+    self = <failure_demo.TestRaises instance at 0x10e2f80>
     
         def test_some_error(self):
     >       if namenotexi:
-    E   NameError: global name 'namenotexi' is not defined
+    E       NameError: global name 'namenotexi' is not defined
     
     failure_demo.py:150: NameError
     ____________________ test_dynamic_compile_shows_nicely _____________________
@@ -420,10 +420,10 @@ get on the terminal - we are working on that):
     >    assert 1 == 0
     E    assert 1 == 0
     
-    <2-codegen 'abc-123' /Users/hpk/p/pytest/doc/example/assertion/failure_demo.py:162>:2: AssertionError
+    <2-codegen 'abc-123' /home/hpk/p/pytest/doc/en/example/assertion/failure_demo.py:162>:2: AssertionError
     ____________________ TestMoreErrors.test_complex_error _____________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x1014a6638>
+    self = <failure_demo.TestMoreErrors instance at 0x10d1b90>
     
         def test_complex_error(self):
             def f():
@@ -452,7 +452,7 @@ get on the terminal - we are working on that):
     failure_demo.py:5: AssertionError
     ___________________ TestMoreErrors.test_z1_unpack_error ____________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x1014a42d8>
+    self = <failure_demo.TestMoreErrors instance at 0x114f3b0>
     
         def test_z1_unpack_error(self):
             l = []
@@ -462,7 +462,7 @@ get on the terminal - we are working on that):
     failure_demo.py:179: ValueError
     ____________________ TestMoreErrors.test_z2_type_error _____________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x1014a0128>
+    self = <failure_demo.TestMoreErrors instance at 0x11496c8>
     
         def test_z2_type_error(self):
             l = 3
@@ -472,19 +472,19 @@ get on the terminal - we are working on that):
     failure_demo.py:183: TypeError
     ______________________ TestMoreErrors.test_startswith ______________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x1014a0ef0>
+    self = <failure_demo.TestMoreErrors instance at 0x10cec20>
     
         def test_startswith(self):
             s = "123"
             g = "456"
     >       assert s.startswith(g)
-    E       assert <built-in method startswith of str object at 0x1014951c0>('456')
-    E        +  where <built-in method startswith of str object at 0x1014951c0> = '123'.startswith
+    E       assert <built-in method startswith of str object at 0x113b918>('456')
+    E        +  where <built-in method startswith of str object at 0x113b918> = '123'.startswith
     
     failure_demo.py:188: AssertionError
     __________________ TestMoreErrors.test_startswith_nested ___________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x1014a4170>
+    self = <failure_demo.TestMoreErrors instance at 0x10c87a0>
     
         def test_startswith_nested(self):
             def f():
@@ -492,15 +492,15 @@ get on the terminal - we are working on that):
             def g():
                 return "456"
     >       assert f().startswith(g())
-    E       assert <built-in method startswith of str object at 0x1014951c0>('456')
-    E        +  where <built-in method startswith of str object at 0x1014951c0> = '123'.startswith
-    E        +    where '123' = <function f at 0x1014aea28>()
-    E        +  and   '456' = <function g at 0x101477c80>()
+    E       assert <built-in method startswith of str object at 0x113b918>('456')
+    E        +  where <built-in method startswith of str object at 0x113b918> = '123'.startswith
+    E        +    where '123' = <function f at 0x10bea28>()
+    E        +  and   '456' = <function g at 0x10beaa0>()
     
     failure_demo.py:195: AssertionError
     _____________________ TestMoreErrors.test_global_func ______________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x1014b3ab8>
+    self = <failure_demo.TestMoreErrors instance at 0x10c5488>
     
         def test_global_func(self):
     >       assert isinstance(globf(42), float)
@@ -510,18 +510,18 @@ get on the terminal - we are working on that):
     failure_demo.py:198: AssertionError
     _______________________ TestMoreErrors.test_instance _______________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x1014a2878>
+    self = <failure_demo.TestMoreErrors instance at 0x113f710>
     
         def test_instance(self):
             self.x = 6*7
     >       assert self.x != 42
     E       assert 42 != 42
-    E        +  where 42 = <failure_demo.TestMoreErrors instance at 0x1014a2878>.x
+    E        +  where 42 = <failure_demo.TestMoreErrors instance at 0x113f710>.x
     
     failure_demo.py:202: AssertionError
     _______________________ TestMoreErrors.test_compare ________________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x10149da70>
+    self = <failure_demo.TestMoreErrors instance at 0x10bae18>
     
         def test_compare(self):
     >       assert globf(10) < 5
@@ -531,7 +531,7 @@ get on the terminal - we are working on that):
     failure_demo.py:205: AssertionError
     _____________________ TestMoreErrors.test_try_finally ______________________
     
-    self = <failure_demo.TestMoreErrors instance at 0x101493908>
+    self = <failure_demo.TestMoreErrors instance at 0x1160248>
     
         def test_try_finally(self):
             x = 1
@@ -540,4 +540,4 @@ get on the terminal - we are working on that):
     E           assert 1 == 0
     
     failure_demo.py:210: AssertionError
-    ======================== 39 failed in 1.05 seconds =========================
+    ======================== 39 failed in 0.25 seconds =========================

doc/en/example/simple.txt

@@ -22,20 +22,22 @@ Here is a basic pattern how to achieve this::
 
 
 For this to work we need to add a command line option and
-provide the ``cmdopt`` through a :ref:`function argument <funcarg>` factory::
+provide the ``cmdopt`` through a :ref:`fixture function <fixture function>`::
 
     # content of conftest.py
+    import pytest
+
     def pytest_addoption(parser):
         parser.addoption("--cmdopt", action="store", default="type1",
             help="my option: type1 or type2")
 
-    def pytest_funcarg__cmdopt(request):
-        return request.config.option.cmdopt
+    @pytest.fixture
+    def cmdopt(request):
+        return request.config.getoption("--cmdopt")
 
-Let's run this without supplying our new command line option::
+Let's run this without supplying our new option::
 
     $ py.test -q test_sample.py
-    collecting ... collected 1 items
     F
     ================================= FAILURES =================================
     _______________________________ test_answer ________________________________
@@ -53,12 +55,10 @@ Let's run this without supplying our new command line option::
     test_sample.py:6: AssertionError
     ----------------------------- Captured stdout ------------------------------
     first
-    1 failed in 0.50 seconds
 
 And now with supplying a command line option::
 
     $ py.test -q --cmdopt=type2
-    collecting ... collected 1 items
     F
     ================================= FAILURES =================================
     _______________________________ test_answer ________________________________
@@ -76,14 +76,11 @@ And now with supplying a command line option::
     test_sample.py:6: AssertionError
     ----------------------------- Captured stdout ------------------------------
     second
-    1 failed in 0.02 seconds
-
-Ok, this completes the basic pattern.  However, one often rather
-wants to process command line options outside of the test and
-rather pass in different or more complex objects.  See the
-next example or refer to :ref:`mysetup` for more information
-on real-life examples.
 
+You can see that the command line option arrived in our test.  This
+completes the basic pattern.  However, one often rather wants to process
+command line options outside of the test and rather pass in different or
+more complex objects.
 
 Dynamically adding command line options
 --------------------------------------------------------------
@@ -109,13 +106,10 @@ directory with the above conftest.py::
 
     $ py.test
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    gw0 I
-    gw0 [0]
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 0 items
     
-    scheduling tests via LoadScheduling
-    
-    =============================  in 5.12 seconds =============================
+    =============================  in 0.00 seconds =============================
 
 .. _`excontrolskip`:
 
@@ -135,7 +129,7 @@ line option to control skipping of ``slow`` marked tests::
             help="run slow tests")
 
     def pytest_runtest_setup(item):
-        if 'slow' in item.keywords and not item.config.getvalue("runslow"):
+        if 'slow' in item.keywords and not item.config.getoption("--runslow"):
             pytest.skip("need --runslow option to run")
 
 We can now write a test module like this::
@@ -156,25 +150,25 @@ and when running it will see a skipped "slow" test::
 
     $ py.test -rs    # "-rs" means report details on the little 's'
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
     
     test_module.py .s
     ========================= short test summary info ==========================
-    SKIP [1] /Users/hpk/tmp/doc-exec-158/conftest.py:9: need --runslow option to run
+    SKIP [1] /tmp/doc-exec-62/conftest.py:9: need --runslow option to run
     
-    =================== 1 passed, 1 skipped in 0.09 seconds ====================
+    =================== 1 passed, 1 skipped in 0.01 seconds ====================
 
 Or run it including the ``slow`` marked test::
 
     $ py.test --runslow
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 2 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
     
     test_module.py ..
     
-    ========================= 2 passed in 0.02 seconds =========================
+    ========================= 2 passed in 0.01 seconds =========================
 
 Writing well integrated assertion helpers
 --------------------------------------------------
@@ -203,7 +197,6 @@ unless the ``--fulltrace`` command line option is specified.
 Let's run our little function::
 
     $ py.test -q test_checkconfig.py
-    collecting ... collected 1 items
     F
     ================================= FAILURES =================================
     ______________________________ test_something ______________________________
@@ -213,7 +206,6 @@ Let's run our little function::
     E       Failed: not configured: 42
     
     test_checkconfig.py:8: Failed
-    1 failed in 0.07 seconds
 
 Detect if running from within a py.test run
 --------------------------------------------------------------
@@ -261,11 +253,11 @@ which will add the string to the test header accordingly::
 
     $ py.test
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
     project deps: mylib-1.1
-    collecting ... collected 0 items
+    collected 0 items
     
-    =============================  in 0.01 seconds =============================
+    =============================  in 0.00 seconds =============================
 
 .. regendoc:wipe
 
@@ -284,21 +276,21 @@ which will add info only when run with "--v"::
 
     $ py.test -v
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2 -- /Users/hpk/venv/0/bin/python
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3 -- /home/hpk/p/pytest/.tox/regen/bin/python
     info1: did you know that ...
     did you?
     collecting ... collected 0 items
     
-    =============================  in 0.03 seconds =============================
+    =============================  in 0.00 seconds =============================
 
 and nothing when run plainly::
 
     $ py.test
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 0 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 0 items
     
-    =============================  in 0.01 seconds =============================
+    =============================  in 0.00 seconds =============================
 
 profiling test duration
 --------------------------
@@ -327,8 +319,8 @@ Now we can profile which test functions execute the slowest::
 
     $ py.test --durations=3
     =========================== test session starts ============================
-    platform darwin -- Python 2.7.1 -- pytest-2.2.2
-    collecting ... collected 3 items
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 3 items
     
     test_some_are_slow.py ...
     
@@ -336,4 +328,78 @@ Now we can profile which test functions execute the slowest::
     0.20s call     test_some_are_slow.py::test_funcslow2
     0.10s call     test_some_are_slow.py::test_funcslow1
     0.00s call     test_some_are_slow.py::test_funcfast
-    ========================= 3 passed in 0.33 seconds =========================
+    ========================= 3 passed in 0.31 seconds =========================
+
+incremental testing - test steps
+---------------------------------------------------
+
+.. regendoc:wipe
+
+Sometimes you may have a testing situation which consists of a series
+of test steps.  If one step fails it makes no sense to execute further
+steps as they are all expected to fail anyway and their tracebacks
+add no insight.  Here is a simple ``conftest.py`` file which introduces
+an ``incremental`` marker which is to be used on classes::
+
+    # content of conftest.py
+
+    import pytest
+
+    def pytest_runtest_makereport(item, call):
+        if "incremental" in item.keywords:
+            if call.excinfo is not None:
+                parent = item.parent
+                parent._previousfailed = item
+
+    def pytest_runtest_setup(item):
+        if "incremental" in item.keywords:
+            previousfailed = getattr(item.parent, "_previousfailed", None)
+            if previousfailed is not None:
+                pytest.xfail("previous test failed (%s)" %previousfailed.name)
+
+These two hook implementations work together to abort incremental-marked
+tests in a class.  Here is a test module example::
+
+    # content of test_step.py
+
+    import pytest
+
+    @pytest.mark.incremental
+    class TestUserHandling:
+        def test_login(self):
+            pass
+        def test_modification(self):
+            assert 0
+        def test_deletion(self):
+            pass
+
+    def test_normal():
+        pass
+
+If we run this::
+
+    $ py.test -rx
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 4 items
+    
+    test_step.py .Fx.
+    
+    ================================= FAILURES =================================
+    ____________________ TestUserHandling.test_modification ____________________
+    
+    self = <test_step.TestUserHandling instance at 0x2677b90>
+    
+        def test_modification(self):
+    >       assert 0
+    E       assert 0
+    
+    test_step.py:9: AssertionError
+    ========================= short test summary info ==========================
+    XFAIL test_step.py::TestUserHandling::()::test_deletion
+      reason: previous test failed (test_modification)
+    ============== 1 failed, 2 passed, 1 xfailed in 0.02 seconds ===============
+
+We'll see that ``test_deletion`` was not executed because ``test_modification``
+failed.  It is reported as an "expected failure".
+

doc/en/faq.txt

@@ -3,12 +3,84 @@ Some Issues and Questions
 
 .. note::
 
-    If you don't find an answer here, checkout the :ref:`contact channels`
-    to get help.
+    If you don't find an answer here, you may checkout 
+    `pytest Q&A at Stackoverflow <http://stackoverflow.com/search?q=pytest>`_ 
+    or other :ref:`contact channels` to get help.
 
 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 in pytest style.  
+If you are using trial's unittest.TestCase chances are that you can
+just run your tests even if you return Deferreds.  In addition,
+there also is a dedicated `pytest-twisted
+<http://pypi.python.org/pypi/pytest-twisted`` plugin which allows to
+return deferreds from pytest-style tests, allowing to use
+:ref:`fixtures` and other features.
+ 
+how does py.test work with Django?
+++++++++++++++++++++++++++++++++++++++++++++++
+
+In 2012, some work is going into the `pytest-django plugin <http://pypi.python.org/pypi/pytest-django>`_.  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: 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 <assertfeedback>`.
+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 mostly obsolete assert debugging technique,
+invoked via ``--assert=reinterpret``, activated by default on
+Python-2.5: When an ``assert`` statement fails, py.test re-interprets
+the expression part to show intermediate values.  This 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,53 +92,12 @@ 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
 -------------------------------------------------------
 
-.. _funcargs: test/funcargs.html
+.. _funcargs: funcargs.html
 
 Is using funcarg- versus xUnit setup a style question?
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -80,9 +111,9 @@ 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
+.. _monkeypatch: monkeypatch.html
+.. _tmpdir: tmpdir.html
+.. _capture: capture.html
 
 .. _`why pytest_pyfuncarg__ methods?`:
 
@@ -95,9 +126,14 @@ it is nice to be able to search for ``pytest_funcarg__MYARG`` in
 source code and safely find all factory functions for
 the ``MYARG`` function argument.
 
+.. note::
+
+    With pytest-2.3 you can use the :ref:`@pytest.fixture` decorator
+    to mark a function as a fixture function.  
+
 .. _`Convention over Configuration`: http://en.wikipedia.org/wiki/Convention_over_Configuration
 
-Can I yield multiple values from a funcarg factory function?
+Can I yield multiple values from a fixture function function?
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 There are two conceptual reasons why yielding from a factory function
@@ -113,8 +149,12 @@ is not possible:
   policy - in real-world examples some combinations
   often should not run.
 
-Use the `pytest_generate_tests`_ hook to solve both issues
-and implement the `parametrization scheme of your choice`_.
+However, with pytest-2.3 you can use the :ref:`@pytest.fixture` decorator
+and specify ``params`` so that all tests depending on the factory-created
+resource will run multiple times with different parameters.
+
+You can also use the `pytest_generate_tests`_ hook to 
+implement the `parametrization scheme of your choice`_.
 
 .. _`pytest_generate_tests`: test/funcargs.html#parametrizing-tests
 .. _`parametrization scheme of your choice`: http://tetamap.wordpress.com/2009/05/13/parametrizing-python-tests-generalized/

doc/en/fixture.txt

@@ -0,0 +1,689 @@
+.. _fixture:
+.. _fixtures:
+.. _`fixture functions`:
+
+pytest fixtures: explicit, modular, scalable
+========================================================
+
+.. currentmodule:: _pytest.python
+
+.. versionadded:: 2.0/2.3
+
+.. _`xUnit`: http://en.wikipedia.org/wiki/XUnit
+.. _`general purpose of test fixtures`: http://en.wikipedia.org/wiki/Test_fixture#Software
+.. _`Dependency injection`: http://en.wikipedia.org/wiki/Dependency_injection#Definition
+
+The `general purpose of test fixtures`_ is to provide a fixed baseline
+upon which tests can reliably and repeatedly execute.   pytest-2.3 fixtures
+offer dramatic improvements over the classic xUnit style of setup/teardown 
+functions:
+
+* fixtures have explicit names and are activated by declaring their use
+  from test functions, modules, classes or whole projects.
+
+* fixtures are implemented in a modular manner, as each fixture name
+  triggers a *fixture function* which can itself easily use other 
+  fixtures.
+
+* fixture management scales from simple unit to complex
+  functional testing, allowing to parametrize fixtures and tests according
+  to configuration and component options, or to re-use fixtures
+  across class, module or whole test session scopes.
+
+In addition, pytest continues to support :ref:`xunitsetup`.  You can mix
+both styles, moving incrementally from classic to new style, as you
+prefer.  You can also start out from existing :ref:`unittest.TestCase
+style <unittest.TestCase>` or :ref:`nose based <nosestyle>` projects.
+
+.. _`funcargs`:
+.. _`funcarg mechanism`:
+.. _`fixture function`:
+.. _`@pytest.fixture`:
+.. _`pytest.fixture`:
+
+Fixtures as Function arguments (funcargs)
+-----------------------------------------
+
+Test functions can receive fixture objects by naming them as an input
+argument. For each argument name, a fixture function with that name provides 
+the fixture object.  Fixture functions are registered by marking them with
+:py:func:`@pytest.fixture <_pytest.python.fixture>`.  Let's look at a simple
+self-contained test module containing a fixture and a test function
+using it::
+
+    # content of ./test_smtpsimple.py
+    import pytest
+
+    @pytest.fixture
+    def smtp():
+        import smtplib
+        return smtplib.SMTP("merlinux.eu")
+
+    def test_ehlo(smtp):
+        response, msg = smtp.ehlo()
+        assert response == 250
+        assert "merlinux" in msg
+        assert 0 # for demo purposes
+
+Here, the ``test_ehlo`` needs the ``smtp`` fixture value.  pytest 
+will discover and call the :py:func:`@pytest.fixture <_pytest.python.fixture>` 
+marked ``smtp`` fixture function.  Running the test looks like this::
+
+    $ py.test test_smtpsimple.py
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 1 items
+    
+    test_smtpsimple.py F
+    
+    ================================= FAILURES =================================
+    ________________________________ test_ehlo _________________________________
+    
+    smtp = <smtplib.SMTP instance at 0x1992a70>
+    
+        def test_ehlo(smtp):
+            response, msg = smtp.ehlo()
+            assert response == 250
+            assert "merlinux" in msg
+    >       assert 0 # for demo purposes
+    E       assert 0
+    
+    test_smtpsimple.py:12: AssertionError
+    ========================= 1 failed in 0.30 seconds =========================
+
+In the failure traceback we see that the test function was called with a
+``smtp`` argument, the ``smtplib.SMTP()`` instance created by the fixture
+function.  The test function fails on our deliberate ``assert 0``.  Here is
+an exact protocol of how py.test comes to call the test function this way:
+
+1. pytest :ref:`finds <test discovery>` the ``test_ehlo`` because
+   of the ``test_`` prefix.  The test function needs a function argument
+   named ``smtp``.  A matching fixture function is discovered by
+   looking for a fixture-marked function named ``smtp``.
+
+2. ``smtp()`` is called to create an instance.
+
+3. ``test_ehlo(<SMTP instance>)`` is called and fails in the last
+   line of the test function.
+
+Note that if you misspell a function argument or want
+to use one that isn't available, you'll see an error
+with a list of available function arguments.
+
+.. Note::
+
+    You can always issue::
+
+        py.test --fixtures test_simplefactory.py
+
+    to see available fixtures.
+
+    In versions prior to 2.3 there was no ``@pytest.fixture`` marker
+    and you had to use a magic ``pytest_funcarg__NAME`` prefix
+    for the fixture factory.  This remains and will remain supported 
+    but is not anymore advertised as the primary means of declaring fixture
+    functions.
+
+Funcargs a prime example of dependency injection
+---------------------------------------------------
+
+When injecting fixtures to test functions, pytest-2.0 introduced the
+term "funcargs" or "funcarg mechanism" which continues to be present
+also in pytest-2.3 docs.  It now refers to the specific case of injecting
+fixture values as arguments to test functions.  With pytest-2.3 there are
+more possibilities to use fixtures but "funcargs" probably will remain
+as the main way of dealing with fixtures.
+
+As the following examples show in more detail, funcargs allow test
+functions to easily receive and work against specific pre-initialized
+application objects without having to care about import/setup/cleanup
+details.  It's a prime example of `dependency injection`_ where fixture
+functions take the role of the *injector* and test functions are the
+*consumers* of fixture objects.
+
+.. _smtpshared:
+
+Working with a module-shared fixture
+-----------------------------------------------------------------
+
+.. regendoc:wipe
+
+Fixtures requiring network access depend on connectivity and are 
+usually time-expensive to create.  Extending the previous example, we
+can add a ``scope='module'`` parameter to the 
+:py:func:`@pytest.fixture <_pytest.python.fixture>` invocation
+to cause the decorated ``smtp`` fixture function to only be invoked once 
+per test module.  Multiple test functions in a test module will thus
+each receive the same ``smtp`` fixture instance.  The next example also
+extracts the fixture function into a separate ``conftest.py`` file so
+that all tests in test modules in the directory can access the fixture
+function::
+
+    # content of conftest.py
+    import pytest
+    import smtplib
+
+    @pytest.fixture(scope="module")
+    def smtp():
+        return smtplib.SMTP("merlinux.eu")
+
+The name of the fixture again is ``smtp`` and you can access its result by
+listing the name ``smtp`` as an input parameter in any test or setup
+function (in or below the directory where ``conftest.py`` is located)::
+
+    # content of test_module.py
+
+    def test_ehlo(smtp):
+        response = smtp.ehlo()
+        assert response[0] == 250 
+        assert "merlinux" in response[1]
+        assert 0  # for demo purposes
+
+    def test_noop(smtp):
+        response = smtp.noop()
+        assert response[0] == 250
+        assert 0  # for demo purposes
+
+We deliberately insert failing ``assert 0`` statements in order to
+inspect what is going on and can now run the tests::
+
+    $ py.test test_module.py
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3
+    collected 2 items
+    
+    test_module.py FF
+    
+    ================================= FAILURES =================================
+    ________________________________ test_ehlo _________________________________
+    
+    smtp = <smtplib.SMTP instance at 0x2b8a248>
+    
+        def test_ehlo(smtp):
+            response = smtp.ehlo()
+            assert response[0] == 250
+            assert "merlinux" in response[1]
+    >       assert 0  # for demo purposes
+    E       assert 0
+    
+    test_module.py:6: AssertionError
+    ________________________________ test_noop _________________________________
+    
+    smtp = <smtplib.SMTP instance at 0x2b8a248>
+    
+        def test_noop(smtp):
+            response = smtp.noop()
+            assert response[0] == 250
+    >       assert 0  # for demo purposes
+    E       assert 0
+    
+    test_module.py:11: AssertionError
+    ========================= 2 failed in 0.48 seconds =========================
+
+You see the two ``assert 0`` failing and more importantly you can also see 
+that the same (module-scoped) ``smtp`` object was passed into the two 
+test functions because pytest shows the incoming argument values in the 
+traceback.  As a result, the two test functions using ``smtp`` run as
+quick as a single one because they reuse the same instance.
+
+If you decide that you rather want to have a session-scoped ``smtp``
+instance, you can simply declare it::
+
+    @pytest.fixture(scope=``session``)
+    def smtp(...):
+        # the returned fixture value will be shared for 
+        # all tests needing it
+        
+.. _`request-context`:
+
+Fixtures can interact with the requesting test context
+-------------------------------------------------------------
+
+Fixture functions can themselves use other fixtures by naming
+them as an input argument just like test functions do, see 
+:ref:`interdependent fixtures`.  Moreover, pytest 
+provides a builtin :py:class:`request <FixtureRequest>` object,
+which fixture functions can use to introspect the function, class or module
+for which they are invoked or to register finalizing (cleanup)
+functions which are called when the last test finished execution.  
+
+Further extending the previous ``smtp`` fixture example, let's  
+read an optional server URL from the module namespace and register 
+a finalizer that closes the smtp connection after the last
+test in a module finished execution::
+
+    # content of conftest.py
+    import pytest
+    import smtplib
+
+    @pytest.fixture(scope="module")
+    def smtp(request):
+        server = getattr(request.module, "smtpserver", "merlinux.eu")
+        smtp = smtplib.SMTP(server)
+        def fin():
+            print ("finalizing %s" % smtp)
+            smtp.close()
+        request.addfinalizer(fin)
+        return smtp
+
+The registered ``fin`` function will be called when the last test
+using it has executed::
+
+    $ py.test -s -q --tb=no
+    FF
+    finalizing <smtplib.SMTP instance at 0x1584908>
+
+We see that the ``smtp`` instance is finalized after the two
+tests using it tests executed.  If we had specified ``scope='function'`` 
+then fixture setup and cleanup would occur around each single test. 
+Note that either case the test module itself does not need to change!
+
+Let's quickly create another test module that actually sets the
+server URL and has a test to verify the fixture picks it up::
+    
+    # content of test_anothersmtp.py
+    
+    smtpserver = "mail.python.org"  # will be read by smtp fixture
+
+    def test_showhelo(smtp):
+        assert 0, smtp.helo()
+
+Running it::
+
+    $ py.test -qq --tb=short test_anothersmtp.py
+    F
+    ================================= FAILURES =================================
+    ______________________________ test_showhelo _______________________________
+    test_anothersmtp.py:5: in test_showhelo
+    >       assert 0, smtp.helo()
+    E       AssertionError: (250, 'mail.python.org')
+
+.. _`request`: :py:class:`_pytest.python.FixtureRequest`
+
+.. _`fixture-parametrize`:
+
+Parametrizing a fixture
+-----------------------------------------------------------------
+
+Fixture functions can be parametrized in which case they will be called
+multiple times, each time executing the set of dependent tests, i. e. the
+tests that depend on this fixture.  Test functions do usually not need
+to be aware of their re-running.  Fixture parametrization helps to
+write exhaustive functional tests for components which themselves can be 
+configured in multiple ways.
+
+Extending the previous example, we can flag the fixture to create two
+``smtp`` fixture instances which will cause all tests using the fixture
+to run twice.  The fixture function gets access to each parameter
+through the special `request`_ object::
+
+    # content of conftest.py
+    import pytest
+    import smtplib
+
+    @pytest.fixture(scope="module", 
+                    params=["merlinux.eu", "mail.python.org"])
+    def smtp(request):
+        smtp = smtplib.SMTP(request.param)
+        def fin():
+            print ("finalizing %s" % smtp)
+            smtp.close()
+        request.addfinalizer(fin)
+        return smtp
+
+The main change is the declaration of ``params`` with 
+:py:func:`@pytest.fixture <_pytest.python.fixture>`, a list of values
+for each of which the fixture function will execute and can access
+a value via ``request.param``.  No test function code needs to change.  
+So let's just do another run::
+
+    $ py.test -q test_module.py
+    FFFF
+    ================================= FAILURES =================================
+    __________________________ test_ehlo[merlinux.eu] __________________________
+    
+    smtp = <smtplib.SMTP instance at 0x2368248>
+    
+        def test_ehlo(smtp):
+            response = smtp.ehlo()
+            assert response[0] == 250
+            assert "merlinux" in response[1]
+    >       assert 0  # for demo purposes
+    E       assert 0
+    
+    test_module.py:6: AssertionError
+    __________________________ test_noop[merlinux.eu] __________________________
+    
+    smtp = <smtplib.SMTP instance at 0x2368248>
+    
+        def test_noop(smtp):
+            response = smtp.noop()
+            assert response[0] == 250
+    >       assert 0  # for demo purposes
+    E       assert 0
+    
+    test_module.py:11: AssertionError
+    ________________________ test_ehlo[mail.python.org] ________________________
+    
+    smtp = <smtplib.SMTP instance at 0x2377680>
+    
+        def test_ehlo(smtp):
+            response = smtp.ehlo()
+            assert response[0] == 250
+    >       assert "merlinux" in response[1]
+    E       assert 'merlinux' in 'mail.python.org\nSIZE 10240000\nETRN\nSTARTTLS\nENHANCEDSTATUSCODES\n8BITMIME\nDSN'
+    
+    test_module.py:5: AssertionError
+    ________________________ test_noop[mail.python.org] ________________________
+    
+    smtp = <smtplib.SMTP instance at 0x2377680>
+    
+        def test_noop(smtp):
+            response = smtp.noop()
+            assert response[0] == 250
+    >       assert 0  # for demo purposes
+    E       assert 0
+    
+    test_module.py:11: AssertionError
+
+We see that our two test functions each ran twice, against the different
+``smtp`` instances.  Note also, that with the ``mail.python.org`` 
+connection the second test fails in ``test_ehlo`` because a 
+different server string is expected than what arrived.
+
+
+.. _`interdependent fixtures`:
+
+Modularity: using fixtures from a fixture function
+----------------------------------------------------------
+
+You can not only use fixtures in test functions but fixture functions
+can use other fixtures themselves.  This contributes to a modular design
+of your fixtures and allows re-use of framework-specific fixtures across
+many projects.  As a simple example, we can extend the previous example
+and instantiate an object ``app`` where we stick the already defined
+``smtp`` resource into it::
+
+    # content of test_appsetup.py
+   
+    import pytest
+
+    class App:
+        def __init__(self, smtp):
+            self.smtp = smtp
+
+    @pytest.fixture(scope="module")
+    def app(smtp):
+        return App(smtp)
+
+    def test_smtp_exists(app):
+        assert app.smtp
+
+Here we declare an ``app`` fixture which receives the previously defined
+``smtp`` fixture and instantiates an ``App`` object with it.  Let's run it::
+
+    $ py.test -v test_appsetup.py
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3 -- /home/hpk/p/pytest/.tox/regen/bin/python
+    collecting ... collected 2 items
+    
+    test_appsetup.py:12: test_smtp_exists[merlinux.eu] PASSED
+    test_appsetup.py:12: test_smtp_exists[mail.python.org] PASSED
+    
+    ========================= 2 passed in 6.79 seconds =========================
+
+Due to the parametrization of ``smtp`` the test will run twice with two
+different ``App`` instances and respective smtp servers.  There is no
+need for the ``app`` fixture to be aware of the ``smtp`` parametrization 
+as pytest will fully analyse the fixture dependency graph.  
+
+Note, that the ``app`` fixture has a scope of ``module`` and uses a
+module-scoped ``smtp`` fixture.  The example would still work if ``smtp``
+was cached on a ``session`` scope: it is fine for fixtures to use 
+"broader" scoped fixtures but not the other way round:
+A session-scoped fixture could not use a module-scoped one in a
+meaningful way.
+
+
+.. _`automatic per-resource grouping`:
+
+Automatic grouping of tests by fixture instances
+----------------------------------------------------------
+
+.. regendoc: wipe
+
+pytest minimizes the number of active fixtures during test runs.
+If you have a parametrized fixture, then all the tests using it will
+first execute with one instance and then finalizers are called 
+before the next fixture instance is created.  Among other things,
+this eases testing of applications which create and use global state.
+
+The following example uses two parametrized funcargs, one of which is 
+scoped on a per-module basis, and all the functions perform ``print`` calls
+to show the setup/teardown flow::
+
+    # content of test_module.py
+    import pytest
+
+    @pytest.fixture(scope="module", params=["mod1", "mod2"])
+    def modarg(request):
+        param = request.param
+        print "create", param
+        def fin():
+            print "fin", param
+        request.addfinalizer(fin)
+        return param
+
+    @pytest.fixture(scope="function", params=[1,2])
+    def otherarg(request):
+        return request.param
+
+    def test_0(otherarg):
+        print "  test0", otherarg
+    def test_1(modarg):
+        print "  test1", modarg
+    def test_2(otherarg, modarg):
+        print "  test2", otherarg, modarg
+
+Let's run the tests in verbose mode and with looking at the print-output::
+
+    $ py.test -v -s test_module.py
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.3 -- /home/hpk/p/pytest/.tox/regen/bin/python
+    collecting ... collected 8 items
+    
+    test_module.py:16: test_0[1] PASSED
+    test_module.py:16: test_0[2] PASSED
+    test_module.py:18: test_1[mod1] PASSED
+    test_module.py:20: test_2[1-mod1] PASSED
+    test_module.py:20: test_2[2-mod1] PASSED
+    test_module.py:18: test_1[mod2] PASSED
+    test_module.py:20: test_2[1-mod2] PASSED
+    test_module.py:20: test_2[2-mod2] PASSED
+    
+    ========================= 8 passed in 0.01 seconds =========================
+      test0 1
+      test0 2
+    create mod1
+      test1 mod1
+      test2 1 mod1
+      test2 2 mod1
+    fin mod1
+    create mod2
+      test1 mod2
+      test2 1 mod2
+      test2 2 mod2
+    fin mod2
+
+You can see that the parametrized module-scoped ``modarg`` resource caused
+an ordering of test execution that lead to the fewest possible "active" resources. The finalizer for the ``mod1`` parametrized resource was executed 
+before the ``mod2`` resource was setup.
+
+.. _`usefixtures`:
+
+
+using fixtures from classes, modules or projects
+----------------------------------------------------------------------
+
+.. regendoc:wipe
+
+Sometimes test functions do not directly need access to a fixture object.
+For example, tests may require to operate with an empty directory as the
+current working directory but otherwise do not care for the concrete
+directory.  Here is how you can can use the standard `tempfile
+<http://docs.python.org/library/tempfile.html>`_ and pytest fixtures to
+achieve it.  We separate the creation of the fixture into a conftest.py
+file::
+
+    # content of conftest.py
+    
+    import pytest
+    import tempfile
+    import os
+
+    @pytest.fixture()
+    def cleandir():
+        newpath = tempfile.mkdtemp()
+        os.chdir(newpath)
+
+and declare its use in a test module via a ``usefixtures`` marker::
+
+    # content of test_setenv.py
+    import os
+    import pytest
+
+    @pytest.mark.usefixtures("cleandir")
+    class TestDirectoryInit:
+        def test_cwd_starts_empty(self):
+            assert os.listdir(os.getcwd()) == []
+            with open("myfile", "w") as f:
+                f.write("hello")
+
+        def test_cwd_again_starts_empty(self):
+            assert os.listdir(os.getcwd()) == []
+
+Due to the ``usefixtures`` marker, the ``cleandir`` fixture
+will be required for the execution of each test method, just as if
+you specified a "cleandir" function argument to each of them.  Let's run it
+to verify our fixture is activated and the tests pass::
+
+    $ py.test -q
+    ..
+
+You can specify multiple fixtures like this::
+
+    @pytest.mark.usefixtures("cleandir", "anotherfixture")
+
+and you may specify fixture usage at the test module level, using 
+a generic feature of the mark mechanism::
+
+    pytestmark = pytest.mark.usefixtures("cleandir")
+
+Lastly you can put fixtures required by all tests in your project 
+into an ini-file::
+
+    # content of pytest.ini
+
+    [pytest]
+    usefixtures = cleandir
+
+
+.. _`autouse fixtures`:
+
+autouse fixtures (xUnit setup on steroids)
+----------------------------------------------------------------------
+
+.. regendoc:wipe
+
+Occasionally, you may want to have fixtures get invoked automatically
+without a `usefixtures`_ or `funcargs`_ reference.   As a practical 
+example, suppose we have a database fixture which has a
+begin/rollback/commit architecture and we want to automatically surround
+each test method by a transaction and a rollback.  Here is a dummy
+self-contained implementation of this idea::
+
+    # content of test_db_transact.py
+    
+    import pytest
+
+    class DB:
+        def __init__(self):
+            self.intransaction = []
+        def begin(self, name):
+            self.intransaction.append(name)
+        def rollback(self):
+            self.intransaction.pop()
+
+    @pytest.fixture(scope="module")
+    def db():
+        return DB()
+
+    class TestClass:
+        @pytest.fixture(autouse=True)
+        def transact(self, request, db):
+            db.begin(request.function.__name__)
+            request.addfinalizer(db.rollback)
+
+        def test_method1(self, db):
+            assert db.intransaction == ["test_method1"]
+
+        def test_method2(self, db):
+            assert db.intransaction == ["test_method2"]
+
+The class-level ``transact`` fixture is marked with *autouse=true*
+which implies that all test methods in the class will use this fixture
+without a need to state it in the test function signature or with a
+class-level ``usefixtures`` decorator.
+
+If we run it, we get two passing tests::
+
+    $ py.test -q
+    ..
+
+Here is how autouse fixtures work in other scopes:
+
+- if an autouse fixture is defined in a test module, all its test 
+  functions automatically use it.  
+
+- if an autouse fixture is defined in a conftest.py file then all tests in 
+  all test modules belows its directory will invoke the fixture.  
+
+- lastly, and **please use that with care**: if you define an autouse
+  fixture in a plugin, it will be invoked for all tests in all projects
+  where the plugin is installed.  This can be useful if a fixture only
+  anyway works in the presence of certain settings e. g. in the ini-file.  Such
+  a global fixture should always quickly determine if it should do
+  any work and avoid expensive imports or computation otherwise.
+
+Note that the above ``transact`` fixture may very well be a fixture that
+you want to make available in your project without having it generally
+active.  The canonical way to do that is to put the transact definition 
+into a conftest.py file **without** using ``autouse``::
+
+    # content of conftest.py
+    @pytest.fixture()
+    def transact(self, request, db):
+        db.begin()
+        request.addfinalizer(db.rollback)
+
+and then e.g. have a TestClass using it by declaring the need::
+
+    @pytest.mark.usefixtures("transact")
+    class TestClass:
+        def test_method1(self):
+            ...
+
+All test methods in this TestClass will use the transaction fixture while
+other test classes or functions in the module will not use it unless 
+they also add a ``transact`` reference.
+
+Shifting (visibility of) fixture functions
+----------------------------------------------------
+
+If during implementing your tests you realize that you
+want to use a fixture function from multiple test files you can move it
+to a :ref:`conftest.py <conftest.py>` file or even separately installable
+:ref:`plugins <plugins>` without changing test code.  The discovery of
+fixtures functions starts at test classes, then test modules, then
+``conftest.py`` files and finally builtin and third party plugins.
+

doc/en/funcarg_compare.txt

@@ -0,0 +1,217 @@
+
+.. _`funcargcompare`:
+
+pytest-2.3: reasoning for fixture/funcarg evolution
+=============================================================
+
+**Target audience**: Reading this document requires basic knowledge of 
+python testing, xUnit setup methods and the (previous) basic pytest 
+funcarg mechanism, see http://pytest.org/2.2.4/funcargs.html 
+If you are new to pytest, then you can simply ignore this
+section and read the other sections.
+
+.. currentmodule:: _pytest
+
+Shortcomings of the previous ``pytest_funcarg__`` mechanism
+--------------------------------------------------------------
+
+The pre pytest-2.3 funcarg mechanism calls a factory each time a
+funcarg for a test function is required.  If a factory wants to
+re-use a resource across different scopes, it often used 
+the ``request.cached_setup()`` helper to manage caching of 
+resources.  Here is a basic example how we could implement 
+a per-session Database object::
+
+    # content of conftest.py 
+    class Database:
+        def __init__(self):
+            print ("database instance created")
+        def destroy(self):
+            print ("database instance destroyed")
+
+    def pytest_funcarg__db(request):
+        return request.cached_setup(setup=DataBase, 
+                                    teardown=lambda db: db.destroy,
+                                    scope="session")
+
+There are several limitations and difficulties with this approach:
+
+1. Scoping funcarg resource creation is not straight forward, instead one must
+   understand the intricate cached_setup() method mechanics.
+
+2. parametrizing the "db" resource is not straight forward: 
+   you need to apply a "parametrize" decorator or implement a
+   :py:func:`~hookspec.pytest_generate_tests` hook 
+   calling :py:func:`~python.Metafunc.parametrize` which
+   performs parametrization at the places where the resource 
+   is used.  Moreover, you need to modify the factory to use an 
+   ``extrakey`` parameter containing ``request.param`` to the 
+   :py:func:`~python.Request.cached_setup` call.
+
+3. Multiple parametrized session-scoped resources will be active
+   at the same time, making it hard for them to affect global state
+   of the application under test.
+
+4. there is no way how you can make use of funcarg factories
+   in xUnit setup methods.
+
+5. A non-parametrized fixture function cannot use a parametrized 
+   funcarg resource if it isn't stated in the test function signature.
+
+All of these limitations are addressed with pytest-2.3 and its
+improved :ref:`fixture mechanism <fixture>`.
+
+
+Direct scoping of fixture/funcarg factories
+--------------------------------------------------------
+
+Instead of calling cached_setup() with a cache scope, you can use the
+:ref:`@pytest.fixture <pytest.fixture>` decorator and directly state
+the scope::
+
+    @pytest.fixture(scope="session")
+    def db(request):
+        # factory will only be invoked once per session - 
+        db = DataBase()
+        request.addfinalizer(db.destroy)  # destroy when session is finished
+        return db
+
+This factory implementation does not need to call ``cached_setup()`` anymore
+because it will only be invoked once per session.  Moreover, the 
+``request.addfinalizer()`` registers a finalizer according to the specified
+resource scope on which the factory function is operating.
+
+
+Direct parametrization of funcarg resource factories 
+----------------------------------------------------------
+
+Previously, funcarg factories could not directly cause parametrization.
+You needed to specify a ``@parametrize`` decorator on your test function
+or implement a ``pytest_generate_tests`` hook to perform
+parametrization, i.e. calling a test multiple times with different value
+sets.  pytest-2.3 introduces a decorator for use on the factory itself::
+
+    @pytest.fixture(params=["mysql", "pg"])
+    def db(request):
+        ... # use request.param
+
+Here the factory will be invoked twice (with the respective "mysql" 
+and "pg" values set as ``request.param`` attributes) and and all of 
+the tests requiring "db" will run twice as well.  The "mysql" and 
+"pg" values will also be used for reporting the test-invocation variants.
+
+This new way of parametrizing funcarg factories should in many cases
+allow to re-use already written factories because effectively
+``request.param`` was already used when test functions/classes were
+parametrized via
+:py:func:`~_pytest.python.Metafunc.parametrize(indirect=True)` calls.
+
+Of course it's perfectly fine to combine parametrization and scoping::
+
+    @pytest.fixture(scope="session", params=["mysql", "pg"])
+    def db(request):
+        if request.param == "mysql":
+            db = MySQL()
+        elif request.param == "pg":
+            db = PG()
+        request.addfinalizer(db.destroy)  # destroy when session is finished
+        return db
+
+This would execute all tests requiring the per-session "db" resource twice,
+receiving the values created by the two respective invocations to the
+factory function.
+
+
+No ``pytest_funcarg__`` prefix when using @fixture decorator
+-------------------------------------------------------------------
+
+When using the ``@fixture`` decorator the name of the function
+denotes the name under which the resource can be accessed as a function
+argument::
+
+    @pytest.fixture()
+    def db(request):
+        ...
+
+The name under which the funcarg resource can be requested is ``db``.
+
+You can still use the "old" non-decorator way of specifying funcarg factories 
+aka::
+
+    def pytest_funcarg__db(request):
+        ...
+
+
+But it is then not possible to define scoping and parametrization.
+It is thus recommended to use the factory decorator.
+
+
+solving per-session setup / autouse fixtures
+--------------------------------------------------------------
+
+pytest for a long time offered a pytest_configure and a pytest_sessionstart
+hook which are often used to setup global resources.  This suffers from
+several problems:
+
+1. in distributed testing the master process would setup test resources
+   that are never needed because it only co-ordinates the test run
+   activities of the slave processes.  
+
+2. if you only perform a collection (with "--collectonly") 
+   resource-setup will still be executed.  
+
+3. If a pytest_sessionstart is contained in some subdirectories
+   conftest.py file, it will not be called.  This stems from the
+   fact that this hook is actually used for reporting, in particular
+   the test-header with platform/custom information.
+
+Moreover, it was not easy to define a scoped setup from plugins or
+conftest files other than to implement a ``pytest_runtest_setup()`` hook
+and caring for scoping/caching yourself.  And it's virtually impossible
+to do this with parametrization as ``pytest_runtest_setup()`` is called
+during test execution and parametrization happens at collection time.
+
+It follows that pytest_configure/session/runtest_setup are often not
+appropriate for implementing common fixture needs.  Therefore, 
+pytest-2.3 introduces :ref:`autouse fixtures` which fully
+integrate with the generic :ref:`fixture mechanism <fixture>` 
+and obsolete many prior uses of pytest hooks.
+
+funcargs/fixture discovery now happens at collection time
+---------------------------------------------------------------------
+
+pytest-2.3 takes care to discover fixture/funcarg factories
+at collection time.  This is more efficient especially for large test suites. 
+Moreover, a call to "py.test --collectonly" should be able to in the future
+show a lot of setup-information and thus presents a nice method to get an
+overview of fixture management in your project.
+
+.. _`compatibility notes`:
+
+.. _`funcargscompat`:
+
+Conclusion and compatibility notes
+---------------------------------------------------------
+
+**funcargs** were originally introduced to pytest-2.0.  In pytest-2.3 
+the mechanism was extended and refined and is now described as
+fixtures:
+
+* previously funcarg factories were specified with a special 
+  ``pytest_funcarg__NAME`` prefix instead of using the 
+  ``@pytest.fixture`` decorator.
+
+* Factories received a ``request`` object which managed caching through
+  ``request.cached_setup()`` calls and allowed using other funcargs via 
+  ``request.getfuncargvalue()`` calls.  These intricate APIs made it hard 
+  to do proper parametrization and implement resource caching. The
+  new :py:func:`pytest.fixture`` decorator allows to declare the scope
+  and let pytest figure things out for you.
+
+* if you used parametrization and funcarg factories which made use of
+  ``request.cached_setup()`` it is recommeneded to invest a few minutes
+  and simplify your fixture function code to use the :ref:`@pytest.fixture`
+  decorator instead.  This will also allow to take advantage of 
+  the automatic per-resource grouping of tests.
+
+