- use an environment variable and venv. See https://github.com/Pylons/pyramid/pull/2468#discussion_r59311019

- rename stanza from `testing_extras` to `tests_require`
- switch from nose to pytest

1 files changed, 92 insertions, 46 deletions

diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index e381a9232..78af6fd40 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -21,27 +21,40 @@ Python 2.7 <https://packaging.python.org/en/latest/projects/#virtualenv>`_),
 `pip <https://packaging.python.org/en/latest/projects/#pip>`_, and `setuptools
 <https://packaging.python.org/en/latest/projects/#easy-install>`_.
 
+To save a little bit of typing and to be certain that we use the modules,
+scripts, and packages installed in our virtual environment, we'll set an
+environment variable, too.
+
 As an example, for Python 3.5+ on Linux:
 
 .. parsed-literal::
 
-    $ python3 -m venv env
-    $ env/bin/pip install pyramid
+    # set an environment variable to where you want your virtual environment
+    $ export VENV=~/env
+    # create the virtual environment
+    $ python3 -m venv $VENV
+    # install pyramid
+    $ $VENV/bin/pip install pyramid
     # or for a specific released version
-    $ env/bin/pip install "pyramid==\ |release|\ "
+    $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
 For Windows:
 
 .. parsed-literal::
 
-    c:\\> c:\\Python35\\python3 -m venv env
-    c:\\> env\\Scripts\\pip install pyramid
+    # set an environment variable to where you want your virtual environment
+    c:\> set VENV=c:\env
+    # create the virtual environment
+    c:\\> c:\\Python35\\python3 -m venv %VENV%
+    # install pyramid
+    c:\\> %VENV%\\Scripts\\pip install pyramid
     # or for a specific released version
-    c:\\> env\\Scripts\\pip install "pyramid==\ |release|\ "
+    c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
 Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick
-Tour*. We're just showing Python 3 a little love (Pyramid had production
-support for Python 3 in October 2011).
+Tour*. We're showing Python 3 for simplicity. (Pyramid had production support
+for Python 3 in October 2011.) Also for simplicity, the remaining examples will
+show only UNIX commands.
 
 .. seealso:: See also:
     :ref:`Quick Tutorial section on Requirements <qtut_requirements>`,
@@ -62,7 +75,7 @@ This simple example is easy to run. Save this as ``app.py`` and run it:
 
 .. code-block:: bash
 
-    $ python ./app.py
+    $ $VENV/bin/python ./app.py
 
 Next open http://localhost:6543/ in a browser, and you will see the ``Hello
 World!`` message.
@@ -111,7 +124,9 @@ Let's see some features of requests and responses in action:
 
 In this Pyramid view, we get the URL being visited from ``request.url``. Also
 if you visited http://localhost:6543/?name=alice in a browser, the name is
-included in the body of the response::
+included in the body of the response:
+
+.. code-block:: text
 
   URL http://localhost:6543/?name=alice with name: alice
 
@@ -239,7 +254,7 @@ Chameleon as a :term:`renderer` in our Pyramid application:
 
 .. code-block:: bash
 
-    $ env/bin/pip install pyramid_chameleon
+    $ $VENV/bin/pip install pyramid_chameleon
 
 With the package installed, we can include the template bindings into our
 configuration in ``app.py``:
@@ -283,7 +298,7 @@ Jinja2 as a :term:`renderer` in our Pyramid applications:
 
 .. code-block:: bash
 
-    $ env/bin/pip install pyramid_jinja2
+    $ $VENV/bin/pip install pyramid_jinja2
 
 With the package installed, we can include the template bindings into our
 configuration:
@@ -492,7 +507,7 @@ We next use the normal Python command to set up our package for development:
 .. code-block:: bash
 
     $ cd hello_world
-    $ env/bin/pip install -e .
+    $ $VENV/bin/pip install -e .
 
 We are moving in the direction of a full-featured Pyramid project, with a
 proper setup for Python standards (packaging) and Pyramid configuration. This
@@ -500,7 +515,7 @@ includes a new way of running your application:
 
 .. code-block:: bash
 
-    $ pserve development.ini
+    $ $VENV/bin/pserve development.ini
 
 Let's look at ``pserve`` and configuration in more depth.
 
@@ -527,7 +542,7 @@ the server when they change:
 
 .. code-block:: bash
 
-    $ pserve development.ini --reload
+    $ $VENV/bin/pserve development.ini --reload
 
 The ``pserve`` command has a number of other options and operations. Most of
 the work, though, comes from your project's wiring, as expressed in the
@@ -607,7 +622,7 @@ It was installed when you previously ran:
 
 .. code-block:: bash
 
-    $ env/bin/pip install -e .
+    $ $VENV/bin/pip install -e .
 
 The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need
 to include its configuration into our web application. The ``pyramid_jinja2``
