Raise an error if the user doesn't define a _db fixture

Author: jeancochrane

README.md

@@ -87,7 +87,7 @@ mocked-engines=database.engine
 # In database.py
 
 db = flask_sqlalchemy.SQLAlchemy()
-engine = sqlalchemy.create_engine('db_connection_string')
+engine = sqlalchemy.create_engine('DATABASE_URI')
 ```
 
 ```python
@@ -489,7 +489,9 @@ Next, install a development version of the plugin:
 pip install -e .
 ```
 
-Export a database connection string that the tests can use:
+Export a [database connection string](http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls)
+that the tests can use (the database referenced by the string will be created
+during test setup, so it does not need to exist):
 
 ```
 export TEST_DATABASE_URL=<db_connection_string>

tests/test_configs.py

@@ -59,3 +59,77 @@ def test_mocked_sessionmakers(db_session):
 
     result = db_testdir.runpytest()
     result.assert_outcomes(passed=1)
+
+
+def test_missing_db_fixture(testdir):
+    '''
+    Test that in the case where the user neglects to define a _db fixture, any
+    tests requiring transactional context will raise an error.
+    '''
+    # Create a conftest file that is missing a _db fixture but is otherwise
+    # valid for a Flask-SQLAlchemy test suite
+    conftest = """
+        import os
+
+        import pytest
+        import sqlalchemy as sa
+        from flask import Flask
+        from flask_sqlalchemy import SQLAlchemy
+        from pytest_postgresql.factories import (init_postgresql_database,
+                                                drop_postgresql_database)
+
+        # Retrieve a database connection string from the shell environment
+        try:
+            DB_CONN = os.environ['TEST_DATABASE_URL']
+        except KeyError:
+            raise KeyError('TEST_DATABASE_URL not found. You must export a database ' +
+                        'connection string to the environmental variable ' +
+                        'TEST_DATABASE_URL in order to run tests.')
+        else:
+            DB_OPTS = sa.engine.url.make_url(DB_CONN).translate_connect_args()
+
+        pytest_plugins = ['pytest-flask-sqlalchemy-transactions']
+
+
+        @pytest.fixture(scope='session')
+        def database(request):
+            '''
+            Create a Postgres database for the tests, and drop it when the tests are done.
+            '''
+            pg_host = DB_OPTS.get("host")
+            pg_port = DB_OPTS.get("port")
+            pg_user = DB_OPTS.get("username")
+            pg_db = DB_OPTS["database"]
+
+            init_postgresql_database(pg_user, pg_host, pg_port, pg_db)
+
+            @request.addfinalizer
+            def drop_database():
+                drop_postgresql_database(pg_user, pg_host, pg_port, pg_db, 9.6)
+
+
+        @pytest.fixture(scope='session')
+        def app(database):
+            '''
+            Create a Flask app context for the tests.
+            '''
+            app = Flask(__name__)
+
+            app.config['SQLALCHEMY_DATABASE_URI'] = DB_CONN
+
+            return app
+    """
+
+    testdir.makeconftest(conftest)
+
+    # Define a test that will always pass, assuming that fixture setup works
+    testdir.makepyfile("""
+        def test_missing_db_fixture(db_session):
+            assert True
+    """)
+
+    result = testdir.runpytest()
+    result.assert_outcomes(error=1)
+    result.stdout.fnmatch_lines([
+        '*NotImplementedError: _db fixture not defined*'
+    ])

transactions/fixtures.py

@@ -5,6 +5,22 @@
 import sqlalchemy as sa
 
 
+@pytest.fixture(scope='module')
+def _db():
+    '''
+    A user-defined _db fixture is required to provide the plugin with a SQLAlchemy
+    Session object that can access the test database. If the user hasn't defined
+    that fixture, raise an error.
+    '''
+    msg = ("_db fixture not defined. The pytest-flask-sqlalchemy-transactions plugin " +
+           "requires you to define a _db fixture that returns a SQLAlchemy session " +
+           "with access to your test database. For more information, see the plugin " +
+           "documentation: " +
+           "https://github.com/jeancochrane/pytest-flask-sqlalchemy-transactions#conftest-setup")
+
+    raise NotImplementedError(msg)
+
+
 @pytest.fixture(scope='function')
 def _transaction(request, _db, mocker):
     '''

transactions/hooks.py

@@ -9,4 +9,3 @@ def pytest_collection_modifyitems(items):
     for item in items:
         if item.get_marker('transactional'):
             item.fixturenames.append('db_session')
-

transactions/plugin.py

@@ -1,4 +1,4 @@
-from .fixtures import _transaction, _engine, _session, db_session, db_engine
+from .fixtures import _db, _transaction, _engine, _session, db_session, db_engine
 from .hooks import pytest_collection_modifyitems
 
 def pytest_addoption(parser):