From 024df6e00ba1d44cabc965fec86cbbdb8decf66b Mon Sep 17 00:00:00 2001 From: holger krekel Date: Fri, 19 Oct 2012 10:07:11 +0200 Subject: [PATCH] some more finalization of docs --- CHANGELOG | 15 +- _pytest/__init__.py | 2 +- _pytest/python.py | 6 +- doc/en/announce/release-2.3.0.txt | 1147 ++++++++++++++++++++++++++++- doc/en/conf.py | 2 +- doc/en/contents.txt | 2 +- doc/en/unittest.txt | 65 +- setup.py | 2 +- tox.ini | 2 +- 9 files changed, 1188 insertions(+), 55 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index ecdc3004d..24ea1d87b 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,17 +1,15 @@ Changes between 2.2.4 and 2.3.0.dev ----------------------------------- +- 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 a generic "markers" object on Nodes and a request.node - attribute pointing to the scope-specific collection node of a request. - node.markers allows reading and manipulating of MarkInfo objects - previously attached with @pytest.mark.* or request.applymarker or - setattr(node.markers, name, pytest.mark.*) calls. - 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 @@ -22,9 +20,6 @@ Changes between 2.2.4 and 2.3.0.dev 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 -- fix issue139 - introduce @pytest.factory which allows direct scoping - and parametrization of funcarg factories. Introduce new @pytest.setup - marker to allow the writing of setup functions which accept funcargs. - 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 @@ -48,6 +43,10 @@ Changes between 2.2.4 and 2.3.0.dev 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 diff --git a/_pytest/__init__.py b/_pytest/__init__.py index 05f795aa8..7a2224b6b 100644 --- a/_pytest/__init__.py +++ b/_pytest/__init__.py @@ -1,2 +1,2 @@ # -__version__ = '2.3.0.dev30' +__version__ = '2.3.0.dev31' diff --git a/_pytest/python.py b/_pytest/python.py index 9c3091a7f..808ff487e 100644 --- a/_pytest/python.py +++ b/_pytest/python.py @@ -10,6 +10,8 @@ from py._code.code import TerminalRepr import _pytest cutdir = py.path.local(_pytest.__file__).dirpath() +callable = py.builtin.callable + class FixtureFunctionMarker: def __init__(self, scope, params, autouse=False): self.scope = scope @@ -45,7 +47,7 @@ def fixture(scope="function", params=None, autouse=False): can see it. If False (the default) then an explicit reference is needed to activate the fixture. """ - if py.builtin.callable(scope) and params is None and autouse == False: + if callable(scope) and params is None and autouse == False: # direct decoration return FixtureFunctionMarker("function", params, autouse)(scope) else: @@ -474,7 +476,7 @@ class Generator(FunctionMixin, PyCollector): seen = {} for i, x in enumerate(self.obj()): name, call, args = self.getcallargs(x) - if not py.builtin.callable(call): + if not callable(call): raise TypeError("%r yielded non callable test %r" %(self.obj, call,)) if name is None: name = "[%d]" % i diff --git a/doc/en/announce/release-2.3.0.txt b/doc/en/announce/release-2.3.0.txt index 46298092d..edc5b51b4 100644 --- a/doc/en/announce/release-2.3.0.txt +++ b/doc/en/announce/release-2.3.0.txt @@ -1,22 +1,32 @@ -pytest-2.3: generalized fixtures/funcarg mechanism +pytest-2.3: improved fixtures / better unittest integration ============================================================================= -pytest is a popular tool for writing automated tests in Python. Version -2.3 comes with several innovations for writing test fixtures -- -needed to provide a fixed base state or preinitialized objects -for your tests. For info and tutorial-style examples, see +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/dev/fixture.html -All changes are backward compatible and you should be able to continue -to run your existing test suites. In particular, dependency-injected -"funcargs" still form the base of the improved fixture system but it is -now easy to create parametrized funcargs/fixtures or cache them across -modules or test sessions. Moreover, there is now support for using -pytest fixtures with unittest-style suites, see here for example: +Moreover, there is now support for using pytest fixtures/funcargs with +unittest-style suites, see here for examples: http://pytest.org/dev/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 of the pytest-2.3 fixture evolution, please consult http://pytest.org/dev/funcarg_compare.html @@ -41,5 +51,1120 @@ have fun, holger krekel +Changes between 2.2.4 and 2.3.0.dev +----------------------------------- + +- 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 + +Changes between 2.2.3 and 2.2.4 +----------------------------------- + +- fix error message for rewritten assertions involving the % operator +- fix issue 126: correctly match all invalid xml characters for junitxml + binary escape +- fix issue with unittest: now @unittest.expectedFailure markers should + be processed correctly (you can also use @pytest.mark markers) +- document integration with the extended distribute/setuptools test commands +- fix issue 140: propperly get the real functions + of bound classmethods for setup/teardown_class +- fix issue #141: switch from the deceased paste.pocoo.org to bpaste.net +- fix issue #143: call unconfigure/sessionfinish always when + configure/sessionstart where called +- fix issue #144: better mangle test ids to junitxml classnames +- upgrade distribute_setup.py to 0.6.27 + +Changes between 2.2.2 and 2.2.3 +---------------------------------------- + +- fix uploaded package to only include neccesary files + +Changes between 2.2.1 and 2.2.2 +---------------------------------------- + +- fix issue101: wrong args to unittest.TestCase test function now + produce better output +- fix issue102: report more useful errors and hints for when a + test directory was renamed and some pyc/__pycache__ remain +- fix issue106: allow parametrize to be applied multiple times + e.g. from module, class and at function level. +- fix issue107: actually perform session scope finalization +- don't check in parametrize if indirect parameters are funcarg names +- add chdir method to monkeypatch funcarg +- fix crash resulting from calling monkeypatch undo a second time +- fix issue115: make --collectonly robust against early failure + (missing files/directories) +- "-qq --collectonly" now shows only files and the number of tests in them +- "-q --collectonly" now shows test ids +- allow adding of attributes to test reports such that it also works + with distributed testing (no upgrade of pytest-xdist needed) + +Changes between 2.2.0 and 2.2.1 +---------------------------------------- + +- fix issue99 (in pytest and py) internallerrors with resultlog now + produce better output - fixed by normalizing pytest_internalerror + input arguments. +- fix issue97 / traceback issues (in pytest and py) improve traceback output + in conjunction with jinja2 and cython which hack tracebacks +- fix issue93 (in pytest and pytest-xdist) avoid "delayed teardowns": + the final test in a test node will now run its teardown directly + instead of waiting for the end of the session. Thanks Dave Hunt for + the good reporting and feedback. The pytest_runtest_protocol as well + as the pytest_runtest_teardown hooks now have "nextitem" available + which will be None indicating the end of the test run. +- fix collection crash due to unknown-source collected items, thanks + to Ralf Schmitt (fixed by depending on a more recent pylib) + +Changes between 2.1.3 and 2.2.0 +---------------------------------------- + +- fix issue90: introduce eager tearing down of test items so that + teardown function are called earlier. +- add an all-powerful metafunc.parametrize function which allows to + parametrize test function arguments in multiple steps and therefore + from indepdenent plugins and palces. +- add a @pytest.mark.parametrize helper which allows to easily + call a test function with different argument values +- Add examples to the "parametrize" example page, including a quick port + of Test scenarios and the new parametrize function and decorator. +- introduce registration for "pytest.mark.*" helpers via ini-files + or through plugin hooks. Also introduce a "--strict" option which + will treat unregistered markers as errors + allowing to avoid typos and maintain a well described set of markers + for your test suite. See exaples at http://pytest.org/latest/mark.html + and its links. +- issue50: introduce "-m marker" option to select tests based on markers + (this is a stricter and more predictable version of '-k' in that "-m" + only matches complete markers and has more obvious rules for and/or + semantics. +- new feature to help optimizing the speed of your tests: + --durations=N option for displaying N slowest test calls + and setup/teardown methods. +- fix issue87: --pastebin now works with python3 +- fix issue89: --pdb with unexpected exceptions in doctest work more sensibly +- fix and cleanup pytest's own test suite to not leak FDs +- fix issue83: link to generated funcarg list +- fix issue74: pyarg module names are now checked against imp.find_module false positives +- fix compatibility with twisted/trial-11.1.0 use cases +- simplify Node.listchain +- simplify junitxml output code by relying on py.xml +- add support for skip properties on unittest classes and functions + +Changes between 2.1.2 and 2.1.3 +---------------------------------------- + +- fix issue79: assertion rewriting failed on some comparisons in boolops +- correctly handle zero length arguments (a la pytest '') +- fix issue67 / junitxml now contains correct test durations, thanks ronny +- fix issue75 / skipping test failure on jython +- fix issue77 / Allow assertrepr_compare hook to apply to a subset of tests + +Changes between 2.1.1 and 2.1.2 +---------------------------------------- + +- fix assertion rewriting on files with windows newlines on some Python versions +- refine test discovery by package/module name (--pyargs), thanks Florian Mayer +- fix issue69 / assertion rewriting fixed on some boolean operations +- fix issue68 / packages now work with assertion rewriting +- fix issue66: use different assertion rewriting caches when the -O option is passed +- don't try assertion rewriting on Jython, use reinterp + +Changes between 2.1.0 and 2.1.1 +---------------------------------------------- + +- fix issue64 / pytest.set_trace now works within pytest_generate_tests hooks +- fix issue60 / fix error conditions involving the creation of __pycache__ +- fix issue63 / assertion rewriting on inserts involving strings containing '%' +- fix assertion rewriting on calls with a ** arg +- don't cache rewritten modules if bytecode generation is disabled +- fix assertion rewriting in read-only directories +- fix issue59: provide system-out/err tags for junitxml output +- fix issue61: assertion rewriting on boolean operations with 3 or more operands +- you can now build a man page with "cd doc ; make man" + +Changes between 2.0.3 and 2.1.0.DEV +---------------------------------------------- + +- fix issue53 call nosestyle setup functions with correct ordering +- fix issue58 and issue59: new assertion code fixes +- merge Benjamin's assertionrewrite branch: now assertions + for test modules on python 2.6 and above are done by rewriting + the AST and saving the pyc file before the test module is imported. + see doc/assert.txt for more info. +- fix issue43: improve doctests with better traceback reporting on + unexpected exceptions +- fix issue47: timing output in junitxml for test cases is now correct +- fix issue48: typo in MarkInfo repr leading to exception +- fix issue49: avoid confusing error when initizaliation partially fails +- fix issue44: env/username expansion for junitxml file path +- show releaselevel information in test runs for pypy +- reworked doc pages for better navigation and PDF generation +- report KeyboardInterrupt even if interrupted during session startup +- fix issue 35 - provide PDF doc version and download link from index page + +Changes between 2.0.2 and 2.0.3 +---------------------------------------------- + +- fix issue38: nicer tracebacks on calls to hooks, particularly early + configure/sessionstart ones + +- fix missing skip reason/meta information in junitxml files, reported + via http://lists.idyll.org/pipermail/testing-in-python/2011-March/003928.html + +- fix issue34: avoid collection failure with "test" prefixed classes + deriving from object. + +- don't require zlib (and other libs) for genscript plugin without + --genscript actually being used. + +- speed up skips (by not doing a full traceback represenation + internally) + +- fix issue37: avoid invalid characters in junitxml's output + +Changes between 2.0.1 and 2.0.2 +---------------------------------------------- + +- tackle issue32 - speed up test runs of very quick test functions + by reducing the relative overhead + +- fix issue30 - extended xfail/skipif handling and improved reporting. + If you have a syntax error in your skip/xfail + expressions you now get nice error reports. + + Also you can now access module globals from xfail/skipif + expressions so that this for example works now:: + + import pytest + import mymodule + @pytest.mark.skipif("mymodule.__version__[0] == "1") + def test_function(): + pass + + This will not run the test function if the module's version string + does not start with a "1". Note that specifying a string instead + of a boolean expressions allows py.test to report meaningful information + when summarizing a test run as to what conditions lead to skipping + (or xfail-ing) tests. + +- fix issue28 - setup_method and pytest_generate_tests work together + The setup_method fixture method now gets called also for + test function invocations generated from the pytest_generate_tests + hook. + +- fix issue27 - collectonly and keyword-selection (-k) now work together + Also, if you do "py.test --collectonly -q" you now get a flat list + of test ids that you can use to paste to the py.test commandline + in order to execute a particular test. + +- fix issue25 avoid reported problems with --pdb and python3.2/encodings output + +- fix issue23 - tmpdir argument now works on Python3.2 and WindowsXP + Starting with Python3.2 os.symlink may be supported. By requiring + a newer py lib version the py.path.local() implementation acknowledges + this. + +- fixed typos in the docs (thanks Victor Garcia, Brianna Laugher) and particular + thanks to Laura Creighton who also revieved parts of the documentation. + +- fix slighly wrong output of verbose progress reporting for classes + (thanks Amaury) + +- more precise (avoiding of) deprecation warnings for node.Class|Function accesses + +- avoid std unittest assertion helper code in tracebacks (thanks Ronny) + +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. +- allow to omit "()" in test ids to allow for uniform test ids + as produced by Alfredo's nice pytest.vim 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/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 + parametraization remains the "pytest_generate_tests" + mechanism, see the docs. + +Changes between 1.3.4 and 2.0.0 +---------------------------------------------- + +- pytest-2.0 is now its own package and depends on pylib-2.0 +- new ability: python -m pytest / python -m pytest.main ability +- new python invcation: pytest.main(args, plugins) to load + some custom plugins early. +- try harder to run unittest test suites in a more compatible manner + by deferring setup/teardown semantics to the unittest package. + also work harder to run twisted/trial and Django tests which + should now basically work by default. +- introduce a new way to set config options via ini-style files, + by default setup.cfg and tox.ini files are searched. The old + ways (certain environment variables, dynamic conftest.py reading + is removed). +- add a new "-q" option which decreases verbosity and prints a more + nose/unittest-style "dot" output. +- fix issue135 - marks now work with unittest test cases as well +- fix issue126 - introduce py.test.set_trace() to trace execution via + PDB during the running of tests even if capturing is ongoing. +- fix issue123 - new "python -m py.test" invocation for py.test + (requires Python 2.5 or above) +- fix issue124 - make reporting more resilient against tests opening + files on filedescriptor 1 (stdout). +- fix issue109 - sibling conftest.py files will not be loaded. + (and Directory collectors cannot be customized anymore from a Directory's + conftest.py - this needs to happen at least one level up). +- introduce (customizable) assertion failure representations and enhance + output on assertion failures for comparisons and other cases (Floris Bruynooghe) +- nose-plugin: pass through type-signature failures in setup/teardown + functions instead of not calling them (Ed Singleton) +- remove py.test.collect.Directory (follows from a major refactoring + and simplification of the collection process) +- majorly reduce py.test core code, shift function/python testing to own plugin +- fix issue88 (finding custom test nodes from command line arg) +- refine 'tmpdir' creation, will now create basenames better associated + with test names (thanks Ronny) +- "xpass" (unexpected pass) tests don't cause exitcode!=0 +- fix issue131 / issue60 - importing doctests in __init__ files used as namespace packages +- fix issue93 stdout/stderr is captured while importing conftest.py +- fix bug: unittest collected functions now also can have "pytestmark" + applied at class/module level +- add ability to use "class" level for cached_setup helper +- fix strangeness: mark.* objects are now immutable, create new instances + +Changes between 1.3.3 and 1.3.4 +---------------------------------------------- + +- fix issue111: improve install documentation for windows +- fix issue119: fix custom collectability of __init__.py as a module +- fix issue116: --doctestmodules work with __init__.py files as well +- fix issue115: unify internal exception passthrough/catching/GeneratorExit +- fix issue118: new --tb=native for presenting cpython-standard exceptions + +Changes between 1.3.2 and 1.3.3 +---------------------------------------------- + +- fix issue113: assertion representation problem with triple-quoted strings + (and possibly other cases) +- make conftest loading detect that a conftest file with the same + content was already loaded, avoids surprises in nested directory structures + which can be produced e.g. by Hudson. It probably removes the need to use + --confcutdir in most cases. +- fix terminal coloring for win32 + (thanks Michael Foord for reporting) +- fix weirdness: make terminal width detection work on stdout instead of stdin + (thanks Armin Ronacher for reporting) +- remove trailing whitespace in all py/text distribution files + +Changes between 1.3.1 and 1.3.2 +---------------------------------------------- + +New features +++++++++++++++++++ + +- fix issue103: introduce py.test.raises as context manager, examples:: + + with py.test.raises(ZeroDivisionError): + x = 0 + 1 / x + + with py.test.raises(RuntimeError) as excinfo: + call_something() + + # you may do extra checks on excinfo.value|type|traceback here + + (thanks Ronny Pfannschmidt) + +- Funcarg factories can now dynamically apply a marker to a + test invocation. This is for example useful if a factory + provides parameters to a test which are expected-to-fail:: + + def pytest_funcarg__arg(request): + request.applymarker(py.test.mark.xfail(reason="flaky config")) + ... + + def test_function(arg): + ... + +- improved error reporting on collection and import errors. This makes + use of a more general mechanism, namely that for custom test item/collect + nodes ``node.repr_failure(excinfo)`` is now uniformly called so that you can + override it to return a string error representation of your choice + which is going to be reported as a (red) string. + +- introduce '--junitprefix=STR' option to prepend a prefix + to all reports in the junitxml file. + +Bug fixes / Maintenance +++++++++++++++++++++++++++ + +- make tests and the ``pytest_recwarn`` plugin in particular fully compatible + to Python2.7 (if you use the ``recwarn`` funcarg warnings will be enabled so that + you can properly check for their existence in a cross-python manner). +- refine --pdb: ignore xfailed tests, unify its TB-reporting and + don't display failures again at the end. +- fix assertion interpretation with the ** operator (thanks Benjamin Peterson) +- fix issue105 assignment on the same line as a failing assertion (thanks Benjamin Peterson) +- fix issue104 proper escaping for test names in junitxml plugin (thanks anonymous) +- fix issue57 -f|--looponfail to work with xpassing tests (thanks Ronny) +- fix issue92 collectonly reporter and --pastebin (thanks Benjamin Peterson) +- fix py.code.compile(source) to generate unique filenames +- fix assertion re-interp problems on PyPy, by defering code + compilation to the (overridable) Frame.eval class. (thanks Amaury Forgeot) +- fix py.path.local.pyimport() to work with directories +- streamline py.path.local.mkdtemp implementation and usage +- don't print empty lines when showing junitxml-filename +- add optional boolean ignore_errors parameter to py.path.local.remove +- fix terminal writing on win32/python2.4 +- py.process.cmdexec() now tries harder to return properly encoded unicode objects + on all python versions +- install plain py.test/py.which scripts also for Jython, this helps to + get canonical script paths in virtualenv situations +- make path.bestrelpath(path) return ".", note that when calling + X.bestrelpath the assumption is that X is a directory. +- make initial conftest discovery ignore "--" prefixed arguments +- fix resultlog plugin when used in an multicpu/multihost xdist situation + (thanks Jakub Gustak) +- perform distributed testing related reporting in the xdist-plugin + rather than having dist-related code in the generic py.test + distribution +- fix homedir detection on Windows +- ship distribute_setup.py version 0.6.13 + +Changes between 1.3.0 and 1.3.1 +--------------------------------------------- + +New features +++++++++++++++++++ + +- issue91: introduce new py.test.xfail(reason) helper + to imperatively mark a test as expected to fail. Can + be used from within setup and test functions. This is + useful especially for parametrized tests when certain + configurations are expected-to-fail. In this case the + declarative approach with the @py.test.mark.xfail cannot + be used as it would mark all configurations as xfail. + +- issue102: introduce new --maxfail=NUM option to stop + test runs after NUM failures. This is a generalization + of the '-x' or '--exitfirst' option which is now equivalent + to '--maxfail=1'. Both '-x' and '--maxfail' will + now also print a line near the end indicating the Interruption. + +- issue89: allow py.test.mark decorators to be used on classes + (class decorators were introduced with python2.6) and + also allow to have multiple markers applied at class/module level + by specifying a list. + +- improve and refine letter reporting in the progress bar: + . pass + f failed test + s skipped tests (reminder: use for dependency/platform mismatch only) + x xfailed test (test that was expected to fail) + X xpassed test (test that was expected to fail but passed) + + You can use any combination of 'fsxX' with the '-r' extended + reporting option. The xfail/xpass results will show up as + skipped tests in the junitxml output - which also fixes + issue99. + +- make py.test.cmdline.main() return the exitstatus instead of raising + SystemExit and also allow it to be called multiple times. This of + course requires that your application and tests are properly teared + down and don't have global state. + +Fixes / Maintenance +++++++++++++++++++++++ + +- improved traceback presentation: + - improved and unified reporting for "--tb=short" option + - Errors during test module imports are much shorter, (using --tb=short style) + - raises shows shorter more relevant tracebacks + - --fulltrace now more systematically makes traces longer / inhibits cutting + +- improve support for raises and other dynamically compiled code by + manipulating python's linecache.cache instead of the previous + rather hacky way of creating custom code objects. This makes + it seemlessly work on Jython and PyPy where it previously didn't. + +- fix issue96: make capturing more resilient against Control-C + interruptions (involved somewhat substantial refactoring + to the underlying capturing functionality to avoid race + conditions). + +- fix chaining of conditional skipif/xfail decorators - so it works now + as expected to use multiple @py.test.mark.skipif(condition) decorators, + including specific reporting which of the conditions lead to skipping. + +- fix issue95: late-import zlib so that it's not required + for general py.test startup. + +- fix issue94: make reporting more robust against bogus source code + (and internally be more careful when presenting unexpected byte sequences) +Changes between 1.2.1 and 1.3.0 +--------------------------------------------- + +- deprecate --report option in favour of a new shorter and easier to + remember -r option: it takes a string argument consisting of any + combination of 'xfsX' characters. They relate to the single chars + you see during the dotted progress printing and will print an extra line + per test at the end of the test run. This extra line indicates the exact + position or test ID that you directly paste to the py.test cmdline in order + to re-run a particular test. + +- allow external plugins to register new hooks via the new + pytest_addhooks(pluginmanager) hook. The new release of + the pytest-xdist plugin for distributed and looponfailing + testing requires this feature. + +- add a new pytest_ignore_collect(path, config) hook to allow projects and + plugins to define exclusion behaviour for their directory structure - + for example you may define in a conftest.py this method:: + + def pytest_ignore_collect(path): + return path.check(link=1) + + to prevent even a collection try of any tests in symlinked dirs. + +- new pytest_pycollect_makemodule(path, parent) hook for + allowing customization of the Module collection object for a + matching test module. + +- extend and refine xfail mechanism: + ``@py.test.mark.xfail(run=False)`` do not run the decorated test + ``@py.test.mark.xfail(reason="...")`` prints the reason string in xfail summaries + specifiying ``--runxfail`` on command line virtually ignores xfail markers + +- expose (previously internal) commonly useful methods: + py.io.get_terminal_with() -> return terminal width + py.io.ansi_print(...) -> print colored/bold text on linux/win32 + py.io.saferepr(obj) -> return limited representation string + +- expose test outcome related exceptions as py.test.skip.Exception, + py.test.raises.Exception etc., useful mostly for plugins + doing special outcome interpretation/tweaking + +- (issue85) fix junitxml plugin to handle tests with non-ascii output + +- fix/refine python3 compatibility (thanks Benjamin Peterson) + +- fixes for making the jython/win32 combination work, note however: + jython2.5.1/win32 does not provide a command line launcher, see + http://bugs.jython.org/issue1491 . See pylib install documentation + for how to work around. + +- fixes for handling of unicode exception values and unprintable objects + +- (issue87) fix unboundlocal error in assertionold code + +- (issue86) improve documentation for looponfailing + +- refine IO capturing: stdin-redirect pseudo-file now has a NOP close() method + +- ship distribute_setup.py version 0.6.10 + +- added links to the new capturelog and coverage plugins + + +Changes between 1.2.1 and 1.2.0 +--------------------------------------------- + +- refined usage and options for "py.cleanup":: + + py.cleanup # remove "*.pyc" and "*$py.class" (jython) files + py.cleanup -e .swp -e .cache # also remove files with these extensions + py.cleanup -s # remove "build" and "dist" directory next to setup.py files + py.cleanup -d # also remove empty directories + py.cleanup -a # synonym for "-s -d -e 'pip-log.txt'" + py.cleanup -n # dry run, only show what would be removed + +- add a new option "py.test --funcargs" which shows available funcargs + and their help strings (docstrings on their respective factory function) + for a given test path + +- display a short and concise traceback if a funcarg lookup fails + +- early-load "conftest.py" files in non-dot first-level sub directories. + allows to conveniently keep and access test-related options in a ``test`` + subdir and still add command line options. + +- fix issue67: new super-short traceback-printing option: "--tb=line" will print a single line for each failing (python) test indicating its filename, lineno and the failure value + +- fix issue78: always call python-level teardown functions even if the + according setup failed. This includes refinements for calling setup_module/class functions + which will now only be called once instead of the previous behaviour where they'd be called + multiple times if they raise an exception (including a Skipped exception). Any exception + will be re-corded and associated with all tests in the according module/class scope. + +- fix issue63: assume <40 columns to be a bogus terminal width, default to 80 + +- fix pdb debugging to be in the correct frame on raises-related errors + +- update apipkg.py to fix an issue where recursive imports might + unnecessarily break importing + +- fix plugin links + +Changes between 1.2 and 1.1.1 +--------------------------------------------- + +- moved dist/looponfailing from py.test core into a new + separately released pytest-xdist plugin. + +- new junitxml plugin: --junitxml=path will generate a junit style xml file + which is processable e.g. by the Hudson CI system. + +- new option: --genscript=path will generate a standalone py.test script + which will not need any libraries installed. thanks to Ralf Schmitt. + +- new option: --ignore will prevent specified path from collection. + Can be specified multiple times. + +- new option: --confcutdir=dir will make py.test only consider conftest + files that are relative to the specified dir. + +- new funcarg: "pytestconfig" is the pytest config object for access + to command line args and can now be easily used in a test. + +- install 'py.test' and `py.which` with a ``-$VERSION`` suffix to + disambiguate between Python3, python2.X, Jython and PyPy installed versions. + +- new "pytestconfig" funcarg allows access to test config object + +- new "pytest_report_header" hook can return additional lines + to be displayed at the header of a test run. + +- (experimental) allow "py.test path::name1::name2::..." for pointing + to a test within a test collection directly. This might eventually + evolve as a full substitute to "-k" specifications. + +- streamlined plugin loading: order is now as documented in + customize.html: setuptools, ENV, commandline, conftest. + also setuptools entry point names are turned to canonical namees ("pytest_*") + +- automatically skip tests that need 'capfd' but have no os.dup + +- allow pytest_generate_tests to be defined in classes as well + +- deprecate usage of 'disabled' attribute in favour of pytestmark +- deprecate definition of Directory, Module, Class and Function nodes + in conftest.py files. Use pytest collect hooks instead. + +- collection/item node specific runtest/collect hooks are only called exactly + on matching conftest.py files, i.e. ones which are exactly below + the filesystem path of an item + +- change: the first pytest_collect_directory hook to return something + will now prevent further hooks to be called. + +- change: figleaf plugin now requires --figleaf to run. Also + change its long command line options to be a bit shorter (see py.test -h). + +- change: pytest doctest plugin is now enabled by default and has a + new option --doctest-glob to set a pattern for file matches. + +- change: remove internal py._* helper vars, only keep py._pydir + +- robustify capturing to survive if custom pytest_runtest_setup + code failed and prevented the capturing setup code from running. + +- make py.test.* helpers provided by default plugins visible early - + works transparently both for pydoc and for interactive sessions + which will regularly see e.g. py.test.mark and py.test.importorskip. + +- simplify internal plugin manager machinery +- simplify internal collection tree by introducing a RootCollector node + +- fix assert reinterpreation that sees a call containing "keyword=..." + +- fix issue66: invoke pytest_sessionstart and pytest_sessionfinish + hooks on slaves during dist-testing, report module/session teardown + hooks correctly. + +- fix issue65: properly handle dist-testing if no + execnet/py lib installed remotely. + +- skip some install-tests if no execnet is available + +- fix docs, fix internal bin/ script generation + + +Changes between 1.1.1 and 1.1.0 +--------------------------------------------- + +- introduce automatic plugin registration via 'pytest11' + entrypoints via setuptools' pkg_resources.iter_entry_points + +- fix py.test dist-testing to work with execnet >= 1.0.0b4 + +- re-introduce py.test.cmdline.main() for better backward compatibility + +- svn paths: fix a bug with path.check(versioned=True) for svn paths, + allow '%' in svn paths, make svnwc.update() default to interactive mode + like in 1.0.x and add svnwc.update(interactive=False) to inhibit interaction. + +- refine distributed tarball to contain test and no pyc files + +- try harder to have deprecation warnings for py.compat.* accesses + report a correct location + +Changes between 1.1.0 and 1.0.2 +--------------------------------------------- + +* adjust and improve docs + +* remove py.rest tool and internal namespace - it was + never really advertised and can still be used with + the old release if needed. If there is interest + it could be revived into its own tool i guess. + +* fix issue48 and issue59: raise an Error if the module + from an imported test file does not seem to come from + the filepath - avoids "same-name" confusion that has + been reported repeatedly + +* merged Ronny's nose-compatibility hacks: now + nose-style setup_module() and setup() functions are + supported + +* introduce generalized py.test.mark function marking + +* reshuffle / refine command line grouping + +* deprecate parser.addgroup in favour of getgroup which creates option group + +* add --report command line option that allows to control showing of skipped/xfailed sections + +* generalized skipping: a new way to mark python functions with skipif or xfail + at function, class and modules level based on platform or sys-module attributes. + +* extend py.test.mark decorator to allow for positional args + +* introduce and test "py.cleanup -d" to remove empty directories + +* fix issue #59 - robustify unittest test collection + +* make bpython/help interaction work by adding an __all__ attribute + to ApiModule, cleanup initpkg + +* use MIT license for pylib, add some contributors + +* remove py.execnet code and substitute all usages with 'execnet' proper + +* fix issue50 - cached_setup now caches more to expectations + for test functions with multiple arguments. + +* merge Jarko's fixes, issue #45 and #46 + +* add the ability to specify a path for py.lookup to search in + +* fix a funcarg cached_setup bug probably only occuring + in distributed testing and "module" scope with teardown. + +* many fixes and changes for making the code base python3 compatible, + many thanks to Benjamin Peterson for helping with this. + +* consolidate builtins implementation to be compatible with >=2.3, + add helpers to ease keeping 2 and 3k compatible code + +* deprecate py.compat.doctest|subprocess|textwrap|optparse + +* deprecate py.magic.autopath, remove py/magic directory + +* move pytest assertion handling to py/code and a pytest_assertion + plugin, add "--no-assert" option, deprecate py.magic namespaces + in favour of (less) py.code ones. + +* consolidate and cleanup py/code classes and files + +* cleanup py/misc, move tests to bin-for-dist + +* introduce delattr/delitem/delenv methods to py.test's monkeypatch funcarg + +* consolidate py.log implementation, remove old approach. + +* introduce py.io.TextIO and py.io.BytesIO for distinguishing between + text/unicode and byte-streams (uses underlying standard lib io.* + if available) + +* make py.unittest_convert helper script available which converts "unittest.py" + style files into the simpler assert/direct-test-classes py.test/nosetests + style. The script was written by Laura Creighton. + +* simplified internal localpath implementation + +Changes between 1.0.1 and 1.0.2 +------------------------------------------- + +* fixing packaging issues, triggered by fedora redhat packaging, + also added doc, examples and contrib dirs to the tarball. + +* added a documentation link to the new django plugin. + +Changes between 1.0.0 and 1.0.1 +------------------------------------------- + +* added a 'pytest_nose' plugin which handles nose.SkipTest, + nose-style function/method/generator setup/teardown and + tries to report functions correctly. + +* capturing of unicode writes or encoded strings to sys.stdout/err + work better, also terminalwriting was adapted and somewhat + unified between windows and linux. + +* improved documentation layout and content a lot + +* added a "--help-config" option to show conftest.py / ENV-var names for + all longopt cmdline options, and some special conftest.py variables. + renamed 'conf_capture' conftest setting to 'option_capture' accordingly. + +* fix issue #27: better reporting on non-collectable items given on commandline + (e.g. pyc files) + +* fix issue #33: added --version flag (thanks Benjamin Peterson) + +* fix issue #32: adding support for "incomplete" paths to wcpath.status() + +* "Test" prefixed classes are *not* collected by default anymore if they + have an __init__ method + +* monkeypatch setenv() now accepts a "prepend" parameter + +* improved reporting of collection error tracebacks + +* simplified multicall mechanism and plugin architecture, + renamed some internal methods and argnames + +Changes between 1.0.0b9 and 1.0.0 +------------------------------------------- + +* more terse reporting try to show filesystem path relatively to current dir +* improve xfail output a bit + +Changes between 1.0.0b8 and 1.0.0b9 +------------------------------------------- + +* cleanly handle and report final teardown of test setup + +* fix svn-1.6 compat issue with py.path.svnwc().versioned() + (thanks Wouter Vanden Hove) + +* setup/teardown or collection problems now show as ERRORs + or with big "E"'s in the progress lines. they are reported + and counted separately. + +* dist-testing: properly handle test items that get locally + collected but cannot be collected on the remote side - often + due to platform/dependency reasons + +* simplified py.test.mark API - see keyword plugin documentation + +* integrate better with logging: capturing now by default captures + test functions and their immediate setup/teardown in a single stream + +* capsys and capfd funcargs now have a readouterr() and a close() method + (underlyingly py.io.StdCapture/FD objects are used which grew a + readouterr() method as well to return snapshots of captured out/err) + +* make assert-reinterpretation work better with comparisons not + returning bools (reported with numpy from thanks maciej fijalkowski) + +* reworked per-test output capturing into the pytest_iocapture.py plugin + and thus removed capturing code from config object + +* item.repr_failure(excinfo) instead of item.repr_failure(excinfo, outerr) + + +Changes between 1.0.0b7 and 1.0.0b8 +------------------------------------------- + +* pytest_unittest-plugin is now enabled by default + +* introduced pytest_keyboardinterrupt hook and + refined pytest_sessionfinish hooked, added tests. + +* workaround a buggy logging module interaction ("closing already closed + files"). Thanks to Sridhar Ratnakumar for triggering. + +* if plugins use "py.test.importorskip" for importing + a dependency only a warning will be issued instead + of exiting the testing process. + +* many improvements to docs: + - refined funcargs doc , use the term "factory" instead of "provider" + - added a new talk/tutorial doc page + - better download page + - better plugin docstrings + - added new plugins page and automatic doc generation script + +* fixed teardown problem related to partially failing funcarg setups + (thanks MrTopf for reporting), "pytest_runtest_teardown" is now + always invoked even if the "pytest_runtest_setup" failed. + +* tweaked doctest output for docstrings in py modules, + thanks Radomir. + +Changes between 1.0.0b3 and 1.0.0b7 +------------------------------------------- + +* renamed py.test.xfail back to py.test.mark.xfail to avoid + two ways to decorate for xfail + +* re-added py.test.mark decorator for setting keywords on functions + (it was actually documented so removing it was not nice) + +* remove scope-argument from request.addfinalizer() because + request.cached_setup has the scope arg. TOOWTDI. + +* perform setup finalization before reporting failures + +* apply modified patches from Andreas Kloeckner to allow + test functions to have no func_code (#22) and to make + "-k" and function keywords work (#20) + +* apply patch from Daniel Peolzleithner (issue #23) + +* resolve issue #18, multiprocessing.Manager() and + redirection clash + +* make __name__ == "__channelexec__" for remote_exec code + +Changes between 1.0.0b1 and 1.0.0b3 +------------------------------------------- + +* plugin classes are removed: one now defines + hooks directly in conftest.py or global pytest_*.py + files. + +* added new pytest_namespace(config) hook that allows + to inject helpers directly to the py.test.* namespace. + +* documented and refined many hooks + +* added new style of generative tests via + pytest_generate_tests hook that integrates + well with function arguments. + + +Changes between 0.9.2 and 1.0.0b1 +------------------------------------------- + +* introduced new "funcarg" setup method, + see doc/test/funcarg.txt + +* introduced plugin architecuture and many + new py.test plugins, see + doc/test/plugins.txt + +* teardown_method is now guaranteed to get + called after a test method has run. + +* new method: py.test.importorskip(mod,minversion) + will either import or call py.test.skip() + +* completely revised internal py.test architecture + +* new py.process.ForkedFunc object allowing to + fork execution of a function to a sub process + and getting a result back. + +XXX lots of things missing here XXX + +Changes between 0.9.1 and 0.9.2 +------------------------------------------- + +* refined installation and metadata, created new setup.py, + now based on setuptools/ez_setup (thanks to Ralf Schmitt + for his support). + +* improved the way of making py.* scripts available in + windows environments, they are now added to the + Scripts directory as ".cmd" files. + +* py.path.svnwc.status() now is more complete and + uses xml output from the 'svn' command if available + (Guido Wesdorp) + +* fix for py.path.svn* to work with svn 1.5 + (Chris Lamb) + +* fix path.relto(otherpath) method on windows to + use normcase for checking if a path is relative. + +* py.test's traceback is better parseable from editors + (follows the filenames:LINENO: MSG convention) + (thanks to Osmo Salomaa) + +* fix to javascript-generation, "py.test --runbrowser" + should work more reliably now + +* removed previously accidentally added + py.test.broken and py.test.notimplemented helpers. + +* there now is a py.__version__ attribute + +Changes between 0.9.0 and 0.9.1 +------------------------------------------- + +This is a fairly complete list of changes between 0.9 and 0.9.1, which can +serve as a reference for developers. + +* allowing + signs in py.path.svn urls [39106] +* fixed support for Failed exceptions without excinfo in py.test [39340] +* added support for killing processes for Windows (as well as platforms that + support os.kill) in py.misc.killproc [39655] +* added setup/teardown for generative tests to py.test [40702] +* added detection of FAILED TO LOAD MODULE to py.test [40703, 40738, 40739] +* fixed problem with calling .remove() on wcpaths of non-versioned files in + py.path [44248] +* fixed some import and inheritance issues in py.test [41480, 44648, 44655] +* fail to run greenlet tests when pypy is available, but without stackless + [45294] +* small fixes in rsession tests [45295] +* fixed issue with 2.5 type representations in py.test [45483, 45484] +* made that internal reporting issues displaying is done atomically in py.test + [45518] +* made that non-existing files are igored by the py.lookup script [45519] +* improved exception name creation in py.test [45535] +* made that less threads are used in execnet [merge in 45539] +* removed lock required for atomical reporting issue displaying in py.test + [45545] +* removed globals from execnet [45541, 45547] +* refactored cleanup mechanics, made that setDaemon is set to 1 to make atexit + get called in 2.5 (py.execnet) [45548] +* fixed bug in joining threads in py.execnet's servemain [45549] +* refactored py.test.rsession tests to not rely on exact output format anymore + [45646] +* using repr() on test outcome [45647] +* added 'Reason' classes for py.test.skip() [45648, 45649] +* killed some unnecessary sanity check in py.test.collect [45655] +* avoid using os.tmpfile() in py.io.fdcapture because on Windows it's only + usable by Administrators [45901] +* added support for locking and non-recursive commits to py.path.svnwc [45994] +* locking files in py.execnet to prevent CPython from segfaulting [46010] +* added export() method to py.path.svnurl +* fixed -d -x in py.test [47277] +* fixed argument concatenation problem in py.path.svnwc [49423] +* restore py.test behaviour that it exits with code 1 when there are failures + [49974] +* don't fail on html files that don't have an accompanying .txt file [50606] +* fixed 'utestconvert.py < input' [50645] +* small fix for code indentation in py.code.source [50755] +* fix _docgen.py documentation building [51285] +* improved checks for source representation of code blocks in py.test [51292] +* added support for passing authentication to py.path.svn* objects [52000, + 52001] +* removed sorted() call for py.apigen tests in favour of [].sort() to support + Python 2.3 [52481] diff --git a/doc/en/conf.py b/doc/en/conf.py index ec1aa20e6..346100545 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -17,7 +17,7 @@ # # The full version, including alpha/beta/rc tags. # The short X.Y version. -version = release = "2.3.0.dev28" +version = release = "2.3.0" import sys, os diff --git a/doc/en/contents.txt b/doc/en/contents.txt index eb5e3699b..169524483 100644 --- a/doc/en/contents.txt +++ b/doc/en/contents.txt @@ -12,9 +12,9 @@ Full pytest documentation :maxdepth: 2 overview - example/index apiref plugins + example/index talks develop funcarg_compare.txt diff --git a/doc/en/unittest.txt b/doc/en/unittest.txt index 72a20cf59..99d7295e1 100644 --- a/doc/en/unittest.txt +++ b/doc/en/unittest.txt @@ -10,9 +10,9 @@ py.test has support for running Python `unittest.py style`_ tests. It's meant for leveraging existing unittest-style projects to use pytest features. Concretely, pytest will automatically collect ``unittest.TestCase`` subclasses and their ``test`` methods in -test files. It will invoke typlical ``setUp/tearDown`` methods and +test files. It will invoke typical setup/teardown methods and generally try to make test suites written to run on unittest, to also -run using pytest. We assume here that you are familiar with writing +run using ``py.test``. We assume here that you are familiar with writing ``unittest.TestCase`` style tests and rather focus on integration aspects. @@ -24,8 +24,8 @@ After :ref:`installation` type:: py.test and you should be able to run your unittest-style tests if they -are contained in ``test_*`` modules. This way you can make -use of most :ref:`pytest features `, for example +are contained in ``test_*`` modules. If that works for you then +you can make use of most :ref:`pytest features `, for example ``--pdb`` debugging in failures, using :ref:`plain assert-statements `, :ref:`more informative tracebacks `, stdout-capturing or distributing tests to multiple CPUs via the ``-nNUM`` option if you @@ -35,17 +35,17 @@ the general pytest documentation for many more examples. Mixing pytest fixtures into unittest.TestCase style tests ----------------------------------------------------------- -pytest supports using its :ref:`fixture mechanism ` with -``unittest.TestCase`` style tests. Assuming you have at least skimmed -the pytest fixture features, let's jump-start into an example that -integrates a pytest ``db_class`` fixture, setting up a -class-cached database object, and then reference it from -a unittest-style test:: +Running your unittest with ``py.test`` allows you to use its +:ref:`fixture mechanism ` with ``unittest.TestCase`` style +tests. Assuming you have at least skimmed the pytest fixture features, +let's jump-start into an example that integrates a pytest ``db_class`` +fixture, setting up a class-cached database object, and then reference +it from a unittest-style test:: # content of conftest.py - # hooks and fixtures in this file are available throughout all test - # modules living below the directory of this conftest.py file + # we define a fixture function below and it will be "used" by + # referencing its name from tests import pytest @@ -53,6 +53,7 @@ a unittest-style test:: def db_class(request): class DummyDB: pass + # set a class attribute on the invoking test context request.cls.db = DummyDB() This defines a fixture function ``db_class`` which - if used - is @@ -81,7 +82,7 @@ fixture definition:: assert 0, self.db # fail for demo purposes The ``@pytest.mark.usefixtures("db_class")`` class-decorator makes sure that -the pytest fixture function ``db_class`` is called for each test method. +the pytest fixture function ``db_class`` is called once per class. Due to the deliberately failing assert statements, we can take a look at the ``self.db`` values in the traceback:: @@ -114,7 +115,7 @@ the ``self.db`` values in the traceback:: test_unittest_db.py:12: AssertionError ========================= 2 failed in 0.02 seconds ========================= -This default pytest traceback shows that, indeed, the two test methods +This default pytest traceback shows that the two test methods share the same ``self.db`` instance which was our intention when writing the class-scoped fixture function above. @@ -124,13 +125,17 @@ autouse fixtures and accessing other fixtures Although it's usually better to explicitely declare use of fixtures you need for a given test, you may sometimes want to have fixtures that are -automatically used in a given context. For this, you can flag -fixture functions with ``@pytest.fixture(autouse=True)`` and define -the fixture function in the context where you want it used. Let's look -at an ``initdir`` fixrure which makes all test methods of a ``TestCase`` class -execute in a temporary directory with a pre-initialized ``samplefile.ini``. -Our ``initdir`` fixture itself uses the pytest builtin :ref:`tmpdir ` -fixture to help with creating a temporary dir:: +automatically used in a given context. After all, the traditional +style of unittest-setup mandates the use of this implicit fixture writing +and chances are, you are used to it or like it. + +You can flag fixture functions with ``@pytest.fixture(autouse=True)`` +and define the fixture function in the context where you want it used. +Let's look at an ``initdir`` fixture which makes all test methods of a +``TestCase`` class execute in a temporary directory with a +pre-initialized ``samplefile.ini``. Our ``initdir`` fixture itself uses +the pytest builtin :ref:`tmpdir ` fixture to delegate the +creation of a per-test temporary directory:: # content of test_unittest_cleandir.py import pytest @@ -148,8 +153,8 @@ fixture to help with creating a temporary dir:: Due to the ``autouse`` flag the ``initdir`` fixture function will be used for all methods of the class where it is defined. This is a -shortcut for using a ``@pytest.mark.usefixtures("initdir")`` on the -class like in the previous example. +shortcut for using a ``@pytest.mark.usefixtures("initdir")`` marker +on the class like in the previous example. Running this test module ...:: @@ -161,11 +166,13 @@ was executed ahead of the ``test_method``. .. note:: - ``unittest.TestCase`` methods cannot directly receive fixture + While pytest supports receiving fixtures via :ref:`test function arguments ` for non-unittest test methods, ``unittest.TestCase`` methods cannot directly receive fixture function arguments as implementing that is likely to inflict on the ability to run general unittest.TestCase test suites. - Given enough demand, attempts might be made, though. If - unittest finally grows a reasonable plugin system that should - help as well. In the meanwhile, the above ``usefixtures`` and - ``autouse`` examples should help to mix in pytest fixtures into - unittest suites. + Maybe optional support would be possible, though. If unittest finally + grows a plugin system that should help as well. In the meanwhile, the + above ``usefixtures`` and ``autouse`` examples should help to mix in + pytest fixtures into unittest suites. And of course you can also start + to selectively leave away the ``unittest.TestCase`` subclassing, use + plain asserts and get the unlimited pytest feature set. + diff --git a/setup.py b/setup.py index e445b0da2..e6c6c9019 100644 --- a/setup.py +++ b/setup.py @@ -24,7 +24,7 @@ def main(): name='pytest', description='py.test: simple powerful testing with Python', long_description = long_description, - version='2.3.0.dev30', + version='2.3.0.dev31', url='http://pytest.org', license='MIT license', platforms=['unix', 'linux', 'osx', 'cygwin', 'win32'], diff --git a/tox.ini b/tox.ini index 7f6dcf507..05a5f9728 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] distshare={homedir}/.tox/distshare -envlist=py26,py27,py31,py32,py33,py27-xdist,py25,py24 +envlist=py26,py27,py31,py32,py33,py27-xdist,py25,trial indexserver= pypi = http://pypi.python.org/simple testrun = http://pypi.testrun.org