@@ -638,48 +653,79 @@ the relevant ``.ini`` configuration file.
     :ref:`Quick Tutorial pyramid_debugtoolbar <qtut_debugtoolbar>` and
     :ref:`pyramid_debugtoolbar <toolbar:overview>`
 
-Unit tests and ``nose``
-=======================
+Unit tests and ``py.test``
+==========================
 
 Yikes! We got this far and we haven't yet discussed tests. This is particularly
 egregious, as Pyramid has had a deep commitment to full test coverage since
 before its release.
 
 Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module with
-one unit test in it. To run it, let's install the handy ``nose`` test runner by
-editing ``setup.py``. While we're at it, we'll throw in the ``coverage`` tool
-which yells at us for code that isn't tested. Edit line 36 so it becomes the
-following:
+one unit test in it. To run it, let's install the handy ``pytest`` test runner
+by editing ``setup.py``. While we're at it, we'll throw in the ``pytest-cov``
+tool which yells at us for code that isn't tested. Insert and edit the
+following lines as shown:
 
 .. code-block:: python
     :linenos:
-    :lineno-start: 36
+    :lineno-start: 11
+    :emphasize-lines: 8-12
+
+    requires = [
+        'pyramid',
+        'pyramid_jinja2',
+        'pyramid_debugtoolbar',
+        'waitress',
+    ]
 
-          tests_require={
-              'testing': ['nose', 'coverage'],
-          },
+    tests_require = [
+        'WebTest >= 1.3.1',  # py3 compat
+        'pytest',  # includes virtualenv
+        'pytest-cov',
+        ]
 
-We changed ``setup.py`` which means we need to rerun
-``env/bin/pip install -e .``. We can now run all our tests:
+.. code-block:: python
+    :linenos:
+    :lineno-start: 34
+    :emphasize-lines: 2-4
+
+        zip_safe=False,
+        extras_require={
+          'testing': tests_require,
+        },
+
+We changed ``setup.py`` which means we need to rerun ``$VENV/bin/pip install -e
+".[testing]"``. We can now run all our tests:
 
 .. code-block:: bash
 
-    $ nosetests hello_world/tests.py
-    .
-    Name                  Stmts   Miss  Cover   Missing
-    ---------------------------------------------------
-    hello_world              11      8    27%   11-23
-    hello_world.models        5      1    80%   8
-    hello_world.tests        14      0   100%
-    hello_world.views         4      0   100%
-    ---------------------------------------------------
-    TOTAL                    34      9    74%
-    ----------------------------------------------------------------------
-    Ran 1 test in 0.009s
+    $ $VENV/bin/py.test --cov=hello_world --cov-report=term-missing hello_world/tests.py
+
+This yields the following output.
+
+.. code-block:: text
+
+    =========================== test session starts ===========================
+    platform darwin -- Python 3.5.0, pytest-2.9.1, py-1.4.31, pluggy-0.3.1
+    rootdir: /Users/stevepiercy/projects/hack-on-pyramid/hello_world, inifile:
+    plugins: cov-2.2.1
+    collected 1 items
+
+    hello_world/tests.py .
+    ------------- coverage: platform darwin, python 3.5.0-final-0 -------------
+    Name                       Stmts   Miss  Cover   Missing
+    --------------------------------------------------------
+    hello_world/__init__.py       11      8    27%   11-23
+    hello_world/resources.py       5      1    80%   8
+    hello_world/tests.py          14      0   100%
+    hello_world/views.py           4      0   100%
+    --------------------------------------------------------
+    TOTAL                         34      9    74%
 
-    OK
+    ========================= 1 passed in 0.22 seconds =========================
 
-Our unit test passed. What did our test look like?
+Our unit test passed, although its coverage is incomplete. What did our test
+look like?
 
 .. literalinclude:: quick_tour/package/hello_world/tests.py
     :linenos:
@@ -817,9 +863,9 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold!
 
 .. code-block:: bash
 
-  $ pcreate --scaffold alchemy sqla_demo
+  $ $VENV/bin/pcreate --scaffold alchemy sqla_demo
   $ cd sqla_demo
-  $ env/bin/pip install -e .
+  $ $VENV/bin/pip install -e .
 
 We now have a working sample SQLAlchemy application with all dependencies
 installed. The sample project provides a console script to initialize a SQLite
@@ -827,8 +873,8 @@ database with tables. Let's run it, then start the application:
 
 .. code-block:: bash
 
-  $ initialize_sqla_demo_db development.ini
-  $ pserve development.ini
+  $ $VENV/bin/initialize_sqla_demo_db development.ini
+  $ $VENV/bin/pserve development.ini
 
 The ORM eases the mapping of database structures into a programming language.
 SQLAlchemy uses "models" for this mapping. The scaffold generated a sample