sync basiclayout, installation, models with new structure

29 files changed, 785 insertions, 235 deletions

diff --git a/docs/tutorials/wiki2/src/basiclayout/.gitignore b/docs/tutorials/wiki2/src/basiclayout/.gitignore
index 1853d983c..c612e59f2 100644
--- a/docs/tutorials/wiki2/src/basiclayout/.gitignore
+++ b/docs/tutorials/wiki2/src/basiclayout/.gitignore
@@ -19,3 +19,4 @@ Data.fs*
 .DS_Store
 coverage
 test
+*.sqlite
diff --git a/docs/tutorials/wiki2/src/basiclayout/testing.ini b/docs/tutorials/wiki2/src/basiclayout/testing.ini
new file mode 100644
index 000000000..85e5e1ae9
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/testing.ini
@@ -0,0 +1,79 @@
+###
+# app configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+
+sqlalchemy.url = sqlite:///%(here)s/testing.sqlite
+
+retry.attempts = 3
+
+[pshell]
+setup = tutorial.pshell.setup
+
+###
+# wsgi server configuration
+###
+
+[alembic]
+# path to migration scripts
+script_location = tutorial/alembic
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(rev)s
+# file_template = %%(rev)s_%%(slug)s
+
+[server:main]
+use = egg:waitress#main
+listen = *:6543
+
+###
+# logging configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy, alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[logger_alembic]
+level = WARN
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/basiclayout/tests/conftest.py b/docs/tutorials/wiki2/src/basiclayout/tests/conftest.py
new file mode 100644
index 000000000..2db65f887
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tests/conftest.py
@@ -0,0 +1,125 @@
+import alembic
+import alembic.config
+import alembic.command
+import os
+from pyramid.paster import get_appsettings
+from pyramid.scripting import prepare
+from pyramid.testing import DummyRequest
+import pytest
+import transaction
+from webob.cookies import Cookie
+import webtest
+
+from tutorial import main
+from tutorial import models
+from tutorial.models.meta import Base
+
+
+def pytest_addoption(parser):
+    parser.addoption('--ini', action='store', metavar='INI_FILE')
+
+@pytest.fixture(scope='session')
+def ini_file(request):
+    # potentially grab this path from a pytest option
+    return os.path.abspath(request.config.option.ini or 'testing.ini')
+
+@pytest.fixture(scope='session')
+def app_settings(ini_file):
+    return get_appsettings(ini_file)
+
+@pytest.fixture(scope='session')
+def dbengine(app_settings, ini_file):
+    engine = models.get_engine(app_settings)
+
+    alembic_cfg = alembic.config.Config(ini_file)
+    Base.metadata.drop_all(bind=engine)
+    alembic.command.stamp(alembic_cfg, None, purge=True)
+
+    # run migrations to initialize the database
+    # depending on how we want to initialize the database from scratch
+    # we could alternatively call:
+    # Base.metadata.create_all(bind=engine)
+    # alembic.command.stamp(alembic_cfg, "head")
+    alembic.command.upgrade(alembic_cfg, "head")
+
+    yield engine
+
+    Base.metadata.drop_all(bind=engine)
+    alembic.command.stamp(alembic_cfg, None, purge=True)
+
+@pytest.fixture(scope='session')
+def app(app_settings, dbengine):
+    return main({}, dbengine=dbengine, **app_settings)
+
+@pytest.fixture
+def tm():
+    tm = transaction.TransactionManager(explicit=True)
+    tm.begin()
+    tm.doom()
+
+    yield tm
+
+    tm.abort()
+
+@pytest.fixture
+def dbsession(app, tm):
+    session_factory = app.registry['dbsession_factory']
+    return models.get_tm_session(session_factory, tm)
+
+@pytest.fixture
+def testapp(app, tm, dbsession):
+    # override request.dbsession and request.tm with our own
+    # externally-controlled values that are shared across requests but aborted
+    # at the end
+    testapp = webtest.TestApp(app, extra_environ={
+        'HTTP_HOST': 'example.com',
+        'tm.active': True,
+        'tm.manager': tm,
+        'app.dbsession': dbsession,
+    })
+
+    return testapp
+
+@pytest.fixture
+def app_request(app, tm, dbsession):
+    """
+    A real request.
+
+    This request is almost identical to a real request but it has some
+    drawbacks in tests as it's harder to mock data and is heavier.
+
+    """
+    env = prepare(registry=app.registry)
+    request = env['request']
+    request.host = 'example.com'
+
+    # without this, request.dbsession will be joined to the same transaction
+    # manager but it will be using a different sqlalchemy.orm.Session using
+    # a separate database transaction
+    request.dbsession = dbsession
+    request.tm = tm
+
+    yield request
+    env['closer']()
+
+@pytest.fixture
+def dummy_request(app, tm, dbsession):
+    """
+    A lightweight dummy request.
+
+    This request is ultra-lightweight and should be used only when the
+    request itself is not a large focus in the call-stack.
+
+    It is way easier to mock and control side-effects using this object.
+
+    - It does not have request extensions applied.
+    - Threadlocals are not properly pushed.
+
+    """
+    request = DummyRequest()
+    request.registry = app.registry
+    request.host = 'example.com'
+    request.dbsession = dbsession
+    request.tm = tm
+
+    return request
diff --git a/docs/tutorials/wiki2/src/basiclayout/tests/test_functional.py b/docs/tutorials/wiki2/src/basiclayout/tests/test_functional.py
new file mode 100644
index 000000000..dbcd8aec7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tests/test_functional.py
@@ -0,0 +1,13 @@
+from tutorial import models
+
+def test_my_view_success(testapp, dbsession):
+    model = models.MyModel(name='one', value=55)
+    dbsession.add(model)
+    dbsession.flush()
+
+    res = testapp.get('/', status=200)
+    assert res.body
+
+def test_notfound(testapp):
+    res = testapp.get('/badurl', status=404)
+    assert res.status_code == 404
diff --git a/docs/tutorials/wiki2/src/basiclayout/tests/test_it.py b/docs/tutorials/wiki2/src/basiclayout/tests/test_it.py
deleted file mode 100644
index ea16534fc..000000000
--- a/docs/tutorials/wiki2/src/basiclayout/tests/test_it.py
+++ /dev/null
@@ -1,66 +0,0 @@
-import unittest
-
-from pyramid import testing
-
-import transaction
-
-
-def dummy_request(dbsession):
-    return testing.DummyRequest(dbsession=dbsession)
-
-
-class BaseTest(unittest.TestCase):
-    def setUp(self):
-        self.config = testing.setUp(settings={
-            'sqlalchemy.url': 'sqlite:///:memory:'
-        })
-        self.config.include('tutorial.models')
-        settings = self.config.get_settings()
-
-        from tutorial.models import (
-            get_engine,
-            get_session_factory,
-            get_tm_session,
-            )
-
-        self.engine = get_engine(settings)
-        session_factory = get_session_factory(self.engine)
-
-        self.session = get_tm_session(session_factory, transaction.manager)
-
-    def init_database(self):
-        from tutorial.models.meta import Base
-        Base.metadata.create_all(self.engine)
-
-    def tearDown(self):
-        from tutorial.models.meta import Base
-
-        testing.tearDown()
-        transaction.abort()
-        Base.metadata.drop_all(self.engine)
-
-
-class TestMyViewSuccessCondition(BaseTest):
-
-    def setUp(self):
-        super(TestMyViewSuccessCondition, self).setUp()
-        self.init_database()
-
-        from tutorial.models import MyModel
-
-        model = MyModel(name='one', value=55)
-        self.session.add(model)
-
-    def test_passing_view(self):
-        from tutorial.views.default import my_view
-        info = my_view(dummy_request(self.session))
-        self.assertEqual(info['one'].name, 'one')
-        self.assertEqual(info['project'], 'myproj')
-
-
-class TestMyViewFailureCondition(BaseTest):
-
-    def test_failing_view(self):
-        from tutorial.views.default import my_view
-        info = my_view(dummy_request(self.session))
-        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tests/test_views.py b/docs/tutorials/wiki2/src/basiclayout/tests/test_views.py
new file mode 100644
index 000000000..8ae464d03
--- /dev/null
+++ b/docs/tutorials/wiki2/src/basiclayout/tests/test_views.py
@@ -0,0 +1,23 @@
+from tutorial import models
+from tutorial.views.default import my_view
+from tutorial.views.notfound import notfound_view
+
+
+def test_my_view_failure(app_request):
+    info = my_view(app_request)
+    assert info.status_int == 500
+
+def test_my_view_success(app_request, dbsession):
+    model = models.MyModel(name='one', value=55)
+    dbsession.add(model)
+    dbsession.flush()
+
+    info = my_view(app_request)
+    assert app_request.response.status_int == 200
+    assert info['one'].name == 'one'
+    assert info['project'] == 'myproj'
+
+def test_notfound_view(app_request):
+    info = notfound_view(app_request)
+    assert app_request.response.status_int == 404
+    assert info == {}
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index 5c2ba5cc0..7edc0957d 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -5,8 +5,8 @@ def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
     with Configurator(settings=settings) as config:
