diff --git a/AUTHORS b/AUTHORS index 025a3c8f6..717595346 100644 --- a/AUTHORS +++ b/AUTHORS @@ -135,6 +135,7 @@ Russel Winder Ryan Wooden Samuele Pedroni Simon Gomizelj +Skylar Downes Stefan Farmbauer Stefan Zimmermann Stefano Taschini diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 78d7501fb..fbf43bd09 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -8,7 +8,9 @@ * Fix exception formatting while importing modules when the exception message contains non-ascii characters (`#2336`_). Thanks `@fabioz`_ for the report and `@nicoddemus`_ for the PR. - + +* Added documentation related to issue (`#1937`_) + Thanks `@skylarjhdownes`_ for the PR. * @@ -17,10 +19,13 @@ * + +.. _@skylarjhdownes: https://github.com/skylarjhdownes .. _@fabioz: https://github.com/fabioz .. _@metasyn: https://github.com/metasyn +.. _#1937: https://github.com/pytest-dev/pytest/issues/1937 .. _#2276: https://github.com/pytest-dev/pytest/issues/2276 .. _#2336: https://github.com/pytest-dev/pytest/issues/2336 @@ -292,6 +297,7 @@ + 3.0.2 (2016-09-01) ================== diff --git a/doc/en/contents.rst b/doc/en/contents.rst index d7f900810..ce6396e47 100644 --- a/doc/en/contents.rst +++ b/doc/en/contents.rst @@ -12,6 +12,7 @@ Full pytest documentation getting-started usage + existingtestsuite assert builtin fixture diff --git a/doc/en/customize.rst b/doc/en/customize.rst index d12a49037..e1d8fc571 100644 --- a/doc/en/customize.rst +++ b/doc/en/customize.rst @@ -45,11 +45,11 @@ Here is the algorithm which finds the rootdir from ``args``: matched, it becomes the ini-file and its directory becomes the rootdir. - if no ini-file was found, use the already determined common ancestor as root - directory. This allows to work with pytest in structures that are not part of + directory. This allows the use of pytest in structures that are not part of a package and don't have any particular ini-file configuration. If no ``args`` are given, pytest collects test below the current working -directory and also starts determining the rootdir from there. +directory and also starts determining the rootdir from there. :warning: custom pytest plugin commandline arguments may include a path, as in ``pytest --log-output ../../test.log args``. Then ``args`` is mandatory, @@ -97,6 +97,8 @@ check for ini-files as follows:: .. _`how to change command line options defaults`: .. _`adding default options`: + + How to change command line options defaults ------------------------------------------------ diff --git a/doc/en/existingtestsuite.rst b/doc/en/existingtestsuite.rst new file mode 100644 index 000000000..d304b30c9 --- /dev/null +++ b/doc/en/existingtestsuite.rst @@ -0,0 +1,34 @@ +.. _existingtestsuite: + +Using pytest with an existing test suite +=========================================== + +Pytest can be used with most existing test suites, but its +behavior differs from other test runners such as :ref:`nose ` or +Python's default unittest framework. + +Before using this section you will want to :ref:`install pytest `. + +Running an existing test suite with pytest +--------------------------------------------- + +Say you want to contribute to an existing repository somewhere. +After pulling the code into your development space using some +flavor of version control and (optionally) setting up a virtualenv +you will want to run:: + + cd + pip install -e . # Environment dependent alternatives include + # 'python setup.py develop' and 'conda develop' + +in your project root. This will set up a symlink to your code in +site-packages, allowing you to edit your code while your tests +run against it as if it were installed. + +Setting up your project in development mode lets you avoid having to +reinstall every time you want to run your tests, and is less brittle than +mucking about with sys.path to point your tests at local code. + +Also consider using :ref:`tox `. + +.. include:: links.inc diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index c65cfe94f..9f2aa2cda 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -49,17 +49,17 @@ That's it. You can execute the test function now:: platform linux -- Python 3.5.2, pytest-3.0.7, py-1.4.32, pluggy-0.4.0 rootdir: $REGENDOC_TMPDIR, inifile: collected 1 items - + test_sample.py F - + ======= FAILURES ======== _______ test_answer ________ - + def test_answer(): > assert func(3) == 5 E assert 4 == 5 E + where 4 = func(3) - + test_sample.py:5: AssertionError ======= 1 failed in 0.12 seconds ======== @@ -128,15 +128,15 @@ run the module by passing its filename:: .F ======= FAILURES ======== _______ TestClass.test_two ________ - + self = - + def test_two(self): x = "hello" > assert hasattr(x, 'check') E AssertionError: assert False E + where False = hasattr('hello', 'check') - + test_class.py:8: AssertionError 1 failed, 1 passed in 0.12 seconds @@ -165,14 +165,14 @@ before performing the test function call. Let's just run it:: F ======= FAILURES ======== _______ test_needsfiles ________ - + tmpdir = local('PYTEST_TMPDIR/test_needsfiles0') - + def test_needsfiles(tmpdir): print (tmpdir) > assert 0 E assert 0 - + test_tmpdir.py:3: AssertionError --------------------------- Captured stdout call --------------------------- PYTEST_TMPDIR/test_needsfiles0 @@ -192,6 +192,7 @@ Here are a few suggestions where to go next: * :ref:`cmdline` for command line invocation examples * :ref:`good practices ` for virtualenv, test layout +* :ref:`existingtestsuite` for working with pre-existing tests * :ref:`fixtures` for providing a functional baseline to your tests * :ref:`plugins` managing and writing plugins diff --git a/doc/en/goodpractices.rst b/doc/en/goodpractices.rst index c17fabbc9..92cd9ed81 100644 --- a/doc/en/goodpractices.rst +++ b/doc/en/goodpractices.rst @@ -187,6 +187,8 @@ You can then install your package in "editable" mode:: pip install -e . which lets you change your source code (both tests and application) and rerun tests at will. +This is similar to running `python setup.py develop` or `conda develop` in that it installs +your package using a symlink to your development code. Once you are done with your work and want to make sure that your actual package passes all tests you may want to look into `tox`_, the diff --git a/doc/en/nose.rst b/doc/en/nose.rst index a785ecfaa..5effd0d7b 100644 --- a/doc/en/nose.rst +++ b/doc/en/nose.rst @@ -47,9 +47,19 @@ Unsupported idioms / known issues ``tests.test_mod``) but different file system paths (e.g. ``tests/test_mode.py`` and ``other/tests/test_mode.py``) by extending sys.path/import semantics. pytest does not do that - but there is discussion in `issue268 `_ for adding some support. Note that + but there is discussion in `#268 `_ for adding some support. Note that `nose2 choose to avoid this sys.path/import hackery `_. + If you place a conftest.py file in the root directory of your project + (as determined by pytest) pytest will run tests "nose style" against + the code below that directory by adding it to your ``sys.path`` instead of + running against your installed code. + + You may find yourself wanting to do this if you ran ``python setup.py install`` + to set up your project, as opposed to ``python setup.py develop`` or any of + the package manager equivalents. Installing with develop in a + virtual environment like Tox is recommended over this pattern. + - nose-style doctests are not collected and executed correctly, also doctest fixtures don't work. @@ -62,3 +72,4 @@ Unsupported idioms / known issues being the recommended alternative. +