@@ -20,9 +20,11 @@ transactions using [Flask-SQLAlchemy](http://flask-sqlalchemy.pocoo.org/latest/)
20
20
- [ ` mocked-engines ` ] ( #mocked-engines )
21
21
- [ ` mocked-sessions ` ] ( #mocked-sessions )
22
22
- [ ` mocked-sessionmakers ` ] ( #mocked-sessionmakers )
23
+ - [ Writing transactional tests] ( #writing-transactional-tests )
23
24
- [ Fixtures] ( #fixtures )
24
25
- [ ` db_session ` ] ( #db_session )
25
26
- [ ` db_engine ` ] ( #db_engine )
27
+ - [ Enabling transactions without fixtures] ( #enabling-transactions-without-fixtures )
26
28
- [ ** Development** ] ( #development )
27
29
- [ Running the tests] ( #running-the-tests )
28
30
- [ Acknowledgements] ( #acknowledgements )
@@ -277,7 +279,7 @@ engine = sqlalchemy.create_engine(DATABASE_URI)
277
279
``` ini
278
280
# In setup.cfg
279
281
280
- [pytest]
282
+ [tool: pytest]
281
283
mocked-engines =database.engine
282
284
```
283
285
@@ -286,7 +288,7 @@ To patch multiple objects at once, separate the paths with a whitespace:
286
288
``` ini
287
289
# In setup.cfg
288
290
289
- [pytest]
291
+ [tool: pytest]
290
292
mocked-engines =database.engine database.second_engine
291
293
```
292
294
@@ -312,7 +314,7 @@ db = SQLAlchemy()
312
314
``` ini
313
315
# In setup.cfg
314
316
315
- [pytest]
317
+ [tool: pytest]
316
318
mocked-sessions =database.db.session
317
319
```
318
320
@@ -321,7 +323,7 @@ To patch multiple objects at once, separate the paths with a whitespace:
321
323
``` ini
322
324
# In setup.cfg
323
325
324
- [pytest]
326
+ [tool: pytest]
325
327
mocked-sessions =database.db.session database.second_db.session
326
328
```
327
329
@@ -347,17 +349,48 @@ WorkerSessionmaker = sessionmaker()
347
349
```
348
350
349
351
``` ini
350
- [pytest]
352
+ [tool: pytest]
351
353
mocked-sessionmakers =database.WorkerSessionmaker
352
354
```
353
355
354
356
To patch multiple objects at once, separate the paths with a whitespace.
355
357
356
358
``` ini
357
- [pytest]
359
+ [tool: pytest]
358
360
mocked-sessionmakers =database.WorkerSessionmaker database.SecondWorkerSessionmaker
359
361
```
360
362
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
+
361
394
## <a name =" fixtures " ></a >Fixtures
362
395
363
396
This plugin provides two fixtures for performing database updates inside nested
@@ -426,6 +459,27 @@ def test_transaction_doesnt_persist(db_engine):
426
459
assert row_name != ' testing'
427
460
```
428
461
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
+
429
483
# <a name =" development " ></a >Development
430
484
431
485
## <a name =" running-the-tests " ></a >Running the tests
@@ -469,6 +523,6 @@ efforts. Thanks to Igor, the plugin name is much stronger.
469
523
470
524
## <a name =" copyright " ></a >Copyright
471
525
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.
473
527
474
528
Third-party copyright in this distribution is noted where applicable.
0 commit comments