test_data 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 492abd0bddc1329c073d45cb984dd60aa374f3520c6d3362bec34ece165f0407
-  data.tar.gz: efee863beeba57aa27e98d8b833ca0398d022baaa710b8a741d8da3995a71dce
+  metadata.gz: b4b24762c44d8997a2c66d9dde519931efe100390e3f075defdbbc777cb6a1c6
+  data.tar.gz: 5709a9832370b6047d1f3c68b837558a62fd858912b6d9f9afb41e3a7119898f
 SHA512:
-  metadata.gz: 1796bcb024853380c7a387f5f69d8b564ca78c4318fbf0a3c526546c5000fb5f676cc846a0541443c5d53e664f3b74d1970df4526d12b7f931209e9d78cdb684
-  data.tar.gz: b77b0c1a24a806ac817d516173a6f68b9e7d63ca088bae6cc32de41c688df0c296a1eedf7e7bde81ce46faba76301b98fde0f1fd1a2ccc1842f9095fdbafc132
+  metadata.gz: 448a864a21894a44ffa3408763cbe0c92a7240da6612d2409dcbe494b00069dfc0138a3e9de254bbf965faef9e1e39e92eda203ef47d202b733b44381c32df7b
+  data.tar.gz: cdf0687b88e0a2692eecfcaa25f24ae3b25b0383f99356039cbf00b1e432899933a46f52ad45d0abe16c3f86d006401ba1fba91478f231bbfe19bc551bfd4386

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/CHANGELOG.md

@@ -1,4 +1,20 @@
-# unreleased
+# 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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    test_data (0.1.0)
+    test_data (0.2.0)
       railties (~> 6.0)
 
 GEM

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

@@ -1,5 +1,9 @@
 # The `test_data` gem
 
+**HEADS UP: 0.2.0 made a whole bunch of breaking changes to the public API and
+we haven't finished rewriting the README yet. Please bear with us while we work
+through it. 🙇**
+
 `test_data` does what it says on the tin: it provides a fast & reliable system
 for managing your Rails application's test data.
 