-        config.include('.models')
         config.include('pyramid_jinja2')
         config.include('.routes')
+        config.include('.models')
         config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
index d8a273e9e..1c3ec5ee8 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
@@ -65,13 +65,21 @@ def includeme(config):
     # use pyramid_retry to retry a request when transient exceptions occur
     config.include('pyramid_retry')
 
-    session_factory = get_session_factory(get_engine(settings))
+    # hook to share the dbengine fixture in testing
+    dbengine = settings.get('dbengine')
+    if not dbengine:
+        dbengine = get_engine(settings)
+
+    session_factory = get_session_factory(dbengine)
     config.registry['dbsession_factory'] = session_factory
 
     # make request.dbsession available for use in Pyramid
-    config.add_request_method(
-        # r.tm is the transaction manager used by pyramid_tm
-        lambda r: get_tm_session(session_factory, r.tm),
-        'dbsession',
-        reify=True
-    )
+    def dbsession(request):
+        # hook to share the dbsession fixture in testing
+        dbsession = request.environ.get('app.dbsession')
+        if dbsession is None:
+            # request.tm is the transaction manager used by pyramid_tm
+            dbsession = get_tm_session(session_factory, request.tm)
+        return dbsession
+
+    config.add_request_method(dbsession, reify=True)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views/default.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/default.py
index 094b2f303..a0f654d38 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/views/default.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views/default.py
@@ -1,7 +1,6 @@
 from pyramid.view import view_config
 from pyramid.response import Response
