test_data 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb3ddac1f4153d6b3995975a7b3016089c0f64ef783b45af3b21d5a2ea00f671
-  data.tar.gz: 0d45ac53789a0015c88f6d3f8cc545409c4c42fbd112f63edb1489cc5d603c7c
+  metadata.gz: 492abd0bddc1329c073d45cb984dd60aa374f3520c6d3362bec34ece165f0407
+  data.tar.gz: efee863beeba57aa27e98d8b833ca0398d022baaa710b8a741d8da3995a71dce
 SHA512:
-  metadata.gz: 7368531e5dcc41910350809eb2d5a36763f395a749f69dbe85579792cca513fbe5663a0c02c2595009617a63d274caba073572a854cb3f334a07b4b57ce98ff8
-  data.tar.gz: 358f87044733160c2d4ee49b6e8ec1b422cc08e6aa4f0a12a7b47f190899b67ea707159e5cc2e66c307934ad4c1315c45fcbde4666eeb5497b98868afbae31ee
+  metadata.gz: 1796bcb024853380c7a387f5f69d8b564ca78c4318fbf0a3c526546c5000fb5f676cc846a0541443c5d53e664f3b74d1970df4526d12b7f931209e9d78cdb684
+  data.tar.gz: b77b0c1a24a806ac817d516173a6f68b9e7d63ca088bae6cc32de41c688df0c296a1eedf7e7bde81ce46faba76301b98fde0f1fd1a2ccc1842f9095fdbafc132

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+# unreleased
+
+- New feature: `TestData.load_rails_fixtures` to override default fixtures
+  behavior by loading it in a nested transaction after `TestData.truncate`
+- Breaking change: move transactions configuration out of `TestData.load` and
+  instead a global setting for `TestData.config` named
+  `use_transactional_data_loader`
+- Cascades truncation of test_data tables unless they're explicitly specified by
+  the truncate_these_test_data_tables` option
+- Add secrets.yml and cable.yml generators to `test_data:configure` task
+- Print the size of each dump and warn when dump size reaches certain thresholds
+  or increases significantly in the `test_data:dump` task
+
 # 0.0.2
 
 - Make the rest of the gem better

data/Gemfile.lock

@@ -1,26 +1,26 @@
 PATH
   remote: .
   specs:
-    test_data (0.0.2)
+    test_data (0.1.0)
       railties (~> 6.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (6.1.3.1)
-      actionview (= 6.1.3.1)
-      activesupport (= 6.1.3.1)
+    actionpack (6.1.4)
+      actionview (= 6.1.4)
+      activesupport (= 6.1.4)
       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.3.1)
-      activesupport (= 6.1.3.1)
+    actionview (6.1.4)
+      activesupport (= 6.1.4)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activesupport (6.1.3.1)
+    activesupport (6.1.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -29,18 +29,18 @@ GEM
     ast (2.4.2)
     builder (3.2.4)
     coderay (1.1.3)
-    concurrent-ruby (1.1.8)
+    concurrent-ruby (1.1.9)
     crass (1.0.6)
     erubi (1.10.0)
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
-    loofah (2.9.1)
+    loofah (2.10.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     method_source (1.0.0)
-    mini_portile2 (2.5.1)
+    mini_portile2 (2.5.3)
     minitest (5.14.4)
-    nokogiri (1.11.3)
+    nokogiri (1.11.7)
       mini_portile2 (~> 2.5.0)
       racc (~> 1.4)
     parallel (1.20.1)
@@ -58,11 +58,11 @@ GEM
       nokogiri (>= 1.6)
     rails-html-sanitizer (1.3.0)
       loofah (~> 2.3)
-    railties (6.1.3.1)
-      actionpack (= 6.1.3.1)
-      activesupport (= 6.1.3.1)
+    railties (6.1.4)
+      actionpack (= 6.1.4)
+      activesupport (= 6.1.4)
       method_source
-      rake (>= 0.8.7)
+      rake (>= 0.13)
       thor (~> 1.0)
     rainbow (3.0.0)
     rake (13.0.3)

data/LICENSE.txt

@@ -1,9 +1,4 @@
-Copyright (c) 2019 Test Double, LLC
-
-Portions of these files Copyright (c) 2012-18 Bozhidar Batsov:
-  - config/base.yml
-  - lib/standard/cop/block_single_line_braces.rb
-  - test/cop_invoker.rb
+Copyright (c) 2022 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

@@ -1,48 +1,99 @@
 # The `test_data` gem
 
-`test_data` is what it says on the tin: a fast & reliable system for managing
-your Rails application's test data.
+`test_data` does what it says on the tin: it provides a fast & reliable system
+for managing your Rails application's test data.
 
 The gem serves as both an alternative to
 [fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)
 & [factory_bot](https://github.com/thoughtbot/factory_bot), as well a broader
-workflow for building high-performance test suites that will scale with your
-application.
+workflow for building test suites that will scale gracefully as your application
+grows in size and complexity.
 
 What it does:
 
-* Establishes a fourth Rails environment named `test_data` designed to help you
-  create a universe of data your tests can rely on by simply using your
-  application. No Ruby DSL, no YAML files, no precarious approximations of
-  realism: **real data created by your app**
+* Establishes a fourth Rails environment (you can [define custom Rails
+  environments](https://guides.rubyonrails.org/configuring.html#creating-rails-environments)!)
+  named `test_data`, which you'll use to create a universe of data for your
+  tests by simply running and using your application. No Ruby DSL, no YAML
+  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 gracefully: tests that need access to
+  tests. Common edge cases are handled seamlessly. Tests that need access to
   your data will see it and tests that don't, won't
 
-* Safeguards your tests from flaky failures and supercharges their speed by
-  providing a sophisticated transaction manager that isolates each test's
-  changes to your data while ensuring your data is only loaded once
+* 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, unreliable, and brittle, then this gem is
-for you! And even if you're [a factory_bot
+will eventually grow to become slow, incomprehensible, and brittle, 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).
 
-_[Because the gem is still brand new, it makes a number of
+_[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.]_
 
+## Documentation
+
+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.
+
+1. [Getting Started Guide](#getting-started-guide)
+    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)
+    * [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)
+    * [test_data:install](#test_datainstall)
+    * [test_data:configure](#test_dataconfigure)
+    * [test_data:verify_config](#test_dataverify_config)
+    * [test_data:initialize](#test_datainitialize)
+    * [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.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)
+5. [Assumptions](#assumptions)
+6. [Fears, Uncertainties, and Doubts](#fears-uncertainties-and-doubts) (Q & A)
+7. [Code of Conduct](#code-of-conduct)
+8. [Changelog](/CHANGELOG.md)
+9. [MIT License](/LICENSE.txt)
+
 ## Getting started guide
 
 This guide will walk you through setting up `test_data` in your application. You
 might notice that it's more complicated than installing a gem and declaring some
-default `Widget` attributes! The truth is that designing robust and reliable
-test data that is inherently complex and takes some thoughtful planning. There
-are plenty of shortcuts available, but experience has shown they tend to
-collapse under their own weight as your app scales and your team grows—exactly
-when fast & reliable tests are most valuable.
+default `Widget` attributes! The hard truth is that designing robust and
+reliable test data is an inherently complex problem and takes some thoughtful
+planning. There are plenty of shortcuts available, but experience has shown they
+tend to collapse under their own weight as your app scales and your team
+grows—exactly when having a suite of fast & reliable tests is most valuable.
 
 And if you get stuck or need help as you're getting started, please feel free to
 [ask us for help](https://github.com/testdouble/test_data/discussions/new)!
@@ -62,14 +113,15 @@ end
 ```
 
 Since the `test_data` environment is designed to be used similarly to
