Skip to content

Commit 7e1e9e4

Browse files
authored
Clarify relationship between fixtures and transactions
Previously, the docs only mentioned once that importing one of the transactional fixtures is required in order to enable transactions for a test. Clarify this point with two new sections, "Writing transactional tests" and "Enabling transactions for all tests". Also: Update the copyright date.
1 parent e4c6a3f commit 7e1e9e4

File tree

1 file changed

+61
-7
lines changed

1 file changed

+61
-7
lines changed

README.md

Lines changed: 61 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,11 @@ transactions using [Flask-SQLAlchemy](http://flask-sqlalchemy.pocoo.org/latest/)
2020
- [`mocked-engines`](#mocked-engines)
2121
- [`mocked-sessions`](#mocked-sessions)
2222
- [`mocked-sessionmakers`](#mocked-sessionmakers)
23+
- [Writing transactional tests](#writing-transactional-tests)
2324
- [Fixtures](#fixtures)
2425
- [`db_session`](#db_session)
2526
- [`db_engine`](#db_engine)
27+
- [Enabling transactions without fixtures](#enabling-transactions-without-fixtures)
2628
- [**Development**](#development)
2729
- [Running the tests](#running-the-tests)
2830
- [Acknowledgements](#acknowledgements)
@@ -277,7 +279,7 @@ engine = sqlalchemy.create_engine(DATABASE_URI)
277279
```ini
278280
# In setup.cfg
279281

280-
[pytest]
282+
[tool:pytest]
281283
mocked-engines=database.engine
282284
```
283285

@@ -286,7 +288,7 @@ To patch multiple objects at once, separate the paths with a whitespace:
286288
```ini
287289
# In setup.cfg
288290

289-
[pytest]
291+
[tool:pytest]
290292
mocked-engines=database.engine database.second_engine
291293
```
292294

@@ -312,7 +314,7 @@ db = SQLAlchemy()
312314
```ini
313315
# In setup.cfg
314316

315-
[pytest]
317+
[tool:pytest]
316318
mocked-sessions=database.db.session
317319
```
318320

@@ -321,7 +323,7 @@ To patch multiple objects at once, separate the paths with a whitespace:
321323
```ini
322324
# In setup.cfg
323325

324-
[pytest]
326+
[tool:pytest]
325327
mocked-sessions=database.db.session database.second_db.session
326328
```
327329

@@ -347,17 +349,48 @@ WorkerSessionmaker = sessionmaker()
347349
```
348350

349351
```ini
350-
[pytest]
352+
[tool:pytest]
351353
mocked-sessionmakers=database.WorkerSessionmaker
352354
```
353355

354356
To patch multiple objects at once, separate the paths with a whitespace.
355357

356358
```ini
357-
[pytest]
359+
[tool:pytest]
358360
mocked-sessionmakers=database.WorkerSessionmaker database.SecondWorkerSessionmaker
359361
```
360362

363+
### <a name="writing-transactional-tests"></a>Writing transactional tests
364+
365+
Once you have your [conftest file set up](#conftest-setup) and you've [overrided the
366+
necessary connectables in your test configuration](#test-configuration), you're ready
367+
to write some transactional tests. Simply import one of the module's [transactional
368+
fixtures](#fixtures) in your test signature, and the test will be wrapped in a transaction.
369+
370+
Note that by default, **tests are only wrapped in transactions if they import one of
371+
the [transactional fixtures](#fixtures) provided by this module.** Tests that do not
372+
import the fixture will interact with your database without opening a transaction:
373+
374+
```python
375+
# This test will be wrapped in a transaction.
376+
def transactional_test(db_session):
377+
...
378+
379+
# This test **will not** be wrapped in a transaction, since it does not import a
380+
# transactional fixture.
381+
def non_transactional_test():
382+
...
383+
```
384+
385+
The fixtures provide a way for you to control which tests require transactions and
386+
which don't. This is often useful, since avoiding transaction setup can speed up
387+
tests that don't interact with your database.
388+
389+
For more information about the transactional fixtures provided by this module, read on
390+
to the [fixtures section](#fixtures). For guidance on how to automatically enable
391+
transactions without having to specify fixtures, see the section on [enabling transactions
392+
without fixtures](#enabling-transactions-without-fixtures).
393+
361394
## <a name="fixtures"></a>Fixtures
362395

363396
This plugin provides two fixtures for performing database updates inside nested
@@ -426,6 +459,27 @@ def test_transaction_doesnt_persist(db_engine):
426459
assert row_name != 'testing'
427460
```
428461

462+
## <a name="enabling-transactions-without-fixtures"></a>Enabling transactions without fixtures
463+
464+
If you know you want to make all of your tests transactional, it can be annoying to have
465+
to specify one of the [fixtures](#fixtures) in every test signature.
466+
467+
The best way to automatically enable transactions without having to include an extra fixture
468+
in every test is to wire up an
469+
[autouse fixture](https://docs.pytest.org/en/latest/fixture.html#autouse-fixtures-xunit-setup-on-steroids)
470+
for your test suite. This can be as simple as:
471+
472+
```python
473+
# Automatically enable transactions for all tests, without importing any extra fixtures.
474+
@pytest.fixture(autouse=True)
475+
def enable_transactional_tests(db_session):
476+
pass
477+
```
478+
479+
In this configuration, the `enable_transactional_tests` fixture will be automatically used in
480+
all tests, meaning that `db_session` will also be used. This way, all tests will be wrapped
481+
in transactions without having to explicitly require either `db_session` or `enable_transactional_tests`.
482+
429483
# <a name="development"></a>Development
430484

431485
## <a name="running-the-tests"></a>Running the tests
@@ -469,6 +523,6 @@ efforts. Thanks to Igor, the plugin name is much stronger.
469523

470524
## <a name="copyright"></a>Copyright
471525

472-
Copyright (c) 2018 Jean Cochrane and DataMade. Released under the MIT License.
526+
Copyright (c) 2019 Jean Cochrane and DataMade. Released under the MIT License.
473527

474528
Third-party copyright in this distribution is noted where applicable.

0 commit comments

Comments
 (0)