Merge pull request #2550 from Pylons/vincent-ferotin-scaffolds-allow-pytest-run-without-args

Vincent ferotin scaffolds allow pytest run without args

6 files changed, 114 insertions, 45 deletions

diff --git a/docs/conventions.rst b/docs/conventions.rst
index 0f5daf106..43853882c 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -55,7 +55,7 @@ character, e.g.:
 
   .. code-block:: bash
 
-     $ $VENV/bin/py.test tutorial/tests.py -q
+     $ $VENV/bin/py.test -q
 
 (See :term:`venv` for the meaning of ``$VENV``)
 
@@ -64,7 +64,7 @@ drive letter and/or a directory name, e.g.:
 
   .. code-block:: doscon
 
-     c:\examples> %VENV%\Scripts\py.test tutorial\tests.py -q
+     c:\examples> %VENV%\Scripts\py.test -q
 
 (See :term:`venv` for the meaning of ``%VENV%``)
 
@@ -73,7 +73,7 @@ example block commands are prefixed only with a ``>`` character, e.g.:
 
   .. code-block:: doscon
 
-     > %VENV%\Scripts\py.test tutorial\tests.py -q
+     > %VENV%\Scripts\py.test -q
 
 When a command that should be typed on one line is too long to fit on a page,
 the backslash ``\`` is used to indicate that the following printed line should
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 56247ee33..1ce12a938 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -209,19 +209,19 @@ On UNIX:
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test myproject/tests.py -q
+   $ $VENV/bin/py.test -q
 
 On Windows:
 
 .. code-block:: doscon
 
-   > %VENV%\Scripts\py.test myproject\tests.py -q
+   > %VENV%\Scripts\py.test -q
 
 Here's sample output from a test run on UNIX:
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test myproject/tests.py -q
+   $ $VENV/bin/py.test -q
    ..
    2 passed in 0.47 seconds
 