-
-from sqlalchemy.exc import DBAPIError
+from sqlalchemy.exc import SQLAlchemyError
 
 from .. import models
 
@@ -10,8 +9,8 @@ from .. import models
 def my_view(request):
     try:
         query = request.dbsession.query(models.MyModel)
-        one = query.filter(models.MyModel.name == 'one').first()
-    except DBAPIError:
+        one = query.filter(models.MyModel.name == 'one').one()
+    except SQLAlchemyError:
         return Response(db_err_msg, content_type='text/plain', status=500)
     return {'one': one, 'project': 'myproj'}
 
diff --git a/docs/tutorials/wiki2/src/installation/.gitignore b/docs/tutorials/wiki2/src/installation/.gitignore
index 1853d983c..c612e59f2 100644
--- a/docs/tutorials/wiki2/src/installation/.gitignore
+++ b/docs/tutorials/wiki2/src/installation/.gitignore
@@ -19,3 +19,4 @@ Data.fs*
 .DS_Store
 coverage
 test
+*.sqlite
diff --git a/docs/tutorials/wiki2/src/installation/testing.ini b/docs/tutorials/wiki2/src/installation/testing.ini
new file mode 100644
index 000000000..85e5e1ae9
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/testing.ini
@@ -0,0 +1,79 @@
+###
+# app configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+
+sqlalchemy.url = sqlite:///%(here)s/testing.sqlite
+
+retry.attempts = 3
+
+[pshell]
+setup = tutorial.pshell.setup
+
+###
+# wsgi server configuration
+###
+
+[alembic]
+# path to migration scripts
+script_location = tutorial/alembic
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(rev)s
+# file_template = %%(rev)s_%%(slug)s
+
+[server:main]
+use = egg:waitress#main
+listen = *:6543
+
+###
+# logging configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy, alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[logger_alembic]
+level = WARN
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/installation/tests/conftest.py b/docs/tutorials/wiki2/src/installation/tests/conftest.py
new file mode 100644
index 000000000..2db65f887
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tests/conftest.py
@@ -0,0 +1,125 @@
+import alembic
+import alembic.config
+import alembic.command
+import os
+from pyramid.paster import get_appsettings
+from pyramid.scripting import prepare
+from pyramid.testing import DummyRequest
+import pytest
+import transaction
+from webob.cookies import Cookie
+import webtest
+
+from tutorial import main
+from tutorial import models
+from tutorial.models.meta import Base
+
+
+def pytest_addoption(parser):
+    parser.addoption('--ini', action='store', metavar='INI_FILE')
+
+@pytest.fixture(scope='session')
+def ini_file(request):
+    # potentially grab this path from a pytest option
+    return os.path.abspath(request.config.option.ini or 'testing.ini')
+
+@pytest.fixture(scope='session')
+def app_settings(ini_file):
+    return get_appsettings(ini_file)
+
+@pytest.fixture(scope='session')
+def dbengine(app_settings, ini_file):
+    engine = models.get_engine(app_settings)
+
+    alembic_cfg = alembic.config.Config(ini_file)
+    Base.metadata.drop_all(bind=engine)
+    alembic.command.stamp(alembic_cfg, None, purge=True)
+
+    # run migrations to initialize the database
+    # depending on how we want to initialize the database from scratch
+    # we could alternatively call:
+    # Base.metadata.create_all(bind=engine)
+    # alembic.command.stamp(alembic_cfg, "head")
+    alembic.command.upgrade(alembic_cfg, "head")
+
+    yield engine
+
+    Base.metadata.drop_all(bind=engine)
+    alembic.command.stamp(alembic_cfg, None, purge=True)
+
+@pytest.fixture(scope='session')
+def app(app_settings, dbengine):
+    return main({}, dbengine=dbengine, **app_settings)
+
+@pytest.fixture
+def tm():
+    tm = transaction.TransactionManager(explicit=True)
+    tm.begin()
+    tm.doom()
+
+    yield tm
+
+    tm.abort()
+
+@pytest.fixture
+def dbsession(app, tm):
+    session_factory = app.registry['dbsession_factory']
+    return models.get_tm_session(session_factory, tm)
+
+@pytest.fixture
+def testapp(app, tm, dbsession):
+    # override request.dbsession and request.tm with our own
+    # externally-controlled values that are shared across requests but aborted
+    # at the end
+    testapp = webtest.TestApp(app, extra_environ={
+        'HTTP_HOST': 'example.com',
+        'tm.active': True,
+        'tm.manager': tm,
+        'app.dbsession': dbsession,
+    })
+
+    return testapp
+
+@pytest.fixture
+def app_request(app, tm, dbsession):
+    """
+    A real request.
+
+    This request is almost identical to a real request but it has some
+    drawbacks in tests as it's harder to mock data and is heavier.
+
+    """
+    env = prepare(registry=app.registry)
+    request = env['request']
+    request.host = 'example.com'
+
+    # without this, request.dbsession will be joined to the same transaction
+    # manager but it will be using a different sqlalchemy.orm.Session using
+    # a separate database transaction
+    request.dbsession = dbsession
+    request.tm = tm
+
+    yield request
+    env['closer']()
+
+@pytest.fixture
+def dummy_request(app, tm, dbsession):
+    """
+    A lightweight dummy request.
+
+    This request is ultra-lightweight and should be used only when the
+    request itself is not a large focus in the call-stack.
+
+    It is way easier to mock and control side-effects using this object.
+
+    - It does not have request extensions applied.
+    - Threadlocals are not properly pushed.
+
+    """
+    request = DummyRequest()
+    request.registry = app.registry
+    request.host = 'example.com'
+    request.dbsession = dbsession
+    request.tm = tm
+
+    return request
diff --git a/docs/tutorials/wiki2/src/installation/tests/test_functional.py b/docs/tutorials/wiki2/src/installation/tests/test_functional.py
new file mode 100644
index 000000000..dbcd8aec7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tests/test_functional.py
@@ -0,0 +1,13 @@
+from tutorial import models
+
+def test_my_view_success(testapp, dbsession):
+    model = models.MyModel(name='one', value=55)
+    dbsession.add(model)
+    dbsession.flush()
+
+    res = testapp.get('/', status=200)
+    assert res.body
+
+def test_notfound(testapp):
+    res = testapp.get('/badurl', status=404)
+    assert res.status_code == 404
diff --git a/docs/tutorials/wiki2/src/installation/tests/test_it.py b/docs/tutorials/wiki2/src/installation/tests/test_it.py
deleted file mode 100644
index ea16534fc..000000000
--- a/docs/tutorials/wiki2/src/installation/tests/test_it.py
+++ /dev/null
@@ -1,66 +0,0 @@
-import unittest
-
-from pyramid import testing
-
-import transaction
-
-
-def dummy_request(dbsession):
-    return testing.DummyRequest(dbsession=dbsession)
-
-
-class BaseTest(unittest.TestCase):
-    def setUp(self):
-        self.config = testing.setUp(settings={
-            'sqlalchemy.url': 'sqlite:///:memory:'
-        })
-        self.config.include('tutorial.models')
-        settings = self.config.get_settings()
-
-        from tutorial.models import (
-            get_engine,
-            get_session_factory,
-            get_tm_session,
-            )
-
-        self.engine = get_engine(settings)
-        session_factory = get_session_factory(self.engine)
-
-        self.session = get_tm_session(session_factory, transaction.manager)
-
-    def init_database(self):
-        from tutorial.models.meta import Base
-        Base.metadata.create_all(self.engine)
-
-    def tearDown(self):
-        from tutorial.models.meta import Base
-
-        testing.tearDown()
-        transaction.abort()
-        Base.metadata.drop_all(self.engine)
-
-
-class TestMyViewSuccessCondition(BaseTest):
-
-    def setUp(self):
-        super(TestMyViewSuccessCondition, self).setUp()
-        self.init_database()
-
-        from tutorial.models import MyModel
-
-        model = MyModel(name='one', value=55)
-        self.session.add(model)
-
-    def test_passing_view(self):
-        from tutorial.views.default import my_view
-        info = my_view(dummy_request(self.session))
-        self.assertEqual(info['one'].name, 'one')
-        self.assertEqual(info['project'], 'myproj')
-
-
-class TestMyViewFailureCondition(BaseTest):
-
-    def test_failing_view(self):
-        from tutorial.views.default import my_view
-        info = my_view(dummy_request(self.session))
-        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/installation/tests/test_views.py b/docs/tutorials/wiki2/src/installation/tests/test_views.py
new file mode 100644
index 000000000..8ae464d03
--- /dev/null
+++ b/docs/tutorials/wiki2/src/installation/tests/test_views.py
@@ -0,0 +1,23 @@
+from tutorial import models
+from tutorial.views.default import my_view
+from tutorial.views.notfound import notfound_view
+
+
+def test_my_view_failure(app_request):
+    info = my_view(app_request)
+    assert info.status_int == 500
+
+def test_my_view_success(app_request, dbsession):
+    model = models.MyModel(name='one', value=55)
+    dbsession.add(model)
+    dbsession.flush()
+
+    info = my_view(app_request)
+    assert app_request.response.status_int == 200
+    assert info['one'].name == 'one'
+    assert info['project'] == 'myproj'
+
+def test_notfound_view(app_request):
+    info = notfound_view(app_request)
+    assert app_request.response.status_int == 404
+    assert info == {}
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/__init__.py b/docs/tutorials/wiki2/src/installation/tutorial/__init__.py
index 5c2ba5cc0..7edc0957d 100644
--- a/docs/tutorials/wiki2/src/installation/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/installation/tutorial/__init__.py
@@ -5,8 +5,8 @@ def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
     with Configurator(settings=settings) as config:
-        config.include('.models')
         config.include('pyramid_jinja2')
         config.include('.routes')
+        config.include('.models')
         config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
index d8a273e9e..1c3ec5ee8 100644
--- a/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
@@ -65,13 +65,21 @@ def includeme(config):
     # use pyramid_retry to retry a request when transient exceptions occur
     config.include('pyramid_retry')
 
-    session_factory = get_session_factory(get_engine(settings))
+    # hook to share the dbengine fixture in testing
+    dbengine = settings.get('dbengine')
+    if not dbengine:
+        dbengine = get_engine(settings)
+
+    session_factory = get_session_factory(dbengine)
     config.registry['dbsession_factory'] = session_factory
 
     # make request.dbsession available for use in Pyramid
-    config.add_request_method(
-        # r.tm is the transaction manager used by pyramid_tm
-        lambda r: get_tm_session(session_factory, r.tm),
-        'dbsession',
-        reify=True
-    )
+    def dbsession(request):
+        # hook to share the dbsession fixture in testing
+        dbsession = request.environ.get('app.dbsession')
+        if dbsession is None:
+            # request.tm is the transaction manager used by pyramid_tm
+            dbsession = get_tm_session(session_factory, request.tm)
+        return dbsession
+
+    config.add_request_method(dbsession, reify=True)
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/views/default.py b/docs/tutorials/wiki2/src/installation/tutorial/views/default.py
index 094b2f303..a0f654d38 100644
--- a/docs/tutorials/wiki2/src/installation/tutorial/views/default.py
+++ b/docs/tutorials/wiki2/src/installation/tutorial/views/default.py
@@ -1,7 +1,6 @@
 from pyramid.view import view_config
 from pyramid.response import Response