@@ -18,9 +22,9 @@ 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 each of your tests will against
+  pristine data, 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
@@ -48,15 +52,12 @@ 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)
+    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)
@@ -70,15 +71,11 @@ application.
     * [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.uses_test_data](#testdatauses_test_data)
+    * [TestData.uses_clean_slate](#testdatauses_clean_slate)
     * [TestData.prevent_rails_fixtures_from_loading_automatically!](#testdataprevent_rails_fixtures_from_loading_automatically)
-    * [TestData.load_rails_fixtures](#testdataload_rails_fixtures)
+    * [TestData.uses_rails_fixtures(self)](#testdatauses_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)
 7. [Code of Conduct](#code-of-conduct)
@@ -140,21 +137,29 @@ Created database 'yourappname_test_data'
 ------------
 
 (1 row)
+
+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 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!
+The purpose of the `test_data` database is to provide a sandbox in which you
+will manually generate test data by playing aroundo with your app. Once you've
+craeted enough data to drive tests of your application, `test_data` facilitates
+dumping the resulting state of the `test_data` database so that your tests can
+load it into the `test` database. 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!
 
 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!)
+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!)
 
 ### Step 2: Create some test data
 
@@ -220,9 +225,9 @@ This will dump three files into `test/support/test_data`:
 * Non-test data (`ar_internal_metadata` and `schema_migrations` by default) in
   `non_test_data.sql`
 
-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,8 +238,8 @@ 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
@@ -248,92 +253,79 @@ 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.
+accomplishes this with its [TestData.uses_test_data](#testdatauses_test_data)
+method.
 
 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`:
+data with every test, you could load them 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:
+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
+with covering each test's behavior 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 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:
+you have existing tests that use factories instead), you probably want to use
+[TestData.uses_clean_slate](#testdatauses_clean_slate) to clear data generated
+by this gem out before they run. One way to do that would be to define two test
+types:
 
 ```ruby
 # Tests using data created by `test_data`
 class TestDataTestCase < ActiveSupport::TestCase
   setup do
-    TestData.load
-  end
-
-  teardown do
-    TestData.rollback
+    TestData.uses_test_data
   end
 end
 
-# Tests that don't need a shared data source
-class SomeModelTestCase < ActiveSupport::TestCase
+# Tests that don't rely on test_data or Rails fixtures:
+class CleanSlateTestCase < ActiveSupport::TestCase
   setup do
-    TestData.truncate
-  end
-
-  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)
+    TestData.uses_clean_slate
   end
 end
-
 ```
 
 ### 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 persist your test data manually inside each
+and every test.
+
+But `test_data` stores your data as SQL, as opposed to Ruby or YAML. So
+providing a straightforward way to maintain it as your application grows and
+your schema evolves is a going concern of this gem.
+
+Fortunately, because your `test_data` database needs to be maintained for the
+entire life of your application and because production databases need the same
+thing, we already have a fantastic tool for the job: [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.
@@ -343,7 +335,8 @@ 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:
 
 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`
+   files (i.e. if someone has updated the SQL dump and your local Postgres
+   database is out of date), drop it with `rake test_data:drop_database`
 
 2. Load your schema & data into the `test_data` database with `rake
    test_data:load`
@@ -402,20 +395,23 @@ 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
-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.
+work" after adding `TestData.uses_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.uses_test_data` 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. Care should be taken to preserve the conceptual encapsulation of each
+test, however, as naively squashing errors can introduce coupling between your
+factories and your `test_data` database that inadvertently tangles the two
+together (where both test data sources become necessary to interact with the
+system).
 
 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
@@ -625,7 +621,7 @@ Here's what you can do if you can't get your fixtures to play nicely with your
    available to these tests
 
 3. In tests that need fixtures, call
-   [TestData.load_rails_fixtures](#testdataload_rails_fixtures)
+   [TestData.load_rails_fixtures(self)](#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
@@ -641,7 +637,7 @@ test to get it passing:
 ```ruby
 class AnExistingFixtureUsingTest < ActiveSupport::Testcase
   def setup
-    TestData.load_rails_fixtures
+    TestData.load_rails_fixtures(self)
     # pre-existing setup
   end
 
@@ -662,7 +658,8 @@ 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.*
+[TestData.load_rails_fixtures(self)](#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
@@ -676,7 +673,7 @@ class ActiveSupport::TestCase
       fixtures :all
 
       setup do
-        TestData.load_rails_fixtures
+        TestData.load_rails_fixtures(self)
       end
 
       teardown do
@@ -1042,11 +1039,11 @@ 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.
+If you're using
+[TestData.load_rails_fixtures(self)](#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
 
@@ -1101,7 +1098,10 @@ 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.
+into an effectively empty test database inside a nested transaction. Because the
+feature uses Rails built-in fixtures-loading code as well as its caching
+mechanism, the method must be passed an instance of the running test class (in
+a Minitest `setup` hook, that means `TestData.load_rails_fixtures(self)`)
 
 Using this feature requires that you've:
 

data/example/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    test_data (0.0.2)
+    test_data (0.2.0)
       railties (~> 6.0)
 
 GEM

data/example/config/credentials.yml.enc

@@ -1,2 +1 @@
-F/lkjSeOZwy+4IAYNV/+5sOwn9XOGjyNNvDkNyrpRG0kqoP8jmI4GE8mb73fdRIVoI9H7zefa3GxQ7R+udxqKWMLwAtSgTt+YGf5Eng0IzRBPp7hY2gIxFO0b84/+eG4Q6rD5xsg0kogzK3Ab4jj7f8Ci8vzFclSwqyUwP6TBCnaZJYsLMcNmF3tKBnWrJNKcQJ6Rj6/J2OH/nNi5x+KbsIgbARCJsZEK8PjD+cx8Qs9Cvk99Pj3VljLmjYA0L3jx1uCKahr0tzkkPkujBCKci05QHF/+vq0fcFduxc5wwlf5qMf7wGayz8i1YONyM9yORMrcnvSz/6AKC25np24+nmvZNsuVqtyoA4LRL+k3RBCMKo867FkwJmmGkhZSAFplFdQ2C0qJ+Gzem6UD6Lr70klDaUq1hITDqIc--nPRVkeqxjYlJDoKQ--Iu4hCDiJSpYuKL56Z/CUjA==
-
+5AstMrUHKXO5ed+i/hI/GnVm5IB525qXJOqPHvqfqhJSxEJSyfwKfQURigix3HsTcOwcPFIU6vPSC20bi5H8CQ7SHnYdHJuGB2T3WC9iiNiSBz49HaZoYX8ucHYoMMBbC+0u/6diYLW8ZTKR2Ab7bn4r1lkGzQjJe5clic5wNto7btjAbStXyAOHZCStXfnOFgQQhVjZno3iS7c279jaVYkYpZ12P5LbMxcJO4ipWfFexCzysIQu/WSPfmNMcvrIPijmPBvkVMJuhhDzd0yk1ysJu8jJMa8FJKx9aVd7Bes/k8Nywd04GDY6eSxyH6gkoG+BeQeqW3ig1XsuOWvx39qE9EQAcsgT13uxGc8M4wBKqIdSoibPl/79kTB843rnGlL8X/pKipJYczYJxazLSojwcQSto1UeIqQFWaDPQhz0--C7YAj7j4YQdWGiMG--JFTyHZbGKXiCdfZoBmF3xw==

data/example/spec/rails_helper.rb

@@ -32,7 +32,7 @@ rescue ActiveRecord::PendingMigrationError => e
 end
 RSpec.configure do |config|
   # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
-  config.fixture_path = "#{::Rails.root}/spec/fixtures"
+  config.fixture_path = "#{::Rails.root}/test/fixtures"
 
   # If you're not using ActiveRecord, or you'd prefer not to run each of your
   # examples within a transaction, remove the following line or assign false