@@ -235,6 +235,26 @@ only two sample tests exist.
     to a stream of dots. If you don't pass ``-q``, you'll see verbose test
     result output (which normally isn't very useful).
 
+Alternatively, if you'd like to see test coverage, pass the ``--cov`` option
+to ``py.test``:
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov -q
+
+Scaffolds include configuration defaults for ``py.test`` and test coverage.
+These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
+the root of your package. Without these defaults, we would need to specify the
+path to the module on which we want to run tests and coverage.
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=myproject myproject/tests.py -q
+
+.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
+   ``py.test -h`` to see its full set of options.
+
+
 .. index::
    single: running an application
    single: pserve
@@ -909,10 +929,10 @@ The ``tests.py`` module includes unit tests for your application.
    :linenos:
 
 This sample ``tests.py`` file has one unit test and one functional test defined
-within it. These tests are executed when you run ``py.test myproject/tests.py
--q``. You may add more tests here as you build your application. You are not
-required to write tests to use :app:`Pyramid`. This file is simply provided for
-convenience and example.
+within it. These tests are executed when you run ``py.test -q``. You may add
+more tests here as you build your application. You are not required to write
+tests to use :app:`Pyramid`. This file is simply provided for convenience and
+example.
 
 See :ref:`testing_chapter` for more information about writing :app:`Pyramid`
 unit tests.
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index 78af6fd40..b170e5d98 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -699,7 +699,7 @@ We changed ``setup.py`` which means we need to rerun ``$VENV/bin/pip install -e
 
 .. code-block:: bash
 
-    $ $VENV/bin/py.test --cov=hello_world --cov-report=term-missing hello_world/tests.py
+    $ $VENV/bin/py.test --cov --cov-report=term-missing
 
 This yields the following output.
 
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index ee87dcaf9..6172b122b 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -262,14 +262,14 @@ On UNIX
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test tutorial/tests.py -q
+   $ $VENV/bin/py.test -q
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
 
 For a successful test run, you should see output that ends like this:
 
@@ -278,16 +278,6 @@ For a successful test run, you should see output that ends like this:
    .
    1 passed in 0.24 seconds
 
-.. note::
-   py.test follows :ref:`conventions for Python test discovery
-   <pytest:test discovery>`. This explains why we cannot run just ``py.test``
-   without specifying the module to test after generating a project from a
-   scaffold.
-
-   py.test is a :ref:`mature full-featured Python testing tool
-   <pytest:features>`. See py.test's documentation for :ref:`pytest:usage` or
-   invoke ``py.test -h`` to see its full set of options.
-
 
 Expose test coverage information
 --------------------------------
@@ -305,15 +295,15 @@ On UNIX
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
+   $ $VENV/bin/py.test --cov --cov-report=term-missing
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
-       --cov-report=term-missing tutorial\tests.py
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov \
+       --cov-report=term-missing
 
 If successful, you will see output something like this:
 
@@ -341,6 +331,40 @@ If successful, you will see output something like this:
 Our package doesn't quite have 100% test coverage.
 
 
+.. _test_and_coverage_scaffold_defaults_zodb:
+
+Test and coverage scaffold defaults
+-----------------------------------
+
+Scaffolds include configuration defaults for ``py.test`` and test coverage.
+These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
+the root of your package. Without these defaults, we would need to specify the
+path to the module on which we want to run tests and coverage.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py -q
+
+py.test follows :ref:`conventions for Python test discovery
+<pytest:test discovery>`, and the configuration defaults from the scaffold
+tell ``py.test`` where to find the module on which we want to run tests and
+coverage.
+
+.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
+   ``py.test -h`` to see its full set of options.
+
+
 .. _wiki-start-the-application:
 
 Start the application
diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst
index 788ec595b..85a023cc9 100644
--- a/docs/tutorials/wiki/tests.rst
+++ b/docs/tutorials/wiki/tests.rst
@@ -52,20 +52,21 @@ Running the tests
 =================
 
 We can run these tests by using ``py.test`` similarly to how we did in
-:ref:`running_tests`. Our testing dependencies have already been satisfied,
-courtesy of the scaffold, so we can jump right to running tests.
+:ref:`running_tests`. Courtesy of the scaffold, our testing dependencies have
+already been satisfied and ``py.test`` and coverage have already been
+configured, so we can jump right to running tests.
 
 On UNIX:
 
 .. code-block:: text
 
-   $ $VENV/bin/py.test tutorial/tests.py -q
+   $ $VENV/bin/py.test -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial/tests.py -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
 
 The expected result should look like the following:
 
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 6f46c5539..2b8ce5dfa 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -279,14 +279,14 @@ On UNIX
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test tutorial/tests.py -q
+   $ $VENV/bin/py.test -q
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test -q
 
 For a successful test run, you should see output that ends like this:
 
@@ -295,16 +295,6 @@ For a successful test run, you should see output that ends like this:
    ..
    2 passed in 0.44 seconds
 
-.. note::
-   py.test follows :ref:`conventions for Python test discovery
-   <pytest:test discovery>`. This explains why we cannot run just ``py.test``
-   without specifying the module to test after generating a project from a
-   scaffold.
-
-   py.test is a :ref:`mature full-featured Python testing tool
-   <pytest:features>`. See py.test's documentation for :ref:`pytest:usage` or
-   invoke ``py.test -h`` to see its full set of options.
-
 
 Expose test coverage information
 --------------------------------
@@ -322,15 +312,15 @@ On UNIX
 
 .. code-block:: bash
 
-   $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py
+   $ $VENV/bin/py.test --cov --cov-report=term-missing
 
 On Windows
 ^^^^^^^^^^
 
 .. code-block:: doscon
 
-   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
-       --cov-report=term-missing tutorial\tests.py
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov \
+       --cov-report=term-missing
 
 If successful, you will see output something like this:
 
@@ -365,6 +355,40 @@ If successful, you will see output something like this:
 Our package doesn't quite have 100% test coverage.
 
 
+.. _test_and_coverage_scaffold_defaults_sql:
+
+Test and coverage scaffold defaults
+-----------------------------------
+
+Scaffolds include configuration defaults for ``py.test`` and test coverage.
+These configuration files are ``pytest.ini`` and ``.coveragerc``, located at
+the root of your package. Without these defaults, we would need to specify the
+path to the module on which we want to run tests and coverage.
+
+On UNIX
+^^^^^^^
+
+.. code-block:: bash
+
+   $ $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q
+
+On Windows
+^^^^^^^^^^
+
+.. code-block:: doscon
+
+   c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \
+       --cov-report=term-missing tutorial\tests.py -q
+
+py.test follows :ref:`conventions for Python test discovery
+<pytest:test discovery>`, and the configuration defaults from the scaffold
+tell ``py.test`` where to find the module on which we want to run tests and
+coverage.
+
+.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke
+   ``py.test -h`` to see its full set of options.
+
+
 .. _initialize_db_wiki2:
 
 Initializing the database