-
-from sqlalchemy.exc import DBAPIError
+from sqlalchemy.exc import SQLAlchemyError
 
 from .. import models
 
@@ -10,8 +9,8 @@ from .. import models
 def my_view(request):
     try:
         query = request.dbsession.query(models.MyModel)
-        one = query.filter(models.MyModel.name == 'one').first()
-    except DBAPIError:
+        one = query.filter(models.MyModel.name == 'one').one()
+    except SQLAlchemyError:
         return Response(db_err_msg, content_type='text/plain', status=500)
     return {'one': one, 'project': 'myproj'}
 
diff --git a/docs/tutorials/wiki2/src/models/.gitignore b/docs/tutorials/wiki2/src/models/.gitignore
index 1853d983c..c612e59f2 100644
--- a/docs/tutorials/wiki2/src/models/.gitignore
+++ b/docs/tutorials/wiki2/src/models/.gitignore
@@ -19,3 +19,4 @@ Data.fs*
 .DS_Store
 coverage
 test
+*.sqlite
diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py
index 60234751a..fbd848136 100644
--- a/docs/tutorials/wiki2/src/models/setup.py
+++ b/docs/tutorials/wiki2/src/models/setup.py
@@ -19,8 +19,8 @@ requires = [
     'pyramid_tm',
     'SQLAlchemy',
     'transaction',
-    'zope.sqlalchemy',
     'waitress',
+    'zope.sqlalchemy',
 ]
 
 tests_require = [
diff --git a/docs/tutorials/wiki2/src/models/testing.ini b/docs/tutorials/wiki2/src/models/testing.ini
new file mode 100644
index 000000000..85e5e1ae9
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/testing.ini
@@ -0,0 +1,79 @@
+###
+# app configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
+[app:main]
+use = egg:tutorial
+
+pyramid.reload_templates = false
+pyramid.debug_authorization = false
+pyramid.debug_notfound = false
+pyramid.debug_routematch = false
+pyramid.default_locale_name = en
+
+sqlalchemy.url = sqlite:///%(here)s/testing.sqlite
+
+retry.attempts = 3
+
+[pshell]
+setup = tutorial.pshell.setup
+
+###
+# wsgi server configuration
+###
+
+[alembic]
+# path to migration scripts
+script_location = tutorial/alembic
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(rev)s
+# file_template = %%(rev)s_%%(slug)s
+
+[server:main]
+use = egg:waitress#main
+listen = *:6543
+
+###
+# logging configuration
+# https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
+
+[loggers]
+keys = root, tutorial, sqlalchemy, alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_tutorial]
+level = WARN
+handlers =
+qualname = tutorial
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+# "level = INFO" logs SQL queries.
+# "level = DEBUG" logs SQL queries and results.
+# "level = WARN" logs neither.  (Recommended for production systems.)
+
+[logger_alembic]
+level = WARN
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/models/tests/conftest.py b/docs/tutorials/wiki2/src/models/tests/conftest.py
new file mode 100644
index 000000000..2db65f887
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tests/conftest.py
@@ -0,0 +1,125 @@
+import alembic
+import alembic.config
+import alembic.command
+import os
+from pyramid.paster import get_appsettings
+from pyramid.scripting import prepare
+from pyramid.testing import DummyRequest
+import pytest
+import transaction
+from webob.cookies import Cookie
+import webtest
+
+from tutorial import main
+from tutorial import models
+from tutorial.models.meta import Base
+
+
+def pytest_addoption(parser):
+    parser.addoption('--ini', action='store', metavar='INI_FILE')
+
+@pytest.fixture(scope='session')
+def ini_file(request):
+    # potentially grab this path from a pytest option
+    return os.path.abspath(request.config.option.ini or 'testing.ini')
+
+@pytest.fixture(scope='session')
+def app_settings(ini_file):
+    return get_appsettings(ini_file)
+
+@pytest.fixture(scope='session')
+def dbengine(app_settings, ini_file):
+    engine = models.get_engine(app_settings)
+
+    alembic_cfg = alembic.config.Config(ini_file)
+    Base.metadata.drop_all(bind=engine)
+    alembic.command.stamp(alembic_cfg, None, purge=True)
+
+    # run migrations to initialize the database
+    # depending on how we want to initialize the database from scratch
+    # we could alternatively call:
+    # Base.metadata.create_all(bind=engine)
+    # alembic.command.stamp(alembic_cfg, "head")
+    alembic.command.upgrade(alembic_cfg, "head")
+
+    yield engine
+
+    Base.metadata.drop_all(bind=engine)
+    alembic.command.stamp(alembic_cfg, None, purge=True)
+
+@pytest.fixture(scope='session')
+def app(app_settings, dbengine):
+    return main({}, dbengine=dbengine, **app_settings)
+
+@pytest.fixture
+def tm():
+    tm = transaction.TransactionManager(explicit=True)
+    tm.begin()
+    tm.doom()
+
+    yield tm
+
+    tm.abort()
+
+@pytest.fixture
+def dbsession(app, tm):
+    session_factory = app.registry['dbsession_factory']
+    return models.get_tm_session(session_factory, tm)
+
+@pytest.fixture
+def testapp(app, tm, dbsession):
+    # override request.dbsession and request.tm with our own
+    # externally-controlled values that are shared across requests but aborted
+    # at the end
+    testapp = webtest.TestApp(app, extra_environ={
+        'HTTP_HOST': 'example.com',
+        'tm.active': True,
+        'tm.manager': tm,
+        'app.dbsession': dbsession,
+    })
+
+    return testapp
+
+@pytest.fixture
+def app_request(app, tm, dbsession):
+    """
+    A real request.
+
+    This request is almost identical to a real request but it has some
+    drawbacks in tests as it's harder to mock data and is heavier.
+
+    """
+    env = prepare(registry=app.registry)
+    request = env['request']
+    request.host = 'example.com'
+
+    # without this, request.dbsession will be joined to the same transaction
+    # manager but it will be using a different sqlalchemy.orm.Session using
+    # a separate database transaction
+    request.dbsession = dbsession
+    request.tm = tm
+
+    yield request
+    env['closer']()
+
+@pytest.fixture
+def dummy_request(app, tm, dbsession):
+    """
+    A lightweight dummy request.
+
+    This request is ultra-lightweight and should be used only when the
+    request itself is not a large focus in the call-stack.
+
+    It is way easier to mock and control side-effects using this object.
+
+    - It does not have request extensions applied.
+    - Threadlocals are not properly pushed.
+
+    """
+    request = DummyRequest()
+    request.registry = app.registry
+    request.host = 'example.com'
+    request.dbsession = dbsession
+    request.tm = tm
+
+    return request
diff --git a/docs/tutorials/wiki2/src/models/tests/test_functional.py b/docs/tutorials/wiki2/src/models/tests/test_functional.py
new file mode 100644
index 000000000..dbcd8aec7
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tests/test_functional.py
@@ -0,0 +1,13 @@
+from tutorial import models
+
+def test_my_view_success(testapp, dbsession):
+    model = models.MyModel(name='one', value=55)
+    dbsession.add(model)
+    dbsession.flush()
+
+    res = testapp.get('/', status=200)
+    assert res.body
+
+def test_notfound(testapp):
+    res = testapp.get('/badurl', status=404)
+    assert res.status_code == 404
diff --git a/docs/tutorials/wiki2/src/models/tests/test_it.py b/docs/tutorials/wiki2/src/models/tests/test_it.py
deleted file mode 100644
index ea16534fc..000000000
--- a/docs/tutorials/wiki2/src/models/tests/test_it.py
+++ /dev/null
@@ -1,66 +0,0 @@
-import unittest
-
-from pyramid import testing
-
-import transaction
-
-
-def dummy_request(dbsession):
-    return testing.DummyRequest(dbsession=dbsession)
-
-
-class BaseTest(unittest.TestCase):
-    def setUp(self):
-        self.config = testing.setUp(settings={
-            'sqlalchemy.url': 'sqlite:///:memory:'
-        })
-        self.config.include('tutorial.models')
-        settings = self.config.get_settings()
-
-        from tutorial.models import (
-            get_engine,
-            get_session_factory,
-            get_tm_session,
-            )
-
-        self.engine = get_engine(settings)
-        session_factory = get_session_factory(self.engine)
-
-        self.session = get_tm_session(session_factory, transaction.manager)
-
-    def init_database(self):
-        from tutorial.models.meta import Base
-        Base.metadata.create_all(self.engine)
-
-    def tearDown(self):
-        from tutorial.models.meta import Base
-
-        testing.tearDown()
-        transaction.abort()
-        Base.metadata.drop_all(self.engine)
-
-
-class TestMyViewSuccessCondition(BaseTest):
-
-    def setUp(self):
-        super(TestMyViewSuccessCondition, self).setUp()
-        self.init_database()
-
-        from tutorial.models import MyModel
-
-        model = MyModel(name='one', value=55)
-        self.session.add(model)
-
-    def test_passing_view(self):
-        from tutorial.views.default import my_view
-        info = my_view(dummy_request(self.session))
-        self.assertEqual(info['one'].name, 'one')
-        self.assertEqual(info['project'], 'myproj')
-
-
-class TestMyViewFailureCondition(BaseTest):
-
-    def test_failing_view(self):
-        from tutorial.views.default import my_view
-        info = my_view(dummy_request(self.session))
-        self.assertEqual(info.status_int, 500)
diff --git a/docs/tutorials/wiki2/src/models/tests/test_views.py b/docs/tutorials/wiki2/src/models/tests/test_views.py
new file mode 100644
index 000000000..8ae464d03
--- /dev/null
+++ b/docs/tutorials/wiki2/src/models/tests/test_views.py
@@ -0,0 +1,23 @@
+from tutorial import models
+from tutorial.views.default import my_view
+from tutorial.views.notfound import notfound_view
+
+
+def test_my_view_failure(app_request):
+    info = my_view(app_request)
+    assert info.status_int == 500
+
+def test_my_view_success(app_request, dbsession):
+    model = models.MyModel(name='one', value=55)
+    dbsession.add(model)
+    dbsession.flush()
+
+    info = my_view(app_request)
+    assert app_request.response.status_int == 200
+    assert info['one'].name == 'one'
+    assert info['project'] == 'myproj'
+
+def test_notfound_view(app_request):
+    info = notfound_view(app_request)
+    assert app_request.response.status_int == 404
+    assert info == {}
diff --git a/docs/tutorials/wiki2/src/models/tutorial/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
index 5c2ba5cc0..7edc0957d 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
@@ -5,8 +5,8 @@ def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
     with Configurator(settings=settings) as config:
-        config.include('.models')
         config.include('pyramid_jinja2')
         config.include('.routes')
+        config.include('.models')
         config.scan()
     return config.make_wsgi_app()
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
index a4209a6e9..47d77ef01 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
@@ -66,13 +66,21 @@ def includeme(config):
     # use pyramid_retry to retry a request when transient exceptions occur
     config.include('pyramid_retry')
 
-    session_factory = get_session_factory(get_engine(settings))
+    # hook to share the dbengine fixture in testing
+    dbengine = settings.get('dbengine')
+    if not dbengine:
+        dbengine = get_engine(settings)
+
+    session_factory = get_session_factory(dbengine)
     config.registry['dbsession_factory'] = session_factory
 
     # make request.dbsession available for use in Pyramid
-    config.add_request_method(
-        # r.tm is the transaction manager used by pyramid_tm
-        lambda r: get_tm_session(session_factory, r.tm),
-        'dbsession',
-        reify=True
-    )
+    def dbsession(request):
+        # hook to share the dbsession fixture in testing
+        dbsession = request.environ.get('app.dbsession')
+        if dbsession is None:
+            # request.tm is the transaction manager used by pyramid_tm
+            dbsession = get_tm_session(session_factory, request.tm)
+        return dbsession
+
+    config.add_request_method(dbsession, reify=True)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/initialize_db.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initialize_db.py
index e6350fb36..c8034e5a5 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/scripts/initialize_db.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initialize_db.py
@@ -8,6 +8,10 @@ from .. import models
 
 
 def setup_models(dbsession):
+    """
+    Add or update models / fixtures in the database.
+
+    """
     editor = models.User(name='editor', role='editor')
     editor.set_password('editor')
     dbsession.add(editor)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/views/default.py b/docs/tutorials/wiki2/src/models/tutorial/views/default.py
index 094b2f303..a0f654d38 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/views/default.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/views/default.py
@@ -1,7 +1,6 @@
 from pyramid.view import view_config
 from pyramid.response import Response
-
-from sqlalchemy.exc import DBAPIError
+from sqlalchemy.exc import SQLAlchemyError
 
 from .. import models
 
@@ -10,8 +9,8 @@ from .. import models
 def my_view(request):
     try:
         query = request.dbsession.query(models.MyModel)
-        one = query.filter(models.MyModel.name == 'one').first()
-    except DBAPIError:
+        one = query.filter(models.MyModel.name == 'one').one()
+    except SQLAlchemyError:
         return Response(db_err_msg, content_type='text/plain', status=500)
     return {'one': one, 'project': 'myproj'}