test_data 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 492abd0bddc1329c073d45cb984dd60aa374f3520c6d3362bec34ece165f0407
-  data.tar.gz: efee863beeba57aa27e98d8b833ca0398d022baaa710b8a741d8da3995a71dce
+  metadata.gz: 8c9bcdeaebcbad6163fb495b327408b64f7d85f90efd7ab171275ba4fd61e484
+  data.tar.gz: c08433086b9cfcb57e88e275e63f8600083945afdd738962a952e94573b95f77
 SHA512:
-  metadata.gz: 1796bcb024853380c7a387f5f69d8b564ca78c4318fbf0a3c526546c5000fb5f676cc846a0541443c5d53e664f3b74d1970df4526d12b7f931209e9d78cdb684
-  data.tar.gz: b77b0c1a24a806ac817d516173a6f68b9e7d63ca088bae6cc32de41c688df0c296a1eedf7e7bde81ce46faba76301b98fde0f1fd1a2ccc1842f9095fdbafc132
+  metadata.gz: e69305fb469eab8714569cea4b57fb6a3b9050ea97065230ef86afa27e8c089d094b75673515348e31f8ec989a61924fb7924d70c21fdbd31decdef8e490459e
+  data.tar.gz: 1592fccf3753f33c74f449ad2debe029806778383fd07f089c9bb67e49861e5a3885d04497720dd04525511182ca8b87ff6774c90837845204f210d85f3db270

data/.github/workflows/ruby.yml

@@ -7,11 +7,7 @@
 
 name: Ruby
 
-on:
-  push:
-    branches: [ master ]
-  pull_request:
-    branches: [ master ]
+on: [push, pull_request, workflow_dispatch]
 
 jobs:
   test:

data/.standard.yml

@@ -0,0 +1,2 @@
+ruby_version: 2.4.0
+

data/CHANGELOG.md

