Merge pull request #1940 from skylarjhdownes/master

adding documentation about pointing pytest at source files

AUTHORS

@@ -135,6 +135,7 @@ Russel Winder
 Ryan Wooden
 Samuele Pedroni
 Simon Gomizelj
+Skylar Downes
 Stefan Farmbauer
 Stefan Zimmermann
 Stefano Taschini

CHANGELOG.rst

@@ -9,6 +9,8 @@
   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)
 ==================
 

doc/en/contents.rst

@@ -12,6 +12,7 @@ Full pytest documentation
 
    getting-started
    usage
+   existingtestsuite
    assert
    builtin
    fixture

doc/en/customize.rst

@@ -45,7 +45,7 @@ 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
@@ -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
 ------------------------------------------------
 

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 <noseintegration>` or
+Python's default unittest framework.
+
+Before using this section you will want to :ref:`install pytest <getstarted>`.
+
+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 <repository>
+    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 <use tox>`.
+
+.. include:: links.inc

doc/en/getting-started.rst

@@ -192,6 +192,7 @@ Here are a few suggestions where to go next:
 
 * :ref:`cmdline` for command line invocation examples
 * :ref:`good practices <goodpractices>` 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
 

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

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 <https://github.com/pytest-dev/pytest/issues/268>`_ for adding some support.  Note that
+  but there is discussion in `#268 <https://github.com/pytest-dev/pytest/issues/268>`_ for adding some support.  Note that
   `nose2 choose to avoid this sys.path/import hackery <https://nose2.readthedocs.io/en/latest/differences.html#test-discovery-and-loading>`_.
 
+  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.
 
 
+