test_data 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84a9fc3fe7b3dda0cf1ebdc775c9191757d21de11e033189c6450b91f63332e7
-  data.tar.gz: 0a47179f0607d9c57f63706e35de176b14d93989c6e5406094524a0fb3b09704
+  metadata.gz: 4178759cb111f2f83cad983712c1b82220aa09ecdbd7d710b7517974c63fee8c
+  data.tar.gz: dc83bc5526b88239ba2d55661a8ab61865a7a8d19f8c195d2caa41e00125b7e5
 SHA512:
-  metadata.gz: 4c10de3f9e234ae53e47553d099612dc7474cb3e98022b6a953d60beb8da3f502b00f506f29729dad0a9eb37c8e7f05a662263963300d7c531f48fef660c9173
-  data.tar.gz: d718e34070ca15bd9d0e27c75789e170e42da183fac8efc973404d9cea909ce984453f9393277b37ad36ff42fa4866c66de14d2a82a149ae536f0555c2f5f52d
+  metadata.gz: 7aba197cb61bff3286913de3678a6df0f4595774bb7283228de6e26ae64fb03586e8233362bf9cea3ef041cc1e53a539a323e3c5d59fb6d16470f6db904402e5
+  data.tar.gz: bc49d93f8dc68d09612ba36220dd7f380a2f8cc4657f968dc9a8220d96f07532c912f119fed9e2d25ba0840b9480f82a12954ea30a54bd1c1fe357bea8920154

data/CHANGELOG.md

@@ -1,4 +1,22 @@
-# unreleased
+# 0.3.1
+
+- Loosen railties dependencies after verifying basic Rails 7 support
+
+# 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

data/Gemfile.lock

@@ -1,96 +1,96 @@
 PATH
   remote: .
   specs:
-    test_data (0.2.1)
-      railties (~> 6.0)
+    test_data (0.3.1)
+      railties (>= 6.0, < 8.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (6.1.4)
-      actionview (= 6.1.4)
-      activesupport (= 6.1.4)
-      rack (~> 2.0, >= 2.0.9)
+    actionpack (7.0.2.3)
+      actionview (= 7.0.2.3)
+      activesupport (= 7.0.2.3)
+      rack (~> 2.0, >= 2.2.0)
       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 (7.0.2.3)
+      activesupport (= 7.0.2.3)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activesupport (6.1.4)
+    activesupport (7.0.2.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
-      zeitwerk (~> 2.3)
     ast (2.4.2)
     builder (3.2.4)
     coderay (1.1.3)
-    concurrent-ruby (1.1.9)
+    concurrent-ruby (1.1.10)
     crass (1.0.6)
     erubi (1.10.0)
-    i18n (1.8.10)
+    i18n (1.10.0)
       concurrent-ruby (~> 1.0)
-    loofah (2.10.0)
+    loofah (2.15.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     method_source (1.0.0)
-    mini_portile2 (2.5.3)
-    minitest (5.14.4)
-    nokogiri (1.11.7)
-      mini_portile2 (~> 2.5.0)
+    mini_portile2 (2.8.0)
+    minitest (5.15.0)
+    nokogiri (1.13.3)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
-    parallel (1.20.1)
-    parser (3.0.1.0)
+    parallel (1.22.1)
+    parser (3.1.1.0)
       ast (~> 2.4.1)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    racc (1.5.2)
+    racc (1.6.0)
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
     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 (7.0.2.3)
+      actionpack (= 7.0.2.3)
+      activesupport (= 7.0.2.3)
       method_source
-      rake (>= 0.13)
+      rake (>= 12.2)
       thor (~> 1.0)
-    rainbow (3.0.0)
-    rake (13.0.3)
-    regexp_parser (2.1.1)
+      zeitwerk (~> 2.5)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.2.1)
     rexml (3.2.5)
-    rubocop (1.12.1)
+    rubocop (1.26.0)
       parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      parser (>= 3.1.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.2.0, < 2.0)
+      rubocop-ast (>= 1.16.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.4.1)
-      parser (>= 2.7.1.5)
-    rubocop-performance (1.10.1)
-      rubocop (>= 0.90.0, < 2.0)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
+    rubocop-performance (1.13.3)
+      rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.11.0)
-    standard (1.0.5)
-      rubocop (= 1.12.1)
-      rubocop-performance (= 1.10.1)
-    thor (1.1.0)
+    standard (1.9.0)
+      rubocop (= 1.26.0)
+      rubocop-performance (= 1.13.3)
+    thor (1.2.1)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.0.0)
-    zeitwerk (2.4.2)
+    unicode-display_width (2.1.0)
+    zeitwerk (2.5.4)
 
 PLATFORMS
   ruby