-`development` (i.e. with a running server and interacting via a browser) the
-`:test_data` gem group should probably include everything that's available to
-the `:development` group.
+`development` (i.e. with a running server and interacting via a browser), any
+gems in your `:development` gem group should likely be included in a
+`:test_data` gem group as well.
 
 #### Configuring the gem and initializing the database
 
-The gem ships with a number of Rake tasks, including `test_data:install`, which
-will generate the necessary configuration and initialize a `test_data` database:
+The gem ships with a number of Rake tasks, including
+[test_data:install](#test_datainstall), which will generate the necessary
+configuration and initialize a `test_data` database:
 
 ```
 $ bin/rake test_data:install
@@ -118,6 +170,10 @@ environment variable:
 $ RAILS_ENV=test_data bin/rails server
 ```
 
+_[If you're using [webpacker](https://github.com/rails/webpacker), you may also
+need to start its development server as well with `RAILS_ENV=test_data
+bin/webpack-dev-server`]_
+
 Because `test_data` creates a full-fledged Rails environment, you can run any
 number of Rails commands or Rake tasks against its database by setting
 `RAILS_ENV=test_data`, either in your shell environment or with each command
@@ -173,14 +229,16 @@ everything looks good—commit them. (And if the files are gigantic or full of
 noise, you might find [these ideas
 helpful](#are-you-sure-i-should-commit-these-sql-dumps-theyre-way-too-big)).
 
-_[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`
+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
 fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)
-from a set of YAML files—the major difference being how the data is authored.]_
+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.
 
 ### Step 4: Load your data in your tests
 
@@ -189,9 +247,9 @@ 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. The `test_data` gem accomplishes this with its
-[TestData.load](#testdataload) and [TestData.rollback](#testdatarollback)
-methods.
+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.
 
 If you're using (Rails' default)
 [Minitest](https://github.com/seattlerb/minitest) and want to include your test
@@ -199,11 +257,11 @@ data with every test, you can add these hooks to `ActiveSupport::TestCase`:
 
 ```ruby
 class ActiveSupport::TestCase
-  def setup
+  setup do
     TestData.load
   end
 
-  def teardown
+  teardown do
     TestData.rollback
   end
 end
@@ -224,47 +282,52 @@ RSpec.configure do |config|
 end
 ```
 
-That should be all you need to have access to your test data in all of your
-tests, along with the speed and data integrity of wrapping each test in an
-always-rolled-back transaction. For more information on how all this works, see
-the [API reference](#api-reference).
+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 you _don't_ want all of your Rails-aware tests to see this test data (suppose
-you have existing tests that use factories or fixtures instead), you probably
+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:
 
 ```ruby
 # Tests using data created by `test_data`
 class TestDataTestCase < ActiveSupport::TestCase
-  def setup
+  setup do
     TestData.load
   end
 
-  def teardown
+  teardown do
     TestData.rollback
   end
 end
 
-# Tests using data created by `factory_bot`
-class FactoryBotTestCase < ActiveSupport::TestCase
-  include FactoryBot::Syntax::Methods
-
-  def setup
+# Tests that don't need a shared data source
+class SomeModelTestCase < ActiveSupport::TestCase
+  setup do
     TestData.truncate
   end
 
-  def teardown
+  def test_some_model_does_stuff
+    some_model = SomeModel.create!
+
+    result = some_model.does_stuff
+
+    assert_equal :cool_stuff, result
+  end
+
+  teardown do
     TestData.rollback(:after_data_truncate)
   end
 end
 
 ```
 
-For more thoughts on migrating to `test_data` when you have existing tests,
-[some ideas are discussed
-here](#we-already-have-thousands-of-tests-that-depend-on-rails-fixtures-or-factory_bot-can-we-start-using-test_data-without-throwing-them-away-and-starting-over).
-
 ### Step 5: Keeping your test data up-to-date
 
 Because your app relies on its tests and your tests rely on their test data,
@@ -282,17 +345,18 @@ data. Here's a rough outline to updating your `test_data` database:
 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`
 
-2. Load your schema & data into the database with `rake test_data:load`
+2. Load your schema & data into the `test_data` database with `rake
+   test_data:load`
 
 3. Run any pending migrations with `RAILS_ENV=test_data bin/rake db:migrate`
 
 4. If you need to create any additional data, start up the server
-   (`RAILS_ENV=test_data bin/rails s`), just like [Step
+   (`RAILS_ENV=test_data bin/rails s`), just like in [Step
    2](#step-2-create-some-test-data)
 
 5. Export your newly-updated `test_data` database with `rake test_data:dump`
 
-6. Ensure your tests are passing and commit the resulting SQL files
+6. Ensure your tests are passing and then commit the resulting SQL files
 
 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`
@@ -309,6 +373,361 @@ 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).]_
 
+## Factory & Fixture Interoperability Guide
+
+Let's be real, most Rails apps already have some tests, and most of those test
+suites will already be relying on
+[factory_bot](https://github.com/thoughtbot/factory_bot) or Rails' built-in
+[test
+fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures).
+While `test_data` is designed to be an alternative to both of these approaches
+to managing your test data, it wouldn't be practical to ask a team to rewrite
+all their existing tests in order to migrate to a different tool. That's why the
+`test_data` gem goes to great lengths to play nicely with your existing tests,
+while ensuring each test is wrapped in an isolated and fast always-rolled-back
+transaction—regardless if the test depends on `test_data`, factories, fixtures,
+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.
+
+### Using `test_data` with `factory_bot`
+
+This section will document some thoughts and strategies for introducing
+`test_data` to a test suite that's already using `factory_bot`.
+
+#### Getting your factory tests passing after adding `test_data`
+
+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
+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:
+
+```ruby
+class AnExistingFactoryUsingTest < ActiveSupport::Testcase
+  def setup
+    TestData.truncate
+    # pre-existing setup
+  end
+
+  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:
+
+```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
+  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.
+
+### Using `test_data` with Rails fixtures
+
+While [Rails
+fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)
+are similar to factories, the fact that they're run globally by Rails and
+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:
+   [TestData.prevent_rails_fixtures_from_loading_automatically!](#testdataprevent_rails_fixtures_from_loading_automatically)
+   This will effectively turn
+   [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
+
+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
+
+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
+
+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
+    # 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.
+
 ## Rake Task Reference
 
 ### test_data:install
@@ -326,23 +745,43 @@ This task runs several generators:
   too! This gem adds a new `test_data` environment and database that's intended
   to be used to create and dump your test data. This new environment file loads
   your `development` environment's configuration and disables migration schema
-  dumps so that you can run migrations of your `test_data` database without
+  dumps so that you can run migrations against your `test_data` database without
   affecting your app's `schema.rb` or `structure.sql`.
 
-* `config/initializers/test_data.rb` - Calls [TestData.config](#testdataconfig)
-  with an empty block and comments documenting the currently-available options
-  and their default values
+* `config/initializers/test_data.rb` - Creates an initializer for the gem that
+  calls [TestData.config](#testdataconfig) with an empty block and comments
+  documenting the currently-available options and their default values
 
 * `config/database.yml` - This generator adds a new `test_data` section to your
   database configuration, named with the same scheme as your other databases
   (e.g. `your_app_test_data`). If your configuration resembles Rails' generated
-  database.yml and has a working `&default` alias, then this should "just work"
-
-* `config/webpacker.yml` - The gem has nothing to do with web assets or
-  webpacker, but webpacker will display some prominent warnings or errors if it
-  is loaded without a configuration entry for the currently-running environment,
-  so this generator defines an alias based on your `development` config and then
-  defines `test_data` as extending it
+  `database.yml` and has a working `&default` alias, then this should "just
+  work"
+
+* `config/webpacker.yml` - The gem has nothing to do with web assets, but
+  [webpacker](https://github.com/rails/webpacker) will display some prominent
+  warnings or errors if it is loaded without a configuration entry for the
+  currently-running environment, so this generator defines an alias based on
+  your `development` config and then defines `test_data` as extending it
+
+* `config/secrets.yml` - If your app still uses (the now-deprecated)
+  [secrets.yml](https://guides.rubyonrails.org/4_1_release_notes.html#config-secrets-yml)
+  file introduced in Rails 4.1, this generator will ensure that the `test_data`
+  environment is accounted for with a generated `secret_key_base` value. If you
+  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:`
+
+### test_data:verify_config
+
+This task will verify that your configuration appears to be valid by checking
+with each of the gem's generators to inspect your configuration files, and will
+error whenever a configuration problem is detected.
 
 ### test_data:initialize
 
@@ -353,22 +792,23 @@ 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` first if it contains outdated test data)
+   [test_data:drop_database](#test_datadrop_database) first if it contains
+   outdated test data)
 
 3. Checks to see if a dump of the database already exists (by default, stored in
    `test/support/test_data/`)
 
-    * If dumps do exist, it invokes `test_data:load` to load them into the
-      database
+    * If dumps do exist, it invokes [test_data:load](#test_dataload) to load
+      them into the database
 
     * Otherwise, it invokes the task `db:schema:load` and `db:seed` (similar to
-      the `db:setup` task)
+      Rails' built-in `db:setup` task)
 
 ### test_data:dump
 
 This task is designed to be run after you've created or updated your test data
-and you want to run tests against it. The task creates several plain SQL dumps
-from your `test_data` environment's 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`
 
@@ -389,7 +829,7 @@ options to control which tables are exported into which group.
 This task will load your SQL dumps into your `test_data` database by:
 
 1. Verifying the `test_data` environment's database is empty (creating it if it
-   doesn't exist)
+   doesn't exist and failing if it's not empty)
 
 2. Verifying that your schema, test data, and non-test data SQL dumps can be
    found at the configured paths
@@ -409,8 +849,10 @@ $ bin/rake test_data:dump
 ### test_data:create_database
 
 This task will create the `test_data` environment's database if it does not
-already exist. It also enhances Rails' `db:create` task so that `test_data` is
-created along with `development` and `test`.
+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_data:drop_database
 
@@ -449,6 +891,12 @@ TestData.config do |config|
   #   `data_dump_path` will be truncated
   # config.truncate_these_test_data_tables = nil
 
+  # 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
+
   # Log level (valid values: [:debug, :info, :warn, :error, :quiet])
   # Can also be set with env var TEST_DATA_LOG_LEVEL
   # config.log_level = :info
@@ -468,7 +916,7 @@ 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 free of potential data pollution from prior tests.
+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.)
@@ -477,22 +925,24 @@ 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. Starts the `:before_data_load` transaction
+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. Starts the `:after_data_load` transaction
+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.
+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 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.]_
+`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
 
@@ -501,15 +951,15 @@ 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 call
-`TestData.load(transactions: false)`.
+If you need to load the test data and commit it to the database, simply set
+`TestData.config.use_transactional_data_loader = false`.
 
-Once committed, figuring out when and how to clear it out after each test run
-then becomes an additional responsibility. Many folks use
+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 this gem offers a rudimentary
+this, while `test_data` offers a rudimentary
 [TestData.truncate](https://github.com/testdouble/test_data#testdatatruncate)
-method that can be passed `transactions: false` and which may be sufficient.
+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:
@@ -517,38 +967,39 @@ the full run of a test suite:
 ```ruby
 RSpec.configure do |config|
   config.before :all do
-    TestData.load(transactions: false)
+    TestData.load
   end
 
   config.after :all do
-    TestData.truncate(transactions: false)
+    TestData.truncate
   end
 end
 ```
 
-Note that subsequent `TestData.load(transactions: false)` 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.
+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 (`:before_data_load`, `:after_data_load`, and
-`:after_data_truncate`). In most cases you'll want to roll back to
+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. More details on rolling back to each of the
-gem's savepoints follows below.
+when called without an argument. If the specified savepoint isn't active,
+calling `rollback` is a no-op.
 
-#### Rolling back to after the data was loaded
+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:
 
-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.
+* `: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)
 
-(Calling `TestData.rollback` when no `:after_data_load` save point is active is
-a no-op.)
+More details on rolling back to each of the gem's savepoints follows below.
 
 #### Rolling back to before test data was loaded
 
@@ -558,13 +1009,10 @@ that depend on that data _not being there_, you probably want to call
 you can rewind to the moment just before your test data was loaded by calling
 `TestData.rollback(:before_data_load)`.
 
-(Calling `TestData.rollback` when no `:before_data_load` save point is active is
-a no-op.)
-
-**⚠️ Warning:** Repeatedly loading and rolling back to `:before_data_load` is
+**⚠️ 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 more times than is necessary. Consider using
+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
@@ -572,27 +1020,41 @@ 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, 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.
+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
 
-(Calling `TestData.rollback` when no `:after_data_truncate` save point is active
-is a no-op.)
+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 reset
-the state of your `test` database to support these tests, you have two options:
-(1) `TestData.rollback(:before_data_load)` and (2) `TestData.truncate`. As
-discussed above, the former will do the job, but may necessitate repetitive,
-slow reloads of your test data SQL file. `TestData.truncate`, meanwhile,
-truncates all the tables that `TestData.load` inserted into and then creates
-a savepoint nicknamed `:after_data_truncate`.
+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
@@ -611,28 +1073,54 @@ end
 ```
 
 By default, all tables for which there is an `INSERT INTO` statement in your
-test data SQL dump will be truncated, but you can 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.
+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.
 
-Because tests are usually run in a random order, some fault tolerance is built
-in:
+#### If you're not using transactions
 
-* If one test calls `TestData.rollback(:after_data_truncate)` in `teardown`, and
-  the next test calls `TestData.load` in `setup`, the gem will do the
-  probably-intended thing and rollback to `:after_data_load` so that the data is
-  available
+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.
 
-* If a test calls `TestData.truncate` and the `:after_data_truncate` savepoint
-  is rolled back outside the `TestData.rollback` method (e.g.
-  `ActiveRecord::Base.connection.rollback_transaction`), the method will first
-  check a memo written to `ar_internal_metadata` and recreate the
-  `:after_data_truncate` savepoint
+### TestData.prevent_rails_fixtures_from_loading_automatically!
 
-#### If you're not using transactions
+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.)
 
-Just [like TestData.load](#loading-without-transactions), you can call
-`TestData.truncate(transactions: false)` and it'll commit the truncation.
+### TestData.load_rails_fixtures
+
+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.
+
+Using this feature requires that you've:
+
+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)
+
+When you call this method, it will do the following:
+
+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`
+
+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).
 
 ## Assumptions
 
@@ -643,15 +1131,16 @@ yet. Here are some existing assumptions and limitations:
 
 * You're using Rails 6 or higher
 
-* Your app does not rely on Rails' [multi-database
+* Your app does not require Rails' [multi-database
   support](https://guides.rubyonrails.org/active_record_multiple_databases.html)
+  in order to be tested
 
 * Your app has the binstubs `bin/rake` and `bin/rails` that Rails generates and
-  they work (you can regenerate them with `rails app:update:bin`)
+  they work (protip: you can regenerate them with `rails app:update:bin`)
 
 * Your `database.yml` defines a `&default` alias from which to extend the
-  `test_data` database configuration (if it lacks one, you'll need specify the
-  database's configuration on your own)
+  `test_data` database configuration (if your YAML file lacks one, you can
+  always specify the `test_data` database configuration manually)
 
 ## Fears, Uncertainties, and Doubts
 
@@ -672,7 +1161,7 @@ If you use `factory_bot` and all of these are true:
   menu
 
 * Your default factories generate models that resemble real records created by
-  your production application, as opposed to resembling the
+  your production application, as opposed to representing the
   sum-of-all-edge-cases with every boolean flag enabled and optional attribute
   set
 
@@ -690,7 +1179,7 @@ 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`
-incrementally](#we-already-have-thousands-of-tests-that-depend-on-rails-fixtures-or-factory_bot-can-we-start-using-test_data-without-throwing-them-away-and-starting-over)
+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?
 
@@ -717,124 +1206,6 @@ 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).
 
-### We already have thousands of tests that depend on Rails fixtures or factory_bot; can we start using this gem without throwing them away and starting over?
-
-Yes, `test_data` was written with this sort of incremental transition in mind!
-
-Our strongest recommendation is to write each test against only a single source
-of test data. Integration tests inevitably become coupled to the data that's
-available to them, and if a test has access to fixtures, records created by a
-factory, and a `test_data` SQL dump, it is likely to unintentionally become
-dependent on all three. 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 for each
-test.
-
-The rest comes down to how you want to organize your tests, as discussed below.
-
-#### Approach 1: test-data-specific test subclasses
-
-If you're currently using `factory_bot`, you might already have something like
-this in your `test_helper.rb` file:
-
-```ruby
-class ActiveSupport::TestCase
-  include FactoryBot::Syntax::Methods
-end
-```
-
-To avoid including these methods with every Rails-aware test, you might consider
-pushing down new classes for each source of test data:
-
-```ruby
-# Tests using data created by `test_data`
-class TestDataTestCase < ActiveSupport::TestCase
-  def setup
-    TestData.load
-  end
-
-  def teardown
-    TestData.rollback
-  end
-end
-
-# Tests using data created by `factory_bot`
-class FactoryBotTestCase < ActiveSupport::TestCase
-  include FactoryBot::Syntax::Methods
-
-  def setup
-    TestData.truncate
-  end
-
-  def teardown
-    TestData.rollback(:after_data_truncate)
-  end
-end
-```
-
-From there, the class that each test extends will indicate which test data
-strategy it uses.
-
-This approach may work in simple cases, but won't be well-suited to if you're
-already extending any of the half-dozen subclasses of `ActiveSupport::TestCase`
-provided by Rails (or their analogues from
-[rspec-rails](https://github.com/rspec/rspec-rails)).
-
-#### Approach 2: write a helper method to set things up for you
-
-Every situation will be different, but one strategy that suits a lot of
-circumstances would be to write a method 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:
-
-```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
-  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
-```
-
 ### Why can't I save multiple database dumps to cover different scenarios?
 
 For the same reason you (probably) don't have multiple production databases: the
@@ -854,7 +1225,8 @@ production itself.
 
 ### Are you sure I should commit these SQL dumps? They're way too big!
 
-If the dump files generated by `test_data:dump` are absolutely massive, consider the cause:
+If the dump files generated by `test_data:dump` seem massive, consider the
+cause:
 
 1. If you inadvertently created more data than necessary, you might consider
    resetting (or rolling back) your changes and making another attempt at
@@ -867,7 +1239,9 @@ If the dump files generated by `test_data:dump` are absolutely massive, consider
       where they'd 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
+      `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)
 
 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
@@ -903,7 +1277,7 @@ 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 an external helper is a laudable goal that more teams should
+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,
@@ -913,8 +1287,10 @@ 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
-   plain old Ruby object that defined a pure function have been feasible? Could
-   a model instance or even a `Struct` be passed to the
+   [plain old Ruby
+   object](https://steveklabnik.com/writing/the-secret-to-rails-oo-design) that
+   defined a pure function have been feasible? Could a model instance or even a
+   `Struct` be passed to the
    [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
@@ -928,9 +1304,9 @@ 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 data to be
-exercised 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. 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.
 
 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
@@ -944,21 +1320,21 @@ integration tests, but not for basic tests of models, like so:
 
 ```ruby
 class ActionDispatch::IntegrationTest
-  def setup
+  setup do
     TestData.load
   end
 
-  def teardown
+  teardown do
     TestData.rollback
   end
 end
 
 class ActiveSupport::TestCase
-  def setup
+  setup do
     TestData.truncate
   end
 
-  def teardown
+  teardown do
     TestData.rollback(:after_data_truncate)
   end
 end