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

@@ -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)
 ==================
 

doc/en/contents.rst

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

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
 ------------------------------------------------
 

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

@@ -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 = <test_class.TestClass object at 0xdeadbeef>
-    
+
         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 <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.
 
 
+