@@ -103,4 +103,4 @@ DEPENDENCIES
   test_data!
 
 BUNDLED WITH
-   2.2.15
+   2.3.10

data/LICENSE.txt

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

data/README.md

@@ -61,6 +61,7 @@ we have reckoned with to this point.
     * [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)
@@ -375,17 +376,30 @@ RSpec.describe "Kitchen sink", type: :request do
 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
+* 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 `test_data` managing transactions and cleanup for you and
-  just want to load the SQL dump, you can call
+* 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).
@@ -417,23 +431,21 @@ to update your test data. Here's how to do it:
     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
 
-    2. Run `rake test_data:drop_database`
-
-    3. Run `rake test_data:load` to recreate the `test_data` database and load
-       the latest SQL dumps into it
+    2. Run `rake test_data:reinitialize` drop and recreate the `test_data`
+       database and load the latest SQL dumps into it
 
-    4. Run any pending migrations with `RAILS_ENV=test_data bin/rake db:migrate`
+    3. Run any pending migrations with `RAILS_ENV=test_data bin/rake db:migrate`
 
-    5. If you need to create any additional data, start up the server
+    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. Export your newly-updated `test_data` database with `rake test_data:dump`
+    5. Export your newly-updated `test_data` database with `rake test_data:dump`
 
-    7. Ensure your tests are passing and then commit the resulting SQL files
+    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 **4 through 7** above
+  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`
@@ -489,15 +501,15 @@ 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! Test failures are most
-likely caused by the combination of your `test_data` database with the data
-persisted by your factories.
+likely caused by the combination of your `test_data` SQL dump with the records
+inserted by your factories.
 
 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 can
-introduce inadvertent coupling between your factories and your `test_data`
-database such that neither can be used independently of the other.
+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.
 
 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
@@ -651,6 +663,18 @@ 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
@@ -762,8 +786,8 @@ 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)
-   to override Rails' default behavior before any of your tests have loaded or
-   started running
+   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.
@@ -1203,8 +1227,104 @@ 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.
 
-The first and most likely source of unnecessary slowness is redundant test
-cleanup—the speed gained from sandwiching every expensive operation between
+#### 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
@@ -1213,32 +1333,6 @@ 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.
 
-A second opportunity for optimization is to group tests that use the same type
-of test data together, either into separate suites or by preventing them from
-being run in random order across said types. For example, suppose you have 10
-tests that call `TestData.uses_test_data` and 10 that call
-`TestData.uses_rails_fixtures`. If a test that calls `TestData.uses_test_data`
-is followed by another that calls `uses_test_data`, the only operation needed by
-the second call will be a rollback to the savepoint taken after the test data
-was loaded. If, however, a `uses_test_data` test is followed by a
-`uses_rails_fixtures` test, then the test data will be truncated and the
-fixtures loaded and new savepoints created (which would then be undone again if
-the _next_ test happened to call `uses_test_data`).
-
-As a result of the above, the marginal runtime cost for each `TestData.uses_*`
-method depends on which kinds of test precedes and follows it. That means your
-tests will run faster overall if the tests that call `TestData.uses_test_data`
-are run as a group separately from your tests that rely on
-`TestData.uses_clean_slate` or `TestData.uses_rails_fixtures`. Separating your
-tests into logical groups 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. If you're using Minitest, 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.
-
 ## Code of Conduct
 
 This project follows Test Double's [code of