@@ -1,4 +1,41 @@
-# unreleased
+# 0.3.0
+
+- Add a `test_data:reinitialize` task that will delete the `test_data` database
+  if necessary before invoking `test_data:initialize`
+  - Warn if re-initializing and the local database appears to have been dumped
+    or loaded from a dump that is newer than the dumps on disk
+- Add a warning on app load if the dumps on disk appear
+  newer than the local `test_data` database
+
+# 0.2.2
+
+- Improve performance of Rails fixtures being repeatedly loaded by changing the
+caching strategy
+
+# 0.2.1
+
+- Adds several lifecycle hooks:
+  - config.after_test_data_load
+  - config.after_test_data_truncate
+  - config.after_rails_fixture_load
+
+# 0.2.0
+
+- BREAKING CHANGES: Remove or rename a bunch of APIs that aren't quite necessary
+  and leak too much implementation, requiring too much cognitive load for users.
+  - Remove config.use_transactional_data_loader
+  - Remove TestData.rollback
+  - Change TestData.load to TestData.uses_test_data and make it transaction-only
+  - Change TestData.truncate to TestData.uses_clean_slate and make it
+    transaction-only
+  - Change TestData.load_rails_fixtures to TestData.uses_rails_fixtures and make
+    it transaction-only
+  - Add TestData.insert_test_data_dump, which will blindly insert the test SQL
+    dump of test data without any transaction management
+- [#2](https://github.com/testdouble/test_data/issues/2) - Work around
+  hard-coded environment names when initializing test_data environment secrets
+
+# 0.1.0
 
 - New feature: `TestData.load_rails_fixtures` to override default fixtures
   behavior by loading it in a nested transaction after `TestData.truncate`

data/Gemfile.lock

@@ -1,26 +1,26 @@
 PATH
   remote: .
   specs:
-    test_data (0.1.0)
+    test_data (0.3.0)
       railties (~> 6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (6.1.4)
-      actionview (= 6.1.4)
-      activesupport (= 6.1.4)
+    actionpack (6.1.4.1)
+      actionview (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
       rack (~> 2.0, >= 2.0.9)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actionview (6.1.4)
-      activesupport (= 6.1.4)
+    actionview (6.1.4.1)
+      activesupport (= 6.1.4.1)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activesupport (6.1.4)
+    activesupport (6.1.4.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -34,14 +34,14 @@ GEM
     erubi (1.10.0)
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
-    loofah (2.10.0)
+    loofah (2.12.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     method_source (1.0.0)
-    mini_portile2 (2.5.3)
+    mini_portile2 (2.6.1)
     minitest (5.14.4)
-    nokogiri (1.11.7)
-      mini_portile2 (~> 2.5.0)
+    nokogiri (1.12.4)
+      mini_portile2 (~> 2.6.1)
       racc (~> 1.4)
     parallel (1.20.1)
     parser (3.0.1.0)
@@ -56,11 +56,11 @@ GEM
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.3.0)
+    rails-html-sanitizer (1.4.2)
       loofah (~> 2.3)
-    railties (6.1.4)
-      actionpack (= 6.1.4)
-      activesupport (= 6.1.4)
+    railties (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
       method_source
       rake (>= 0.13)
       thor (~> 1.0)

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2022 Test Double, LLC
+Copyright (c) 2021 Test Double, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -18,23 +18,24 @@ What it does:
   files, no precarious approximations of realism: **real data created by your
   app**
 
-* Exposes a simple API for loading your test data and cleaning up between
-  tests. Common edge cases are handled seamlessly. Tests that need access to
-  your data will see it and tests that don't, won't
+* Exposes a simple API for ensuring that your data will be pristine for each of
+  your tests, whether the test depends on test_data, an empty database, or Rails
+  fixtures
 
 * Safeguards your tests from flaky failures and supercharges your build by
   providing a sophisticated transaction manager that isolates each test while
   ensuring your data is only loaded once
 
 If you've despaired over the seeming inevitability that all Rails test suites
-will eventually grow to become slow, incomprehensible, and brittle, then this
-gem is for you! And even if you're [a factory_bot
+will eventually grow to become slow, flaky, and incomprehensible, then this gem
+is for you! And even if you're [a factory_bot
 fan](https://twitter.com/searls/status/1379491813099253762?s=20), we hope you'll
 be open to the idea that [there might be a better way](
 #but-we-use-and-like-factory_bot-and-so-i-am-inclined-to-dislike-everything-about-this-gem).
 
 _[Full disclosure: because the gem is still brand new, it makes a number of
-[assumptions](#assumptions) and may not work for every project just yet.]_
+[assumptions](#assumptions)—chief among them being that **Postgres & Rails 6+
+are required**—so it may not work for every project just yet.]_
 
 ## Documentation
 
@@ -42,21 +43,17 @@ This gem requires a lot of documentation—not because `test_data` does a lot of
 things, but because managing one's test data is an inherently complex task. If
 one reason Rails apps chronically suffer from slow tests is that other
 approaches oversimplify test data management, it stands to reason that any
-discomfort caused by `test_data`'s scope may not indicate _unnecessary
-complexity_ so much as highlight how much acclimatization is needed to adopt the
-necessary diligence to achieve fast, isolated tests that scale with your
-application.
+discomfort caused by `test_data`'s scope may not be _unnecessary complexity_ but
+instead be an indication of how little of the problem's _essential complexity_
+we have reckoned with to this point.
 
 1. [Getting Started Guide](#getting-started-guide)
-    1. [Install and initialize
-       `test_data`](#step-1-install-and-initialize-test_data)
+    1. [Install and initialize `test_data`](#step-1-install-and-initialize-test_data)
     2. [Create some test data](#step-2-create-some-test-data)
     3. [Dump your `test_data` database](#step-3-dump-your-test_data-database)
     4. [Load your data in your tests](#step-4-load-your-data-in-your-tests)
-    5. [Keeping your test data
-       up-to-date](#step-5-keeping-your-test-data-up-to-date)
-2. [Factory & Fixture Interoperability
-   Guide](#factory--fixture-interoperability-guide)
+    5. [Keeping your test data up-to-date](#step-5-keeping-your-test-data-up-to-date)
+2. [Factory & Fixture Interoperability Guide](#factory--fixture-interoperability-guide)
     * [Using `test_data` with `factory_bot`](#using-test_data-with-factory_bot)
     * [Using `test_data` with Rails fixtures](#using-test_data-with-rails-fixtures)
 3. [Rake Task Reference](#rake-task-reference)
@@ -64,23 +61,32 @@ application.
     * [test_data:configure](#test_dataconfigure)
     * [test_data:verify_config](#test_dataverify_config)
     * [test_data:initialize](#test_datainitialize)
+    * [test_data:reinitialize](#test_datareinitialize)
     * [test_data:dump](#test_datadump)
     * [test_data:load](#test_dataload)
     * [test_data:create_database](#test_datacreate_database)
     * [test_data:drop_database](#test_datadrop_database)
 4. [API Reference](#api-reference)
+    * [TestData.uses_test_data](#testdatauses_test_data)
+    * [TestData.uses_clean_slate](#testdatauses_clean_slate)
+    * [TestData.uses_rails_fixtures(self)](#testdatauses_rails_fixtures)
+        * [TestData.prevent_rails_fixtures_from_loading_automatically!](#testdataprevent_rails_fixtures_from_loading_automatically)
     * [TestData.config](#testdataconfig)
-    * [TestData.load](#testdataload)
-    * [TestData.rollback](#testdatarollback)
-        * [TestData.rollback(:before_data_load)](#rolling-back-to-before-test-data-was-loaded)
-        * [TestData.rollback(:after_data_load)](#rolling-back-to-after-the-data-was-loaded)
-        * [TestData.rollback(:after_data_truncate)](#rolling-back-to-after-test-data-was-truncated)
-        * [TestData.rollback(:after_load_rails_fixtures)](#rolling-back-to-after-rails-fixtures-were-loaded)
-    * [TestData.truncate](#testdatatruncate)
-    * [TestData.prevent_rails_fixtures_from_loading_automatically!](#testdataprevent_rails_fixtures_from_loading_automatically)
-    * [TestData.load_rails_fixtures](#testdataload_rails_fixtures)
+    * [TestData.insert_test_data_dump](#testdatainsert_test_data_dump)
 5. [Assumptions](#assumptions)
 6. [Fears, Uncertainties, and Doubts](#fears-uncertainties-and-doubts) (Q & A)
+    * [But we're already happy with
+      factory_bot!](#but-we-use-and-like-factory_bot-and-so-i-am-inclined-to-dislike-everything-about-this-gem)
+    * [How will we handle merge conflicts in the schema
+      dumps?](#how-will-i-handle-merge-conflicts-in-these-sql-files-if-i-have-lots-of-people-working-on-lots-of-feature-branches-all-adding-to-the-test_data-database-dumps)
+    * [Why can't I manage different SQL dumps for different
+      scenarios?](#why-cant-i-save-multiple-database-dumps-to-cover-different-scenarios)
+    * [These SQL dumps are way too large to commit to
+      git!](#are-you-sure-i-should-commit-these-sql-dumps-theyre-way-too-big)
+    * [Tests shouldn't rely on shared test data if they don't need
+      to](#tests-shouldnt-use-shared-test-data-they-should-instantiate-the-objects-they-need)
+    * [My tests aren't as fast as they should
+      be](#im-worried-my-tests-arent-as-fast-as-they-should-be)
 7. [Code of Conduct](#code-of-conduct)
 8. [Changelog](/CHANGELOG.md)
 9. [MIT License](/LICENSE.txt)
@@ -140,21 +146,20 @@ Created database 'yourappname_test_data'
 ------------
 
 (1 row)
-````
 
-The purpose of the `test_data` database is to provide a sandbox in which to
-generate test data by interacting with your app and then dumping the resulting
-state of the database so that your tests can load it later. Rather than try to
-imitate realistic data using factories and fixtures (a task which only grows
-more difficult as your models and their associations increase in complexity),
-your test data will always be realistic because your real application will have
-created it!
+Your test_data environment and database are ready for use! You can now run
+your server (or any command) to create some test data like so:
+
+  $ RAILS_ENV=test_data bin/rails server
+
+````
 
-The database dumps are meant to be committed in git and versioned alongside your
-tests over the life of the application. Its schema & data are should be
-incrementally migrated over time, just like your production database. (As a
-happy side effect, this means your `test_data` database may help you identify
-hard-to-catch migration bugs early, before being deployed to production!)
+The purpose of the `test_data` database is to provide a sandbox in which you
+will manually generate test data by playing around with your app. Rather than
+try to imitate realistic data using factories and fixtures (a task which only
+grows more difficult as your models and their associations increase in
+complexity), your test data will always be realistic because your real
+application will have created it!
 
 ### Step 2: Create some test data
 
@@ -181,31 +186,47 @@ number of Rails commands or Rake tasks against its database by setting
 
 _[Aside: If you experience any hiccups in getting your server to work, please
 [open an issue](https://github.com/testdouble/test_data/issues/new) and let us
-know—it may present an opportunity to improve the `test_data:configure` task!]_
+know—it may present an opportunity for us to improve the `test_data:configure`
+task!]_
 
 #### Create test data by using your app
 
 Once the app is running, it's time to generate some test data. You'll know how
 to accomplish this step better than anyone—it's your app, after all!
 
-Our advice? Spend a little time thoughtfully navigating each feature of your app
-in order to generate enough data to be _representative_ of what would be needed
-to test your system's main behaviors (e.g. one `User` for each role, one of each
-kind of `Order`, etc.), while still being _minimal_ enough that the universe of
-data will be comprehensible & memorable to yourself and your teammates. It can
-also help to give new records memorable names, perhaps in keeping with a common
-theme (easier to refer to "Rafael" than "TestUser #1").
-
-If you make a mistake, it's perfectly okay to reset the database and start over!
-Your future tests will be coupled to this data as your application grows and
-evolves, so it's worth taking the time to ensure the foundation is solid. (But
-that's not to say everything needs to be perfect; you can always change things
-or add more data later—you'll just have to update your tests accordingly.)
+A few bits of advice click & type some test data into existence:
+
+* Spend a little time thoughtfully navigating each feature of your app in order
+  to generate enough data to be representative of what would be needed to test
+  them (e.g. one `User` per role, one of each kind of `Order`, etc.)
+* Less is more: the less test data you create, the more meaningful & memorable
+  it will be to yourself and your teammates when writing tests. Don't keep
+  adding test data unless it will allow you to exercise additional application
+  code (e.g. enough `Project` models to require pagination, but not hundreds of
+  them for the sake of looking "production-like")
+* Memorable names can become memes for the team to quickly recall and reference
+  later (if the admin user is named "Angela" and the manager is "Maria", that'll
+  probably serve you better than generic names like "TestUser #1")
+
+If you make a mistake when creating your initial set of test data, it's
+perfectly okay to reset the database and start over! Your future tests will be
+coupled to this data as your application grows and evolves, so it's worth taking
+the time to ensure the foundation is solid. (But that's not to say everything
+needs to be perfect; you can always change things or add more data later—you'll
+just have to update your tests accordingly.)
 
 ### Step 3: Dump your `test_data` database
 
+Once you've created a good sampling of test data by interacting with your app,
+the next step is to flush it from the `test_data` database to SQL files. These
+database dumps are meant to be committed to source control and versioned
+alongside your tests over the life of the application. Additionally, they are
+designed to be incrementally
+[migrated](#step-5-keeping-your-test-data-up-to-date) over time, just like you
+migrate production database with every release.
+
 Once you have your test data how you want it, dump the schema and data to SQL
-files:
+files with the `test_data:dump` Rake task:
 
 ```
 $ bin/rake test_data:dump
@@ -213,16 +234,19 @@ $ bin/rake test_data:dump
 
 This will dump three files into `test/support/test_data`:
 
-* Schema DDL in `schema.sql`
+* `schema.sql` - Schema DDL used to (re-)initialize the `test_data` environment
+  database for anyone looking to update your test data
 
-* Test data in `data.sql`
+* `data.sql` - The test data itself, exported as a bunch of SQL `INSERT`
+  statements, which will be executed by your tests to load your test data
 
-* Non-test data (`ar_internal_metadata` and `schema_migrations` by default) in
-  `non_test_data.sql`
+* `non_test_data.sql` - Data needed to run the `test_data` environment, but
+  which shouldn't be inserted by your tests (the `ar_internal_metadata` and
+  `schema_migrations` tables, by default; see `config.non_test_data_tables`)
 
-These paths can be overridden with [TestData.config](#testdataconfig) method.
-Additional details can be found in the [test_data:dump](#test_datadump)
-Rake task reference.
+You probably won't need to, but these paths can be overridden with
+[TestData.config](#testdataconfig) method. Additional details can also be found
+in the [test_data:dump](#test_datadump) Rake task reference.
 
 Once you've made your initial set of dumps, briefly inspect them and—if
 everything looks good—commit them. (And if the files are gigantic or full of
@@ -233,136 +257,201 @@ Does it feel weird to dump and commit SQL files? That's okay! It's [healthy to
 be skeptical](https://twitter.com/searls/status/860553435116187649?s=20)
 whenever you're asked to commit a generated file! Remember that the `test_data`
 environment exists only for creating your test data. Your tests will, in turn,
-load the SQL dump of your data into the familiar `test` database, and things
-will proceed just as if you'd been loading [Rails' built-in
+load the SQL dump of your data into the `test` database, and things will proceed
+just as if you'd been loading [Rails' built-in
 fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)
-from a set of YAML files—the major difference being that `test_data` databases
-are generated through realistic use, whereas fixtures are defined manually in
-(sometimes painstaking) YAML.
+from a set of YAML files.
 
 ### Step 4: Load your data in your tests
 
 Now that you've dumped the contents of your `test_data` database, you can start
 writing tests that rely on this test data.
 
-To accomplish this, you'll likely want to add hooks to run before & after each
-test—first to load your test data and then to rollback any changes made by the
-test in order to clear the air for the next test. The `test_data` gem
-accomplishes this with its [TestData.load](#testdataload) and
-[TestData.rollback](#testdatarollback) methods.
+To accomplish this, you'll likely want to add hooks to run before each test to
+put the database into whatever state the test needs.
+
+For the simplest case—ensuring your test data is loaded into the `test` database
+and available to your test, you'll want to call the
+[TestData.uses_test_data](#testdatauses_test_data) method at the beginning of
+the test. The first time `uses_test_data` is called, `test_data` will start a
+transaction and insert your test data. On subsequent calls to `uses_test_data`
+by later tests, the transaction will be rolled back to a save point taken just
+after the data was initially loaded, so that each test gets a clean starting
+point without repeatedly executing the expensive SQL operation.
+
+#### If you want every single test to have access to your test data
 
-If you're using (Rails' default)
-[Minitest](https://github.com/seattlerb/minitest) and want to include your test
-data with every test, you can add these hooks to `ActiveSupport::TestCase`:
+If, for the sake of consistency & simplicity you want every single Rails-aware
+test to have access to your test data, you
+can accomplish this with a single global before-each hook.
+
+If you're using Rails' default
+[Minitest](https://github.com/seattlerb/minitest), you can load it in a `setup`
+hook in `ActiveSupport::TestCase`:
 
 ```ruby
 class ActiveSupport::TestCase
   setup do
-    TestData.load
-  end
-
-  teardown do
-    TestData.rollback
+    TestData.uses_test_data
   end
 end
 ```
 
-If you use [RSpec](https://rspec.info), you can accomplish the same thing with
-global `before(:each)` and `after(:each)` hooks in your `rails_helper.rb` file:
+Likewise, if you use [RSpec](https://rspec.info), you can accomplish the same
+thing with global `before(:each)` hook in your `rails_helper.rb` file:
 
 ```ruby
 RSpec.configure do |config|
   config.before(:each) do
-    TestData.load
-  end
-
-  config.after(:each) do
-    TestData.rollback
+    TestData.uses_test_data
   end
 end
 ```
 
-That should be all you need to have access to your test data in each of your
-tests! Your tests will also benefit from the speed and data integrity that comes
-with wrapping each test in an always-rolled-back transaction. For more
-information on how all this works, see the [API reference](#api-reference). If
-your test suite is already using fixtures or factories and the above hooks just
-broke everything, check out our [interoperability
-guide](#factory--fixture-interoperability-guide) for help.
+#### If some tests rely on test data and others need a clean slate
 
-If you _don't_ want all of your Rails-aware tests to see this test data (suppose
-you have existing tests that use factories instead), you probably
-want to use [TestData.truncate](#testdatatruncate) to clear data generated by
-this gem out before they run. You might do that by defining two test types:
+Of course, for simple units of code, it may be more prudent to manually create
+the test data they need inline as opposed to relying on a shared source of test
+data. For these tests, you can call
+[TestData.uses_clean_slate](#testdatauses_clean_slate) in a `setup` hook.
 
-```ruby
-# Tests using data created by `test_data`
-class TestDataTestCase < ActiveSupport::TestCase
-  setup do
-    TestData.load
-  end
+For the best performance, you might consider a mode-switching method that's
+invoked at the top of each test listing like this:
 
-  teardown do
-    TestData.rollback
+```ruby
+class ActiveSupport::TestCase
+  def self.uses(mode)
+    case mode
+    when :clean_slate
+      setup { TestData.uses_clean_slate }
+    when :test_data
+      setup { TestData.uses_test_data }
+    else
+      raise "Invalid test data mode: #{mode}"
+    end
   end
 end
 
-# Tests that don't need a shared data source
-class SomeModelTestCase < ActiveSupport::TestCase
-  setup do
-    TestData.truncate
-  end
+# A simple model that will `create` its own data
+class WidgetTest < ActiveSupport::TestCase
+  uses :clean_slate
+  # …
+end
 
-  def test_some_model_does_stuff
-    some_model = SomeModel.create!
+# An integrated test that depends on a lot of data
+class KitchenSinkTest < ActionDispatch::IntegrationTest
+  uses :test_data
+  # …
+end
+```
 
-    result = some_model.does_stuff
+Or, with RSpec:
 
-    assert_equal :cool_stuff, result
+```ruby
+module TestDataModes
+  def uses(mode)
+    case mode
+    when :clean_slate
+      before(:each) { TestData.uses_clean_slate }
+    when :test_data
+      before(:each) { TestData.uses_test_data }
+    else
+      raise "Invalid test data mode: #{mode}"
+    end
   end
+end
 
-  teardown do
-    TestData.rollback(:after_data_truncate)
-  end
+RSpec.configure do |config|
+  config.extend(TestDataModes)
+end
+
+RSpec.describe Widget, type: :model do
+  uses :clean_slate
+  # …
 end
 
+RSpec.describe "Kitchen sink", type: :request do
+  uses :test_data
+  # …
+end
 ```
 
+But wait, there's more! If your test suite switches between multiple modes from
+test-to-test, it's important to be aware of the marginal cost _between_ each of
+those tests. For example, two tests in a row that call `TestData.uses_test_data`
+only need a simple rollback as test setup, but a `TestData.uses_test_data`
+followed by a `TestData.uses_clean_slate` requires a rollback, a truncation, and
+another savepoint. These small costs add up, so consider [speeding up your
+build](#im-worried-my-tests-arent-as-fast-as-they-should-be) by grouping your
+tests into sub-suites based on their source of test data.
+
+#### If your situation is more complicated
+
+If you're adding `test_data` to an existing application, it's likely that you
+won't be able to easily adopt a one-size-fits-all approach to test setup across
+your entire suite. Some points of reference, if that's the situation you're in:
+
+* If your test suite is **already using fixtures or factories** and the above
+  hooks just broke everything, check out our [interoperability
+  guide](#factory--fixture-interoperability-guide) for help.
+* If you need to make any changes to the data after it's loaded, truncated, or
+  after Rails fixtures are loaded, you can configure [lifecycle
+  hooks](#lifecycle-hooks) that will help you achieve a **very fast test suite**
+  by including those changes inside the transaction savepoints
+* If you **don't want `test_data` managing transactions** and cleanup for you
+  and just want to load the SQL dump, you can call
+  [TestData.insert_test_data_dump](#testdatainsert_test_data_dump)
+* For more information on how all this works, see the [API
+  reference](#api-reference).
+
 ### Step 5: Keeping your test data up-to-date
 
-Because your app relies on its tests and your tests rely on their test data,
-your test data needs to be maintained for the entire life of your application.
-Fortunately, and because production databases need the same thing, we already
-have a fantastic tool for the job: [Rails
+Your app relies on its tests and your tests rely on their test data. This
+creates a bit of a paradox: creating & maintaining test data is _literally_ a
+tertiary concern but simultaneously an inescapable responsibility that will live
+with you for the life of your application. That's true whether you use this gem,
+`factory_bot`, Rails fixtures, or something else as a source of shared test
+data.
+
+Fortunately, we already have a fantastic tool available for keeping our
+`test_data` database up-to-date over the life of our application: [Rails
 migrations](https://guides.rubyonrails.org/active_record_migrations.html). If
-your migrations are resilient enough for your production data, they should also
-be able to keep your `test_data` database up-to-date.
+your migrations are resilient enough for your production database, they should
+also be able to keep your `test_data` database up-to-date. (As a happy side
+effect of running your migrations against your test data, this means your
+`test_data` database may help you identify hard-to-catch migration bugs early,
+before being deployed to production!)
 
-Whenever you update your schema, migrate your data, or add a feature that
-necessitates the creation of more test data, you'll need to update your test
-data. Here's a rough outline to updating your `test_data` database:
+Whenever you create a new migration or add a major feature, you'll probably need
+to update your test data. Here's how to do it:
 
-1. If your local `test_data` database is out-of-date with your latest SQL dump
-   files, drop it with `rake test_data:drop_database`
+* If the current SQL dumps in `test/support/test_data` are newer than your local
+  `test_data` database:
 
-2. Load your schema & data into the `test_data` database with `rake
-   test_data:load`
+    1. Be sure there's nothing in your local `test_data` database that you added
+       intentionally and forgot to dump, because it's about to be erased
 
-3. Run any pending migrations with `RAILS_ENV=test_data bin/rake db:migrate`
+    2. Run `rake test_data:reinitialize` drop and recreate the `test_data`
+       database and load the latest SQL dumps into it
 
-4. If you need to create any additional data, start up the server
-   (`RAILS_ENV=test_data bin/rails s`), just like in [Step
-   2](#step-2-create-some-test-data)
+    3. Run any pending migrations with `RAILS_ENV=test_data bin/rake db:migrate`
 
-5. Export your newly-updated `test_data` database with `rake test_data:dump`
+    4. If you need to create any additional data, start up the server
+       (`RAILS_ENV=test_data bin/rails s`), just like in [Step
+       2](#step-2-create-some-test-data)
 
-6. Ensure your tests are passing and then commit the resulting SQL files
+    5. Export your newly-updated `test_data` database with `rake test_data:dump`
+
+    6. Ensure your tests are passing and then commit the resulting SQL files
+
+* If the local `test_data` database is already up-to-date with the current SQL
+  dumps, follow steps **3 through 6** above
 
 It's important to keep in mind that your test data SQL dumps are a shared,
 generated resource among your team (just like a `structure.sql` or `schema.rb`
 file). As a result, if your team doesn't integrate code frequently or if the
-test data experiences a lot of churn in coincident feature branches, you'd be
-right to be concerned that [the resulting merge conflicts could become
+test data changes frequently, you'd be right to be concerned that [the resulting
+merge conflicts could become
 significant](#how-will-i-handle-merge-conflicts-in-these-sql-files-if-i-have-lots-of-people-working-on-lots-of-feature-branches-all-adding-to-the-test_data-database-dumps),
 so sweeping changes should be made deliberately and in collaboration with other
 contributors.
@@ -371,7 +460,10 @@ _[Aside: some Rails teams are averse to using migrations to migrate data as well
 as schemas, instead preferring one-off scripts and tasks. You'll have an easier
 time of things if you use migrations for both schema and data changes. Here are
 some notes on [how to write data migrations
-safely](https://blog.testdouble.com/posts/2014-11-04-healthy-migration-habits/#habit-4-dont-reference-models).]_
+safely](https://blog.testdouble.com/posts/2014-11-04-healthy-migration-habits/#habit-4-dont-reference-models).
+Otherwise, you'll need to remember to run any ad hoc deployment scripts against
+your `test_data` Rails environment along with each of your other deployed
+environments.]_
 
 ## Factory & Fixture Interoperability Guide
 
@@ -390,8 +482,8 @@ all three, or none-of-the-above.
 
 This section will hopefully make it a little easier to incorporate new
 `test_data` tests into a codebase that's already using `factory_bot` and/or
-Rails fixtures, whether you choose to incrementally rewrite the older tests to
-conform to your `test_data` or not.
+Rails fixtures, whether you choose to incrementally migrate to using `test_data`
+over time.
 
 ### Using `test_data` with `factory_bot`
 
@@ -402,182 +494,43 @@ This section will document some thoughts and strategies for introducing
 
 Depending on the assumptions your tests make about the state of the database
 before you've loaded any factories, it's possible that everything will "just
-work" after adding `TestData.load` in a before-each hook and `TestData.rollback`
-in an after-each hook (as shown in the [setup
+work" after adding [TestData.uses_test_data](#testdatauses_test_data) in a
+before-each hook (as shown in the [setup
 guide](#step-4-load-your-data-in-your-tests)). So by all means, try running your
 suite after following the initial setup guide and see if the suite just passes.
 
-If you find that your test suite is failing after adding `TestData.load` to your
-setup, don't panic! It probably means that you have test data and factory
-invocations that are, when combined, violating unique validations or database
-constraints. Depending on your situation (e.g. the size of your test suite, how
-well you understand the intentions of older tests) you might try to resolve
-these errors one-by-one, usually by updating the offending factories or
-editing your `test_data` database to ensure they steer clear of one another.
-This can be tedious, however, and can undermine the completeness of either data
-source in the absence of the other.
-
-If your tests are failing after introducing `test_data` and it's not desirable
-or feasible to work through the individual failures, you can accomplish a clean
-segregation between your factory-dependent tests and your tests that rely on
-`test_data` by wrapping each test that depends on `factory_bot` with
-[TestData.truncate](#testdatatruncate) in a before-each hook and
-[TestData.rollback(:after_data_truncate)](#rolling-back-to-after-test-data-was-truncated)
-in an after-each hook, like this:
+If you find that your test suite is failing after adding
+`TestData.uses_test_data` to your setup, don't panic! Test failures are most
+likely caused by the combination of your `test_data` SQL dump with the records
+inserted by your factories.
 
-```ruby
-class AnExistingFactoryUsingTest < ActiveSupport::Testcase
-  def setup
-    TestData.truncate
-    # pre-existing setup
-  end
+One approach would be to attempt to resolve each such failure one-by-one—usually
+by updating the offending factories or editing your `test_data` database to
+ensure they steer clear of one another. Care should be taken to preserve the
+conceptual encapsulation of each test, however, as naively squashing errors
+risks introducing inadvertent coupling between your factories and your
+`test_data` data such that neither can be used independently of the other.
 
-  def test_stuff
-    #… etc
-  end
-
-  def teardown
-    TestData.rollback(:after_truncate)
-  end
-end
-```
-
-What this will do is complicated and counter-intuitive, but also fast and
-reliable: [TestData.truncate](#testdatatruncate) will first ensure that your
-`test_data` database is loaded inside a transaction, then will truncate that
-data (set the `truncate_these_test_data_tables` [config option](#testdataconfig)
-if necessary), and will finally create _yet another_ transaction save point
-named `:after_data_truncate`. From that point onward, your test is free to
-create all the factories it needs without fear of colliding with whatever you've
-got stored in your `test_data` tables.
-
-_[Why does this approach potentially load all the `test_data` data only to
-immediately truncate it? Because it's actually much faster to truncate a large
-data load in a live transaction, rollback the truncation, and then re-truncate
-the data for a subsequent test than it would be to rollback the large data load
-itself and re-load it for a subsequent test. It's silly but it works.]_
-
-Hopefully one of these approaches, or some combination of them will get your
-test suite passing after you've introduced `test_data`.
-
-#### Separating your `test_data` and factory tests
-
-Just because your tests _can_ access both your `factory_bot` factories and
-`test_data` database doesn't mean they _should_.
-
-Integration tests inevitably become coupled to the data that's available to
-them, and if a test has access to both records created by a factory and a
-`test_data` SQL dump, it is likely to unintentionally become inextricable from
-both. This could result in the test having more ways to fail than necessary and
-make it harder to simplify your test data strategy later. Instead, consider
-explicitly opting into a single type of test data by separating your tests based
-on which source of test data they use.
-
-Every situation will be different, but one strategy that suits a lot of
-circumstances would be to write a class method that runs at test-load time to
-declare and configure the test data strategy for the current test.
-
-Taking from [this
-example](/example/test/integration/better_mode_switching_demo_test.rb) test, you
-could implement a class method like this:
+Another approach that the `test_data` gem provides is an additional mode with
+`TestData.uses_clean_slate`, which—when called at the top of a factory-dependent
+test—will ensure that the tables that `test_data` had written to will be
+truncated, allowing the test to create whatever factories it needs without fear
+of conflicts.
 
 ```ruby
-class ActiveSupport::TestCase
-  def self.test_data_mode(mode)
-    case mode
-    when :factory_bot
-      require "factory_bot_rails"
-      include FactoryBot::Syntax::Methods
-
-      setup do
-        TestData.truncate
-      end
-
-      teardown do
-        TestData.rollback(:after_data_truncate)
-      end
-    when :test_data
-      setup do
-        TestData.load
-      end
-
-      teardown do
-        TestData.rollback
-      end
-    end
+class AnExistingFactoryUsingTest < ActiveSupport::Testcase
+  setup do
+    TestData.uses_clean_slate
+    # pre-existing setup
   end
+  # …
 end
 ```
 
-And then (without any class inheritance complications), simply declare which
-kind of test you're specifying:
-
-```ruby
-class SomeFactoryUsingTest < ActiveSupport::TestCase
-  test_data_mode :factory_bot
-
-  # … tests go here
-end
-
-class SomeTestDataUsingTest < ActionDispatch::IntegrationTest
-  test_data_mode :test_data
-
-  # etc.
-end
-```
-
-By following an approach like this one, your `test_data` tests won't even see
-your `create_*` factory methods and your `factory_bot` tests won't have access
-to any of your `test_data`, either. From there, you can  migrate tests onto
-`test_data` incrementally, secure in the knowledge that you're not inadvertently
-tangling your tests' dependency graph further.
-
-#### Speeding up your test suite when using factories
-
-##### Addressing redundant data cleanup
-
-After adding `test_data` to your test suite, consider is how database cleanup
-was being handled previously to make sure it isn't unnecessarily truncating
-everything or resetting the transaction between tests. It's possible that your
-suite is relying on Rails' built-in `use_transactional_tests` feature to wrap
-your tests in always-rolled-back transactions, even if you're not using
-fixtures. Or perhaps your suite uses
-[database_cleaner](https://github.com/DatabaseCleaner/database_cleaner) to
-truncate the database before or after each test. In either case, it's important
-to know that by default [TestData.load](#testdataload) and
-[TestData.rollback](#testdatarollback) will start and rollback a nested
-transaction, respectively. That means—so long as they're called at the top of a
-before-each hook and the end of an after-each hook—you might be able to disable
-`use_transactional_tests` or remove your dependency on `database_cleaner` or any
-other custom truncation logic you might have. Even if you get your suite running
-immediately after adding `test_data`, it's still worth taking the time to
-understand what's going on during test setup & teardown, because there may be an
-opportunity to make your tests faster and more comprehensible by eliminating
-redundant clean-up steps.
-
-##### Avoiding truncate rollback churn
-
-It's important to know that if your test suite has a mix of tests that call
-[TestData.load](#testdataload) and tests that call
-[TestData.truncate](#testdatatruncate), each time the test runner switches
-between the two types, each call to `TestData.load` will cause the transaction
-state to be rolled back from
-[:after_data_truncate](#rolling-back-to-after-test-data-was-truncated) to
-[:after_data_load](#rolling-back-to-after-the-data-was-loaded), only for the
-next test to call `TestData.truncate` truncates all the tables again. In
-practice, this shouldn't be too costly an operation, but if your test order is
-randomized you might find that your build will run faster if you separate each
-set of tests at runtime.
-
-Separating your `test_data` and `factory_bot` tests is pretty trivial if you're
-using RSpec, as the
-[tag](https://relishapp.com/rspec/rspec-core/v/3-10/docs/command-line/tag-option)
-feature was built with this sort of need in mind. Otherwise, you might consider
-organizing the tests in different directories and running multiple commands to
-execute them (e.g. `bin/rails test test/test_data_tests` and `bin/rails
-test/factory_tests`). Every CI configuration is different, however, and you may
-find yourself needing to get creative in configuring things to achieve the
-fastest build time.
+If you have a lot of tests, you can find a more sophisticated approaches for
+logically switching between types of test data declaratively above in the
+[getting started
+section](#if-some-tests-rely-on-test-data-and-others-need-a-clean-slate)
 
 ### Using `test_data` with Rails fixtures
 
@@ -588,145 +541,53 @@ permanently committed to the test database actually makes them a little trickier
 to work with. This section will cover a couple approaches for integrating
 `test_data` into suites that use fixtures.
 
-#### Getting your fixtures-dependent tests passing with `test_data`
-
 It's more likely than not that all your tests will explode in dramatic fashion
-as soon as you add `TestData.load` to a `setup` or `before(:each)` hook. Because
-fixtures will be loaded all-at-once then your `test_data` dump will be inserted
-directly on top of them. If everything works, or if you only encounter a few
-errors throughout your test suite (perhaps based on assertions of the `count` of
-a particular model), congratulations! You should still consider mitigating the
-risks of coupling your tests to both data sources ([as discussed
-above](#separating-your-test_data-and-factory-tests)) by migrating completely
-onto `test_data` over time, but no further action is necessary or recommended.
-
-If, however, you find yourself running into non-trivial challenges (like rampant
-validation or constraint errors), `test_data` provides an API that **overrides
-Rails' built-in fixtures behavior with a monkey patch**. If that bold text
-warning wasn't enough to scare you from reading on, here's how to do it.
-
-_[Note that the following requires `use_transactional_data_loader` to be enabled
-in your [config](#testdataconfig), because it depends on transaction
-rollbacks.]_
-
-Here's what you can do if you can't get your fixtures to play nicely with your
-`test_data` dump:
-
-1. Near the top of your test helper, call:
+as soon as you add `TestData.uses_test_data` to a `setup` or `before(:each)`
+hook. Typically, your fixtures will be loaded and committed immediately with
+your `test_data` dump inserted afterward, which makes it exceedingly likely that
+your tests will fail with primary key and unique constraint conflicts. If that's
+the case you find yourself in, `test_data` provides an API that **overrides
+Rails' built-in fixtures behavior with a monkey patch**.
+
+And if that bold text wasn't enough to scare you off, here's how to do
+it:
+
+1. Before your tests have loaded (e.g. near the top of your test helper), call:
    [TestData.prevent_rails_fixtures_from_loading_automatically!](#testdataprevent_rails_fixtures_from_loading_automatically)
-   This will effectively turn
+   This will patch Rails'
    [setup_fixtures](https://github.com/rails/rails/blob/main/activerecord/lib/active_record/test_fixtures.rb#L105)
-   into a no-op, which means that your test fixtures will not be automatically
-   loaded into your test database
+   and effectively render it into a no-op, which means that your test fixtures
+   will not be automatically loaded into your test database
 
-2. In tests that rely on your `test_data` dump, call [TestData.load and
-   TestData.rollback](#step-4-load-your-data-in-your-tests) as you normally
-   would. Because your fixtures won't be loaded automatically, they won't be
-   available to these tests
+2. In tests that rely on your `test_data` dump, call
+   [TestData.uses_test_data](#step-4-load-your-data-in-your-tests) as you
+   normally would. Because your fixtures won't be loaded automatically, they
+   won't be available to these tests
 
 3. In tests that need fixtures, call
-   [TestData.load_rails_fixtures](#testdataload_rails_fixtures)
-   in a before-each hook and
-   [TestData.rollback(:after_load_rails_fixtures)](#rolling-back-to-after-rails-fixtures-were-loaded)
-   in an after-each hook. This will (in an almost comic level of
-   transaction-nesting) ensure your `test_data` dump is loaded in an initial
-   transaction, then ensure that it is truncated in a second transaction, before
-   loading your rails fixtures in a third transaction. These tests will have
-   access to all your fixture data without being tainted by any of your
-   `test_data` data
+   [TestData.uses_rails_fixtures(self)](#testdatauses_rails_fixtures) in a
+   before-each hook. This will first ensure that any tables written to by
+   `test_data` are truncated (as with `TestData.uses_clean_slate`) before
+   loading your Rails fixtures
 
 For example, you might add the following to an existing fixtures-dependent
 test to get it passing:
 
 ```ruby
 class AnExistingFixtureUsingTest < ActiveSupport::Testcase
-  def setup
-    TestData.load_rails_fixtures
+  setup do
+    TestData.uses_rails_fixtures(self)
     # pre-existing setup
   end
 
-  def test_stuff
-    #… etc
-  end
-
-  def teardown
-    TestData.rollback(:after_load_rails_fixtures)
-  end
-end
-```
-
-_[You don't need to worry about whether `TestData.load` has been called
-previously, the loader will infer your intent and ensure that the transaction
-state is correct before loading your fixtures.]_
-
-#### Separating your `test_data` and fixture tests
-
-*This only applies if you had to use
-[TestData.load_rails_fixtures](#testdataload_rails_fixtures) as shown above.*
-
-Just [like with factories](#separating-your-test_data-and-factory-tests), you
-might benefit from a test helper to clearly declare whether a test uses fixtures
-or `test_data` right at the top. Following the same pattern, you might do this:
-
-```ruby
-class ActiveSupport::TestCase
-  def self.test_data_mode(mode)
-    case mode
-    when :fixtures
-      fixtures :all
-
-      setup do
-        TestData.load_rails_fixtures
-      end
-
-      teardown do
-        TestData.rollback(:after_load_rails_fixtures)
-      end
-    when :test_data
-      setup do
-        TestData.load
-      end
-
-      teardown do
-        TestData.rollback
-      end
-    end
-  end
-end
-```
-
-Which would allow you to simplify the above fixtures-using test to:
-
-```ruby
-class AnExistingFixtureUsingTest < ActiveSupport::Testcase
-  test_data_mode :fixtures
-
-  def test_stuff
-    #… etc
-  end
+  # …
 end
 ```
 
-#### Improving test suite speed with fixtures
-
-Again, as is [the case with
-factories](#improving-test-suite-speed-with-factories), every time your test
-runner randomly picks a `test_data` test after running a fixtures-dependent
-test, it will roll back your fixtures and the truncation of your `test_data`,
-only to re-truncate your `test_data` data and reload your fixtures for the next
-test that happens to use fixtures. But unlike truncation alone, loading your
-fixtures is a non-trivial operation that can chew up a some serious time as your
-suite runs.
-
-As a result, we strongly encourage breaking up your test suite to avoid this
-churn, even if it means splitting your test run over multiple CLI commands. If
-you're using the Rails test runner and Minitest, that likely means sequestering
-one set of tests to one directory and the other to a different directory, as
-there is no granular control over to how the runner randomizes suites. And for
-RSpec,
-[tagging](https://relishapp.com/rspec/rspec-core/v/3-10/docs/command-line/tag-option)
-each spec and running separate commands for each tag could yield significant
-performance improvements.
+If you've adopted a mode-switching helper method [like the one described
+above](#if-some-tests-rely-on-test-data-and-others-need-a-clean-slate), you
+could of course add a third mode to cover any tests that depend on Rails
+fixtures.
 
 ## Rake Task Reference
 
@@ -771,11 +632,9 @@ This task runs several generators:
   have numerous secrets in this file's `development:` stanza, you may want to
   alias and inherit it into `test_data:` like the `webpacker.yml` generator does
 
-* `config/cable.yml` - In the absences of a configuration stanza,
-  [ActionCable](https://guides.rubyonrails.org/action_cable_overview.html) will
-  assume you're using Redis for tracking Websocket connections, so this
-  generator explicitly specifies `async` instead, since that's the default for
-  `development:`
+* `config/cable.yml` - Simply defines a `test_data:` entry that tells
+  [ActionCable](https://guides.rubyonrails.org/action_cable_overview.html) to
+  use the `async` adapter, since that's also the default for `development`
 
 ### test_data:verify_config
 
@@ -792,8 +651,8 @@ your seed file. Specifically:
 1. Creates the `test_data` environment's database, if it doesn't already exist
 
 2. Ensures the database is non-empty to preserve data integrity (run
-   [test_data:drop_database](#test_datadrop_database) first if it contains
-   outdated test data)
+   [test_data:drop_database](#test_datadrop_database) first if you intend to
+   reinitialize it)
 
 3. Checks to see if a dump of the database already exists (by default, stored in
    `test/support/test_data/`)
@@ -804,11 +663,24 @@ your seed file. Specifically:
     * Otherwise, it invokes the task `db:schema:load` and `db:seed` (similar to
       Rails' built-in `db:setup` task)
 
+### test_data:reinitialize
+
+This task is designed for the situation where you may already have a `test_data`
+database created and simply want to drop it and replace it with whatever dumps
+are in the `test/support/test_data` directory.
+
+Dropping the database requires confirmation, either interactively or by setting
+the environment variable `TEST_DATA_CONFIRM`. It will additionally warn you in
+the event that the local database appears to be newer than the dumps on disk
+that would replace it. From there, this task behaves the same way as `rake
+test_data:initialize`.
+
 ### test_data:dump
 
 This task is designed to be run after you've created or updated your test data
-and you're ready to run your tests against it. The task creates several plain
-SQL dumps from your `test_data` environment's database:
+in the `test_data` database and you're ready to run your tests against it. The
+task creates several plain SQL dumps from your `test_data` environment's
+database:
 
 * A schema-only dump, by default in `test/support/test_data/schema.sql`
 
@@ -816,13 +688,13 @@ SQL dumps from your `test_data` environment's database:
   `test/support/test_data/data.sql`
 
 * A data-only dump of records that you *don't* want loaded in your tests in
-  `test/support/test_data/non_test_data.sql` (by default, this includes Rails'
+  `test/support/test_data/non_test_data.sql`. By default, this includes Rails'
   internal tables: `ar_internal_metadata` and `schema_migrations`, configurable
-  with [TestData.config](#testdataconfig)'s `non_test_data_tables`)
+  with [TestData.config](#testdataconfig)'s `non_test_data_tables`
 
 Each of these files are designed to be committed and versioned with the rest of
 your application. [TestData.config](#testdataconfig) includes several
-options to control which tables are exported into which group.
+options to control this task.
 
 ### test_data:load
 
@@ -839,7 +711,7 @@ This task will load your SQL dumps into your `test_data` database by:
 4. Warning if there are pending migrations that haven't been run yet
 
 If there are pending migrations, you'll probably want to run them and then
-dump & commit your test data so that they're all up-to-date:
+dump & commit your test data so that they're up-to-date:
 
 ```
 $ RAILS_ENV=test_data bin/rake db:migrate
@@ -852,275 +724,285 @@ This task will create the `test_data` environment's database if it does not
 already exist. It also
 [enhances](https://dev.to/molly/rake-task-enhance-method-explained-3bo0) Rails'
 `db:create` task so that `test_data` is created along with `development` and
-`test`.
+`test` whenever `rake db:create` is run.
 
 ### test_data:drop_database
 
 This task will drop the `test_data` environment's database if it exists. It also
 enhances Rails' `db:drop` task so that `test_data` is dropped along with
-`development` and `test`.
+`development` and `test` whenever `rake db:drop` is run.
 
 ## API Reference
 
+### TestData.uses_test_data
+
+This is the method designed to be used by your tests to load your test data
+into your `test` database so that your tests can rely on it. Typically, you'll
+want to call it at the beginning of each test that relies on the test data
+managed by this gem—most often, in a before-each hook.
+
+For the sake of speed and integrity, `TestData.uses_test_data` is designed to
+take advantage of nested transactions ([Postgres
+savepoints](https://www.postgresql.org/docs/current/sql-savepoint.html)). By
+default, data is loaded in a transaction and intended to be rolled back to the
+point _immediately after_ the data was imported between tests. This way, your
+test suite only pays the cost of importing the SQL file once, but each of your
+tests can enjoy a clean slate that's free of data pollution from other tests.
+(This is similar to, but separate from, Rails fixtures'
+[use_transactional_tests](https://edgeguides.rubyonrails.org/testing.html#testing-parallel-transactions)
+option.)
+
+_See configuration option:
+[config.after_test_data_load](#configafter_test_data_load)_
+
+### TestData.uses_clean_slate
+
+If a test does not rely on your `test_data` data, you can instead ensure that it
+runs against empty tables by calling `TestData.uses_clean_slate`. Like
+`TestData.uses_test_data`, this would normally be called at the beginning of
+each such test in a before-each hook.
+
+This method works by first ensuring that your test data is loaded (and the
+correspondent savepoint created), then will truncate all affected tables and
+create another savepoint. It's a little counter-intuitive that you'd first
+litter your database with data only to wipe it clean again, but it's much faster
+to repeatedly truncate tables than to repeatedly import large SQL files.
+
+_See configuration options:
+[config.after_test_data_truncate](#configafter_test_data_truncate),
+[config.truncate_these_test_data_tables](#configtruncate_these_test_data_tables)_
+
+### TestData.uses_rails_fixtures
+
+As described in this README's [fixture interop
+guide](#using-test_data-with-rails-fixtures), `TestData.uses_rails_fixtures`
+will load your app's [Rails
+fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)
+by intercepting Rails' built-in fixture-loading code. As with the other "uses"
+methods, you'll likely want to call it in a before-each hook before any test
+that needs access to your Rails fixtures.
+
+There are two additional things to keep in mind if using this method:
+
+1. Using this feature requires that you've first invoked
+   [TestData.prevent_rails_fixtures_from_loading_automatically!](#testdataprevent_rails_fixtures_from_loading_automatically)
+   before your tests have started running to override Rails' default behavior
+   before any of your tests have loaded or started running
+
+2. Because the method depends on Rails' fixture caching mechanism, it must be
+   passed an instance of the running test class (e.g.
+   `TestData.uses_rails_fixtures(self)`)
+
+Under the hood, this method effectively ensures a clean slate the same way
+`TestData.uses_clean_slate` does, except that after creating the truncation
+savepoint, it will then load your fixtures and finally create—wait for it—yet
+another savepoint that subsequent calls to `uses_rails_fixtures` can rollback
+to.
+
+_See configuration option:
+[config.after_rails_fixture_load](#configafter_rails_fixture_load)_
+
+#### TestData.prevent_rails_fixtures_from_loading_automatically!
+
+Call this method before any tests have been loaded or executed by your test
+runner if you're planning to use
+[TestData.uses_rails_fixtures](#testdatauses_rails_fixtures) to load Rails
+fixtures into any of your tests. This method will disable the default behavior
+of loading your Rails fixtures into the test database as soon as the first test
+case with fixtures enabled is executed. (Inspect the [source for the
+patch](/lib/test_data/active_record_ext.rb) to make sure you're comfortable with
+what it's doing.)
+
 ### TestData.config
 
 The generated `config/initializers/test_data.rb` initializer will include a call
 to `TestData.config`, which takes a block that yields a mutable configuration
-object (similar to `Rails.application.config`):
+object (similar to `Rails.application.config`). If anything is unclear after
+reading the documentation, feel free to review the
+[initializer](lib/generators/test_data/initializer_generator.rb) and the [Config
+class](/lib/test_data/config.rb) themselves.
+
+#### Lifecycle hooks
+
+Want to shift forward several timestamp fields after your `test_data` SQL dumps
+are loaded into your test database? Need to refresh a materialized view after
+your Rails fixtures are loaded? You _could_ do these things after calling
+`TestData.uses_test_data` and `TestData.uses_rails_fixtures`, respectively, but
+you'd take the corresponding performance hit in each and every test.
+
+Instead, you can pass a callable or a block and `test_data` will execute it just
+_after_ performing the associated data operation but just _before_ creating a
+transaction savepoint. That way, whenever the gem rolls back between tests, your
+hook won't need to be run again.
+
+##### config.after_test_data_load
+
+This is hook is run immediately after `TestData.uses_test_data` has loaded your
+SQL dumps into the `test` database, but before creating a savepoint. Takes a
+block or anything that responds to `call`.
+
 
 ```ruby
 TestData.config do |config|
-  # Where to store SQL dumps of the test_data database schema
-  # config.schema_dump_path = "test/support/test_data/schema.sql"
-
-  # Where to store SQL dumps of the test_data database test data
-  # config.data_dump_path = "test/support/test_data/data.sql"
+  # Example: roll time forward
+  config.after_test_data_load do
+    Boop.connection.exec_update(<<~SQL, nil, [[nil, Time.zone.now - System.epoch]])
+      update boops set booped_at = booped_at + $1
+    SQL
+  end
+end
+```
 
-  # Where to store SQL dumps of the test_data database non-test data
-  # config.non_test_data_dump_path = "test/support/test_data/non_test_data.sql"
+##### config.after_test_data_truncate
 
-  # Tables whose data shouldn't be loaded into tests.
-  #   ("ar_internal_metadata" and "schema_migrations" are always excluded)
-  # config.non_test_data_tables = []
+This is hook is run immediately after `TestData.uses_clean_slate` has truncated
+your test data, but before creating a savepoint. Takes a block or anything that
+responds to `call`.
 
-  # Tables whose data should be excluded from all dumps (does not affect schema DDL)
-  # config.dont_dump_these_tables = []
+```ruby
+TestData.config do |config|
+  # Example: pass a callable instead of a block
+  config.after_test_data_truncate(SomethingThatRespondsToCall.new)
+end
+```
 
-  # Tables whose data should be truncated by TestData.truncate
-  #   If left as `nil`, all tables inserted into by the SQL file at
-  #   `data_dump_path` will be truncated
-  # config.truncate_these_test_data_tables = nil
+##### config.after_rails_fixture_load
 
-  # Perform TestData.load and TestData.truncate inside nested
-  #   transactions for increased test isolation and speed. Setting this
-  #   to false will disable several features that depend on transactions
-  #   being used
-  # config.use_transactional_data_loader = true
+This is hook is run immediately after `TestData.uses_rails_fixtures` has loaded
+your Rails fixtures into the `test` database, but before creating a savepoint.
+Takes a block or anything that responds to `call`.
 
-  # Log level (valid values: [:debug, :info, :warn, :error, :quiet])
-  # Can also be set with env var TEST_DATA_LOG_LEVEL
-  # config.log_level = :info
+```ruby
+TestData.config do |config|
+  # Example: refresh Postgres assets like materialized views
+  config.after_rails_fixture_load do
+    RefreshesMaterializedViews.new.call
+  end
 end
 ```
 
-### TestData.load
+#### test_data:dump options
 
-This is the method designed to be used by your tests to load your test data
-into your `test` database so that your tests can rely on it.
+The gem provides several options governing the behavior of the
+[test_data:dump](#test_datadump) Rake task. You probably won't need to set these
+unless you run into a problem with the defaults.
 
-#### Loading with the speed & safety of transaction savepoints
+##### config.non_test_data_tables
 
-For the sake of speed and integrity, `TestData.load` is designed to take
-advantage of nested transactions ([Postgres
-savepoints](https://www.postgresql.org/docs/current/sql-savepoint.html)). By
-default, data is loaded in a transaction and intended to be rolled back to the
-point _immediately after_ the data was imported after each test. This way, your
-test suite only pays the cost of importing the SQL file once, but each of your
-tests can enjoy a clean slate that's free of data pollution from other tests.
-(This is similar to, but separate from, Rails fixtures'
-[use_transactional_tests](https://edgeguides.rubyonrails.org/testing.html#testing-parallel-transactions)
-option.)
+Your application may have some tables that are necessary for the operation of
+the application, but irrelevant or incompatible with you your tests. This data
+is still dumped for the sake of being able to restore the database with [rake
+test_data:load](#test_dataload), but will not be loaded when your tests are
+running. Defaults to `[]`, (but will always include `ar_internal_metadata` and
+`schema_migrations`).
+
+```ruby
+TestData.config do |config|
+  config.non_test_data_tables = []
+end
+```
 
-To help think through the method's behavior, the method nicknames its
-transactions `:before_data_load` and `:after_data_load`. The first time you call
-`TestData.load`:
-
-1. Creates the `:before_data_load` savepoint
-2. Executes the SQL found in the data dump (e.g.
-   `test/support/test_data/data.sql`) to insert your test data
-3. Creates the `:after_data_load` savepoint
-
-If the method is called and the `:after_data_load` savepoint is already active
-(indicating that the data is loaded), the method rolls back to
-`:after_data_load`, inferring that the user's intention is to have a clean load
-of the test data.
-
-As an additional safeguard, in case a rollback is triggered unexpectedly (i.e.
-calling `rollback_transaction` on `ActiveRecord::Base.connection` instead of via
-`TestData.rollback`), `test_data` writes a memo indicating that the data is
-loaded in `ar_internal_metadata`. `TestData.load` uses this memo to detect this
-issue and will recreate the `:after_data_load` savepoint rather than attempt to
-erroneously reload your SQL data dump. (Similar error-handling is built-into
-[TestData.truncate](#testdatatruncate) and
-[TestData.load_rails_fixtures](#testdataload_rails_fixtures), as well.)
-
-#### Loading without transactions
-
-For most cases, we strongly recommend using the default transactional testing
-strategy, both because it's faster and because it reduces the risk of test
-pollution. However, you may need to commit your test data if the data needs to
-be loaded by multiple processes or over multiple connections.
-
-If you need to load the test data and commit it to the database, simply set
-`TestData.config.use_transactional_data_loader = false`.
-
-If transactions are disabled, you'll need to decide whether and how to clear the
-data out after each test. Many folks use
-[database_cleaner](https://github.com/DatabaseCleaner/database_cleaner) for
-this, while `test_data` offers a rudimentary
-[TestData.truncate](https://github.com/testdouble/test_data#testdatatruncate)
-method that may be sufficient for your needs.
-
-You might imagine something like this if you were loading the data just once for
-the full run of a test suite:
+##### config.dont_dump_these_tables
+
+Some tables populated by your application may not be necessary to either its
+proper functioning or useful to your tests (e.g. audit logs), so you can save
+time and storage by preventing those tables from being dumped entirely. Defaults
+to `[]`.
 
 ```ruby
-RSpec.configure do |config|
-  config.before :all do
-    TestData.load
-  end
+TestData.config do |config|
+  config.dont_dump_these_tables = []
+end
+```
 
-  config.after :all do
-    TestData.truncate
-  end
+##### config.schema_dump_path
+
+The path to which the schema DDL of your `test_data` database will be written.
+This is only used by [rake test_data:load](#test_dataload) when initializing the
+`test_data` database. Defaults to `"test/support/test_data/schema.sql"`.
+
+```ruby
+TestData.config do |config|
+  config.schema_dump_path = "test/support/test_data/schema.sql"
 end
 ```
 
-Note that when `use_transactional_data_loader` is `false`, subsequent
-`TestData.load` calls won't be able to detect whether the data is already loaded
-and will try to re-insert the data, which will almost certainly result in
-primary key conflicts.
-
-### TestData.rollback
-
-Because the gem loads your data in a transaction, it makes it easy to rollback
-to any of its defined savepoints. In most cases you'll want to roll back to
-`:after_data_load` after each test, and that's what `TestData.rollback` will do
-when called without an argument. If the specified savepoint isn't active,
-calling `rollback` is a no-op.
-
-The gem may create up to four nested savepoints in a single transaction, and
-this method allows you to rollback to any of them. They form the following
-stack:
-
-* `:before_data_load` - Taken before loading your `test_data` dump
-* `:after_data_load` - Taken after loading your `test_data` dump
-* `:after_truncate` - Taken after your `test_data` is truncated
-* `:after_load_rails_fixtures` - Taken after Rails fixtures are loaded via
-  [TestData.load_rails_fixtures](#testdataload_rails_fixtures)
-
-More details on rolling back to each of the gem's savepoints follows below.
-
-#### Rolling back to before test data was loaded
-
-If some tests rely on data loaded by `TestData.load` and you have other tests
-that depend on that data _not being there_, you probably want to call
-[TestData.truncate](#testdatatruncate). But if that won't work for your needs,
-you can rewind to the moment just before your test data was loaded by calling
-`TestData.rollback(:before_data_load)`.
-
-**⚠️ Warning⚠️** Repeatedly loading and rolling back to `:before_data_load` is
-expensive! If your test suite calls `TestData.rollback(:before_data_load)`
-multiple times, it's likely you're re-loading your (possibly large) SQL file of
-test data many more times than is necessary. Consider using
-[TestData.truncate](#testdatatruncate) to achieve the same goal with faster
-performance. Failing that, it might be preferable to partition your test suite
-so that similar tests are run in separate groups (as opposed to in a fully
-random or arbitrary order) to avoid repeatedly thrashing between rollbacks and
-reloads. This partitioning could be accomplished by either configuring your test
-runner or by running separate test commands for each group of tests.
-
-#### Rolling back to after the data was loaded
-
-This is the way you're likely to call this method most often.
-
-When `TestData.rollback` is passed no arguments or called more explicitly as
-`TestData.rollback(:after_data_load)`, the method will rollback to the
-`:after_data_load` transaction savepoint taken immediately after the SQL dump
-was loaded. As a result, it is intended to be run after each test (e.g. in an
-`after(:each)` or `teardown`), to undo any changes made by the test.
-
-#### Rolling back to after test data was truncated
-
-If some of your tests call [TestData.truncate](#testdatatruncate) to clear out
-your test data after it's been loaded (as
-[described](#getting-your-factory-tests-passing-after-adding-test_data) when
-using `test_data` in conjunction with `factory_bot`), then you will likely want
-to run `TestData.rollback(:after_data_truncate)` after each of them. This will
-rewind your test database's state to when those tables were first
-truncated—effectively re-cleaning the slate for the next test.
-
-#### Rolling back to after Rails fixtures were loaded
-
-If you're using [TestData.load_rails_fixtures](#testdataload_rails_fixtures) in
-your test's before-each hook, you'll probably want to teardown that test by
-rolling back with `TestData.rollback(:after_load_rails_fixtures)` in an
-after-each hook, which will rewind to the point just after your Rails fixtures
-were loaded.
-
-### TestData.truncate
-
-Do you have some tests that _shouldn't_ access your test data? Or did some
-existing tests started failing after `test_data` was added? If you want to clear
-the state of your `test` database to support these tests, you can accomplish
-this with `TestData.truncate`. It truncates all the tables that `TestData.load`
-inserted into and then creates a savepoint named `:after_data_truncate`.
-
-Most often, you'll want to call `TestData.truncate` before each test that
-should _not_ have access to your test data created with this gem. After each
-such test, it can clean up by calling `TestData.rollback(:after_data_truncate)`:
+##### config.data_dump_path
+
+The path that the SQL dump of your test data will be written. This is the dump
+that will be executed by `TestData.uses_test_data` in your tests. Defaults to
+`"test/support/test_data/data.sql"`.
 
 ```ruby
-class CleanSlateTest < ActiveDispatch::IntegrationTest
-  def setup do
-    TestData.truncate
-  end
+TestData.config do |config|
+  config.data_dump_path = "test/support/test_data/data.sql"
+end
+```
 
-  def teardown do
-    TestData.rollback(:after_data_truncate)
-  end
+##### config.non_test_data_dump_path
+
+The path to which the [non_test_data_tables](#confignon_test_data_tables) in
+your `test_data` database will be written. This is only used by [rake
+test_data:load](#test_dataload) when initializing the `test_data` database.
+Defaults to `"test/support/test_data/non_test_data.sql"`.
+
+```ruby
+TestData.config do |config|
+  config.non_test_data_dump_path = "test/support/test_data/non_test_data.sql"
 end
 ```
 
-By default, all tables for which there is an `INSERT INTO` statement in your
-test data SQL dump will be truncated (and cascading to any tables with foreign
-keys pointing to those tables), but you can also explicitly specify which tables
-should be truncated yourself by setting the `truncate_these_test_data_tables`
-property on [TestData.config](#testdataconfig) to an array of table names.
+#### Other configuration options
 
-#### If you're not using transactions
+##### config.truncate_these_test_data_tables
 
-Just [like TestData.load](#loading-without-transactions), you can call
-`TestData.truncate` when `use_transactional_data_loader` is `false` and it will
-commit the truncation.
+By default, when [TestData.uses_clean_slate](#testdatauses_clean_slate) is
+called, it will truncate any tables for which an `INSERT` operation was
+detected in your test data SQL dump. This may not be suitable for every case,
+however, so this option allows you to specify which tables are truncated.
+Defaults to `nil`.
 
-### TestData.prevent_rails_fixtures_from_loading_automatically!
+```ruby
+TestData.config do |config|
+  config.truncate_these_test_data_tables = []
+end
+```
 
-Call this method before any tests have been loaded or executed by your test
-runner if you're planning to use
-[TestData.load_rails_fixtures](#testdataload_rails_fixtures) to load Rails
-fixtures into any of your tests. This method will disable the default behavior
-of loading your Rails fixtures into the test database as soon as the first test
-case with fixtures enabled is executed. (Inspect the [source for the
-patch](/lib/test_data/active_record_ext.rb) to make sure you're comfortable with
-what it's doing.)
+##### config.log_level
 
-### TestData.load_rails_fixtures
+The gem outputs its messages to standard output and error by assigning a log
+level to each message. Valid values are `:debug`, `:info`, `:warn`, `:error`,
+`:quiet`. Defaults to `:info`.
 
-As described in this README's [fixture interop
-guide](#getting-your-fixtures-dependent-tests-passing-with-test_data),
-`TestData.load_rails_fixtures` will load your app's [Rails
-fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)
-into an effectively empty test database inside a nested transaction.
+```ruby
+TestData.config do |config|
+  config.log_level = :info
+end
+```
 
-Using this feature requires that you've:
+### TestData.insert_test_data_dump
 
-1. Invoked
-[TestData.prevent_rails_fixtures_from_loading_automatically!](#testdataprevent_rails_fixtures_from_loading_automatically)
-2. Have `config.use_transactional_data_loader` set to true (the default) in your
-   [config](#testdataconfig)
+If you just want to insert the test data in your application's SQL dumps without
+any of the transaction management or test runner assumptions inherent in
+[TestData.uses_test_data](#testdatauses_test_data), then you can call
+`TestData.insert_test_data_dump` to load and execute the dump.
 
-When you call this method, it will do the following:
+This might be necessary in a few different situations:
 
-1. Verify your `test_data` dump has been loaded (or else load it)
-2. Verify the loaded data has been truncated (or else truncate it)
-3. Load your Rails fixtures from their YAML source files into your test database
-4. Create a new savepoint in the nested transactions named
-   `:after_load_rails_fixtures`
+* Running tests in environments that can't be isolated to a single database
+  transaction (e.g. orchestrating tests across multiple databases, processes,
+  etc.)
+* You might ant to use your test data to seed pre-production environments with
+  enough data to exploratory test (as you might do in a `postdeploy` script with
+  your [Heroku Review
+  Apps](https://devcenter.heroku.com/articles/github-integration-review-apps))
+* Your tests require complex heterogeneous sources of data that aren't a good
+  fit for the assumptions and constraints of this library's default methods for
+  preparing test data
 
-Once loaded, your tests will be able to use your test fixtures inside a
-transaction. At teardown-time, you can reset those fixtures by rolling back with
-[TestData.rollback(:after_load_rails_fixtures)](#rolling-back-to-after-rails-fixtures-were-loaded).
+In any case, since `TestData.insert_test_data_dump` is not wrapped in a
+transaction, when used for automated tests, data cleanup becomes your
+responsibility.
 
 ## Assumptions
 
@@ -1148,12 +1030,11 @@ yet. Here are some existing assumptions and limitations:
 
 If you use `factory_bot` and all of these are true:
 
-* Your integration tests are super fast and not getting significantly slower
+* Your integration tests are super fast and are not getting significantly slower
   over time
 
-* Innocuous changes to factories rarely result in unrelated test failures
-  that—rather than indicating a bug in the production code—instead require that
-  each of those tests be analyzed & updated to get them passing again
+* Minor changes to existing factories rarely result in test failures that
+  require unrelated tests to be read & updated to get them passing again
 
 * The number of associated records generated between your most-used factories
   are representative of production data, as opposed to generating a sprawling
@@ -1169,16 +1050,16 @@ If you use `factory_bot` and all of these are true:
   confidence-eroding nested factories with names like `:user`, `:basic_user`,
   `:lite_user`, and `:plain_user_no_associations_allowed`
 
-If none of these things are true, then congratulations! You are using
-`factory_bot` with great success! Unfortunately, in our experience, this outcome
+If none of these things are true, then congratulations! You are probably using
+`factory_bot` to great effect! Unfortunately, in our experience, this outcome
 is exceedingly rare, especially for large and long-lived applications.
 
-However, if any of the above issues resonate with your experience using
-`factory_bot`: these are the sorts of failure modes the `test_data` gem was
-designed to address. We hope you'll consider trying it with an open mind. At the
-same time, we acknowledge that large test suites can't be rewritten and migrated
-to a different source of test data overnight—nor should they be! See our notes
-on [migrating to `test_data`
+However, if you'd answer "no" to any of the above questions, just know that
+these are the sorts of failure modes the `test_data` gem was designed to
+avoid—and we hope you'll consider trying it with an open mind. At the same time,
+we acknowledge that large test suites can't be rewritten and migrated to a
+different source of test data overnight—nor should they be! See our notes on
+[migrating to `test_data`
 incrementally](#factory--fixture-interoperability-guide)
 
 ### How will I handle merge conflicts in these SQL files if I have lots of people working on lots of feature branches all adding to the `test_data` database dumps?
@@ -1198,13 +1079,13 @@ this risk. The reason that the dumps are stored as plain SQL (aside from the
 fact that git's text compression is very good) is to make merge conflicts with
 other branches feasible, if not entirely painless.
 
-However, if your app is in the very initial stages of development and you're
-making breaking changes to your schema very frequently, our best advice is to
-hold off a bit on writing _any_ integration tests that depend on shared sources
-of test data, as they'll be more likely to frustrate your ability to rapidly
-iterate than detect bugs. Once you you have a reasonably stable feature working
-end-to-end, that's a good moment to start adding integration tests (and thus
-pulling in a test data gem like this one to help you).
+However, if your app is in the very initial stages of development or you're
+otherwise making breaking changes to your schema and data very frequently, our
+best advice is to hold off a bit on writing _any_ integration tests that depend
+on shared sources of test data (regardless of tool), as they'll be more likely
+to frustrate your ability to rapidly iterate than detect bugs. Once you you have
+a reasonably stable feature working end-to-end, that's a good moment to start
+adding integration tests—and perhaps pulling in a gem like this one to help you.
 
 ### Why can't I save multiple database dumps to cover different scenarios?
 
@@ -1220,8 +1101,7 @@ By having a single `test_data` database that grows up with your application just
 like `production` does—with both having their schemas and data migrated
 incrementally over time—your integration tests that depend on `test_data` will
 have an early opportunity to catch bugs that otherwise wouldn't be found until
-they were deployed into a long-lived environment like staging or (gasp!)
-production itself.
+they were deployed into a long-lived staging or (gasp!) production environment.
 
 ### Are you sure I should commit these SQL dumps? They're way too big!
 
@@ -1232,16 +1112,17 @@ cause:
    resetting (or rolling back) your changes and making another attempt at
    generating a more minimal set of test data
 
-2. If certain tables have a lot of records but aren't very relevant to your
-   tests (e.g. audit logs), you might consider either of these options:
+2. If some records persisted by your application aren't very relevant to your
+   tests, you might consider either of these options:
 
-    * Add those tables to the `config.non_test_data_tables` configuration array,
-      where they'd still be committed to git, but won't loaded by your tests
+    * If certain tables are necessary for running the app but aren't needed by
+      your tests, you can add them to the `config.non_test_data_tables`
+      configuration array. They'll still be committed to git, but won't loaded
+      by your tests
 
-    * Exclude data from those tables entirely by adding them to the
-      `config.dont_dump_these_tables` array. (Note that `rake test_data:load`
-      won't be able to restore these tables into your `test_data` environment,
-      so if the data is needed for the app to operate, you'll need to dump them)
+    * If the certain tables are not needed by your application or by your tests
+      (e.g. audit logs), add them to the `config.dont_dump_these_tables` array,
+      and they won't be persisted by `rake test_data:dump`
 
 3. If the dumps are _necessarily_ really big (some apps are complex!), consider
    looking into [git-lfs](https://git-lfs.github.com) for tracking them without
@@ -1264,7 +1145,7 @@ test data loaded from this gem or any other:
 def test_exclude_cancelled_orders
   good_order = Order.new
   bad_order = Order.new(cancelled: true)
-  user = User.create!(orders: good_order, bad_order)
+  user = User.create!(orders: [good_order, bad_order])
 
   result = user.active_orders
 
@@ -1273,17 +1154,18 @@ def test_exclude_cancelled_orders
 end
 ```
 
-This test is simple, self-contained, clearly denotes
-[arrange-act-assert](https://github.com/testdouble/contributing-tests/wiki/Arrange-Act-Assert),
-and (most importantly) will only fail if the functionality stops working.
-Maximizing the number of tests that can be written expressively and succinctly
-without the aid of shared test data is a laudable goal that more teams should
-embrace.
+This test is simple, self-contained, clearly demarcates the
+[arrange-act-assert](https://github.com/testdouble/contributing-tests/wiki/Arrange-Act-Assert)
+phases, and (most importantly) will only fail if the functionality stops
+working. Maximizing the number of tests that can be written expressively and
+succinctly without the aid of shared test data is a laudable goal that more
+teams should embrace.
 
 However, what if the code you're writing doesn't need 3 records in the database,
-but 30? Writing that much test setup would be painstaking and—despite being
-fully-encapsulated—hard for readers to understand what's going on. At that
-point, you have two options:
+but 30? Writing that much test setup would be painstaking, despite being
+fully-encapsulated. Long test setup is harder for others to read and understand.
+And because that setup depends on more of your system's code, it will have more
+reasons to break as your codebase changes. At that point, you have two options:
 
 1. Critically validate your design: why is it so hard to set up? Does it
    _really_ require so much persisted data to exercise this behavior? Would a
@@ -1294,8 +1176,8 @@ point, you have two options:
    [subject](https://github.com/testdouble/contributing-tests/wiki/Subject)
    instead of loading everything from the database? When automated testing is
    saved for the very end of a feature's development, it can feel too costly to
-   reexamine design decisions like this, but it's valuable feedback all the
-   same. *Easy to test code is easy to use code*
+   reexamine design decisions like this, but it can be valuable to consider all
+   the same. *Easy to test code is easy to use code*
 
 2. If the complex setup is a necessary reality of the situation that your app
    needs to handle (and it often will be!), then having _some_ kind of shared
@@ -1304,16 +1186,17 @@ point, you have two options:
 
 As a result, there is no one-size-fits-all approach. Straightforward behavior
 that can be invoked with a clear, concise test has no reason to be coupled to a
-shared source of test data. Subtle behavior that requires lots of
-carefully-arranged data would see its tests grow unwieldy without something to
-help populate that data. So both kinds of test clearly have their place.
+shared source of test data. Meanwhile, tests of more complex behaviors that
+require lots of carefully-arranged data might be unmaintainable without a shared
+source of test data to lean on. So both kinds of test clearly have their place.
 
 But this is a pretty nuanced discussion that can be hard to keep in mind when
 under deadline pressure or on a large team where building consensus around norms
 is challenging. As a result, leaving the decision of which type of test to write
 to spur-of-the-moment judgment is likely to result in inconsistent test design.
 Instead, you might consider separating these two categories into separate test
-types or suites.
+types or suites, with simple heuristics to determine which types of code demand
+which type of test.
 
 For example, it would be completely reasonable to load this gem's test data for
 integration tests, but not for basic tests of models, like so:
@@ -1321,21 +1204,13 @@ integration tests, but not for basic tests of models, like so:
 ```ruby
 class ActionDispatch::IntegrationTest
   setup do
-    TestData.load
-  end
-
-  teardown do
-    TestData.rollback
+    TestData.uses_test_data
   end
 end
 
 class ActiveSupport::TestCase
   setup do
-    TestData.truncate
-  end
-
-  teardown do
-    TestData.rollback(:after_data_truncate)
+    TestData.uses_clean_slate
   end
 end
 ```
@@ -1344,6 +1219,120 @@ In short, this skepticism is generally healthy, and encapsulated tests that
 forego reliance on shared sources of test data should be maximized. For
 everything else, there's `test_data`.
 
+### I'm worried my tests aren't as fast as they should be
+
+The `test_data` gem was written to enable tests that are not only more
+comprehensible and maintainable over the long-term, but also _much faster_ to
+run. That said—and especially if you're adding `test_data` to an existing test
+suite—care should be taken to audit everything the suite does between tests in
+order to optimize its overall runtime.
+
+#### Randomized test order leading to data churn
+
+Generally speaking, randomizing the order in which tests run is an unmitigated
+win: randomizing helps you catch any unintended dependency between two tests
+early, when it's still cheap & easy to fix. However, if your tests use different
+sources of test data (e.g. some call `TestData.uses_test_data` and some call
+`TestData.uses_clean_slate`), it's very likely that randomizing your tests will
+result in a significantly slower overall test suite. Instead, if you group tests
+that use the same type of test data together (e.g. by separating them into
+separate suites), you might find profound speed gains.
+
+To illustrate this, suppose you had 5 tests that relied on your `test_data` data
+and 5 that relied on Rails fixtures. If all of these tests ran in random order
+(the default), you might see the following behavior at run-time:
+
+```
+$ bin/rails test test/example_test.rb
+Run options: --seed 63999
+
+# Running:
+
+   test_data -- loading test_data SQL dump
+.  fixtures  -- truncating tables, loading Rails fixtures
+.  fixtures  -- rolling back to Rails fixtures
+.  test_data -- rolling back to clean test_data
+.  fixtures  -- truncating tables, loading Rails fixtures
+.  test_data -- rolling back to clean test_data
+.  fixtures  -- truncating tables, loading Rails fixtures
+.  test_data -- rolling back to clean test_data
+.  fixtures  -- truncating tables, loading Rails fixtures
+.  test_data -- rolling back to clean test_data
+.
+
+Finished in 2.449957s, 4.0817 runs/s, 4.0817 assertions/s.
+10 runs, 10 assertions, 0 failures, 0 errors, 0 skips
+```
+
+So, what can you do to speed this up? The most effective strategy to avoiding
+this churn is to group the execution of each tests that use each source of test
+data into sub-suites that are run serially, on e after the other.
+
+* If you're using Rails' defualt Minitest, we wrote a gem called
+  [minitest-suite](https://github.com/testdouble/minitest-suite) to accomplish
+  exactly this. Just declare something like `suite :test_data` or `suite
+  :fixtures` at the top of each test class
+* If you're using RSpec, the [suite option combined with a custom
+  ordering](https://gist.github.com/myronmarston/8fea012b9eb21b637335bb29069bce6b)
+  can accomplish this. You might also consider using
+  [tags](https://relishapp.com/rspec/rspec-core/v/3-10/docs/command-line/tag-option)
+  to organize your tests by type, but you'll likely have to
+  run a separate CLI invocation for each to avoid the tests from being
+  interleaved
+
+Here's what the same example would do at run-time after adding
+[minitest-suite](https://github.com/testdouble/minitest-suite):
+
+```
+$ bin/rails test test/example_test.rb
+Run options: --seed 50105
+
+# Running:
+
+   test_data -- loading test_data SQL dump
+.  test_data -- rolling back to clean test_data
+.  test_data -- rolling back to clean test_data
+.  test_data -- rolling back to clean test_data
+.  test_data -- rolling back to clean test_data
+.  fixtures -- truncating tables, loading Rails fixtures
+.  fixtures -- rolling back to clean fixtures
+.  fixtures -- rolling back to clean fixtures
+.  fixtures -- rolling back to clean fixtures
+.  fixtures -- rolling back to clean fixtures
+.
+
+Finished in 2.377050s, 4.2069 runs/s, 4.2069 assertions/s.
+10 runs, 10 assertions, 0 failures, 0 errors, 0 skips
+```
+
+By grouping the execution in this way, the most expensive operations will
+usually only be run once: at the beginning of the first test in each suite.
+
+#### Expensive data manipulation
+
+If you're doing anything repeatedly that's data-intensive in your test setup
+after calling one of the `TestData.uses_*` methods, that operation is being
+repeated once per test, which could be very slow. Instead, you might consider
+moving that behavior into a [lifecycle hook](#lifecycle-hooks).
+
+Any code passed to a lifecycle hook will only be executed when data is
+_actually_ loaded or truncated and its effect will be included in the
+transaction savepoint that the `test_data` gem rolls back between tests.
+Seriously, appropriately moving data adjustments into these hooks can cut your
+test suite's runtime by an order of magnitude.
+
+#### Redundant test setup tasks
+
+One of the most likely sources of unnecessary slowness is redundant test
+cleanup. The speed gained from sandwiching every expensive operation between
+transaction savepoints can be profound… but can also easily be erased by a
+single before-each hook calling
+[database_cleaner](https://github.com/DatabaseCleaner/database_cleaner) to
+commit a truncation of the database. As a result, it's worth taking a little
+time to take stock of everything that's called between tests during setup &
+teardown to ensure multiple tools aren't attempting to clean up the state of the
+database and potentially interfering with one another.
+
 ## Code of Conduct
 
 This project follows Test Double's [code of