with_model 2.3.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e161c7fe750e7eb3b78e178a14b2e23ef88b0fa4612abfb22e3920be9eda614e
-  data.tar.gz: fb6d9310626f6a006463782d179406e1a2af10b6672899fb57c2bf26f6df61a0
+  metadata.gz: 82365b7ef365626c49c238c05258d85603f6d9cf18c080c5ef39329c1ecf3346
+  data.tar.gz: d1cf7a5a2f060ab68b1daf20a0495de5a09b706b272387810c3c4acce6e42470
 SHA512:
-  metadata.gz: 7d80585ba48b4b87593f9b7f18b8c4674391e51458b5e273ee121e4962bf4b479000a178a83db14cfa38a1eb185c8f09ac01d727ce6f79afe39ce5e45686ca70
-  data.tar.gz: 3e241e4d17f7b5d889e665e5cb17e5d66de1ca7fdd3b3cbd4e73615421561f735aa3d3f40176b27c1be32cfc9e1db7059d642662ad35fc786fc45620b8a8146f
+  metadata.gz: 6c4d55dda6fe90872b8a31799207acfe4a910734f20e26cd870103d4ddee2dac6f7f756474f2982e944337ec06502b507622a95c89d400df64aae763554b04c7
+  data.tar.gz: f3fc56af09b5da30a0bde842ff0cc66d448089a638bce6203485ce9f48fe35014b21c05cb1d1f06fc179f49077c58f365837e2f5ab15534d0781a0f4f297c4d8

data/.github/workflows/ci.yml

@@ -29,8 +29,6 @@ jobs:
       matrix:
         ruby-version: ["3.3", "3.4", "4.0"]
         active-record:
-          - label: AR 7.2
-            env: ACTIVE_RECORD_VERSION=~> 7.2.0
           - label: AR 8.0
             env: ACTIVE_RECORD_VERSION=~> 8.0.0
           - label: AR 8.1
@@ -52,11 +50,6 @@ jobs:
               label: AR 8-0-stable
               env: ACTIVE_RECORD_BRANCH=8-0-stable
             allow-failure: true
-          - ruby-version: "4.0"
-            active-record:
-              label: AR 7-2-stable
-              env: ACTIVE_RECORD_BRANCH=7-2-stable
-            allow-failure: true
           # A canary for the next Ruby, which cannot fail the build.
           - ruby-version: ruby-head
             active-record:
@@ -78,11 +71,6 @@ jobs:
           ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
           cache-version: ${{ matrix.active-record.env }}
-      # Gemfile.lock is not checked in, so this resolves the newest gems that
-      # satisfy the Gemfile on each run rather than a recorded set. `--all` is
-      # what Bundler 4, shipped with Ruby 4.0, wants for that.
-      - name: Update bundle
-        run: bundle update --all
       # Not bin/rake: bin/ holds generated binstubs and is not checked in, and
       # whether bundling writes them there varies by Bundler version - Bundler 4
       # does not, which left Ruby 4.0 with no binstub to run.

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ### Unreleased
 
+### 2.5.0
+
+- Allow `table(false)` for an abstract model, and for a model whose superclass
+  is `ActiveRecord::Base` or abstract when the model has an existing table: the
+  one its model block names with `self.table_name`, or else the one Active
+  Record names after the model. Its rows are left for the suite to clean up.
+
+### 2.4.0
+
+- Add Test::Unit support, including lifecycle integration for dynamic models and
+  tables.
+- Add `with_model/rspec`, `with_model/minitest`, and `with_model/test_unit`
+  convenience entrypoints.
+- Add runner integration guides for RSpec, Minitest, and Test::Unit.
+- Skip temporary-table teardown when the table has already disappeared.
+- Require Active Record 8.0 or later.
+
 ### 2.3.1
 
 - Honor Active Record destruction callbacks and dependent associations when

data/CONTRIBUTING.md

@@ -24,12 +24,22 @@ avoid anything that only works on the newest of either.
 
 ## Running the tests
 
-The suite runs against both supported test harnesses, so `with_model` has to work
-under each:
+The suite runs against all three supported test harnesses, so `with_model` has
+to work under each:
 
 - `spec/` covers behavior under RSpec.
-- `test/` covers the minitest life cycle — the setup and teardown hooks, and
+- `test/` covers the Minitest life cycle — the setup and teardown hooks, and
   their ordering — rather than repeating the specs.
+- `test_unit/` covers Test::Unit integration in a dedicated process, including
+  native fixture callback ordering.
+
+Run one harness with its scoped Rake task:
+
+```sh
+bundle exec rake spec
+bundle exec rake test
+bundle exec rake test_unit
+```
 
 Run everything, including the linter, with:
 
@@ -37,6 +47,13 @@ Run everything, including the linter, with:
 bundle exec rake
 ```
 
+Validate the README and runner guides with RDoc before submitting documentation
+changes:
+
+```sh
+rm -rf tmp/rdoc && bundle exec rdoc --markup markdown --op tmp/rdoc README.md docs/rspec.md docs/minitest.md docs/test-unit.md lib/**/*.rb
+```
+
 `bin/` holds generated binstubs and is not checked in. Whether bundling writes
 them for you depends on your Bundler version, so create them once if you would
 rather type `bin/rake`:
@@ -75,9 +92,27 @@ bundle exec standardrb --fix
 
 ## Changes and releases
 
-Please add a line to `CHANGELOG.md` under `### Unreleased` describing your change
-from the point of view of someone using the gem. Leave `lib/with_model/version.rb`
-alone: version bumps and releases are cut separately by a maintainer, so a bump
-in a pull request only creates a conflict.
+Please add an entry to `CHANGELOG.md` under `### Unreleased` for each change
+someone using the gem would notice. Leave `lib/with_model/version.rb` alone:
+version bumps and releases are cut separately by a maintainer, so a bump in a
+pull request only creates a conflict.
+
+### Changelog format
+
+- Each release has a `### X.Y.Z` heading, newest first, with unreleased changes
+  under `### Unreleased` at the top. Leave a blank line after each heading.
+- Write one bullet per change, from the point of view of someone using the gem:
+  what they can now do or what behaves differently, not how the code changed.
+- Start with a verb in the imperative mood (Add, Allow, Fix, Deprecate, Remove,
+  Require), and write a full sentence ending in a period.
+- Put code, such as method names, options, and constants, in backticks.
+- Wrap lines at 80 columns, indenting continuation lines by two spaces.
+- List dependency changes last, Active Record before Ruby, with added support
+  before a raised minimum: "Add support for Ruby 4.0." then "Require Ruby 3.3
+  or later."
+- Don't cite issue or pull request numbers. The pull request links the issue.
+- Credit contributors from outside the maintainers by name, in parentheses at
+  the end of the entry, as in "Create table in same database as `superclass`
+  (John Doe)."
 
 Last, but not least, have fun.

data/Gemfile

@@ -24,3 +24,4 @@ gem "rspec"
 gem "ruby-lsp"
 gem "sqlite3"
 gem "standard"
+gem "test-unit"

data/README.md

@@ -14,32 +14,63 @@
 
 Install as usual: `gem install with_model` or add `gem 'with_model'` to your Gemfile. See [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) for supported (tested) Ruby versions.
 
+## Test runner setup
+
+Choose the entrypoint for the test runner that owns the declarations. Each
+performs complete global setup for one runner; see its guide for lifecycle and
+manual-setup details.
+
 ### RSpec
 
-Extend `WithModel` into RSpec:
+```ruby
+require "with_model/rspec"
+```
+
+See the [RSpec guide](docs/rspec.md).
+
+### Minitest
 
 ```ruby
-require "with_model"
+require "with_model/minitest"
+```
 
-RSpec.configure do |config|
-  config.extend WithModel
-end
+See the [Minitest guide](docs/minitest.md).
+
+### Test::Unit
+
+```ruby
+require "with_model/test_unit"
 ```
 
-### minitest/spec
+See the [Test::Unit guide](docs/test-unit.md).
 
-Extend `WithModel` into minitest/spec and set the test runner explicitly:
+### Advanced and mixed-runner setup
+
+Plain `require "with_model"` remains framework-neutral. For manual setup,
+select a runner and extend its test context directly:
 
 ```ruby
+require "minitest"
 require "with_model"
 
 WithModel.runner = :minitest
+Minitest::Test.extend WithModel
+```
+
+RSpec uses `RSpec.configure { |config| config.extend WithModel }`; Test::Unit
+uses `Test::Unit::TestCase.extend WithModel`. A declaration can override the
+global runner when needed:
 
-class Minitest::Spec
-  extend WithModel
+```ruby
+with_model :Post, runner: :test_unit do
+  table
 end
 ```
 
+Loading multiple convenience entrypoints in one process is unsupported because
+the last one changes the global runner. For mixed runners, use plain
+`with_model`, direct extension, and explicit `runner:` options.
+
 ## Usage
 
 After setting up as above, call `with_model` and inside its block pass it a `table` block and a `model` block.
@@ -206,8 +237,9 @@ end
 A `superclass:` that cannot be used raises `WithModel::InvalidSuperclass`: one
 that is not an Active Record class, one with no table of its own
 (`ActiveRecord::Base`, or an abstract class such as a Rails app's
-`ApplicationRecord`), or one whose table has no inheritance column to tell a
-subclass's rows apart. A name that resolves to nothing raises
+`ApplicationRecord`) when the model has no existing table of its own either (see
+[Existing tables](#existing-tables)), or a concrete one whose table has no
+inheritance column to tell a subclass's rows apart. A name that resolves to nothing raises
 `WithModel::MissingSuperclass`, a kind of `InvalidSuperclass`, quoting the
 constant Ruby could not find — for a namespaced name, that is the segment which
 is actually missing. Both are `ArgumentError`s.
@@ -218,6 +250,64 @@ enough on its own. Rows the model wrote are deleted when it goes away, since the
 name a class that is about to stop existing and would make the superclass
 unloadable.
 
+### Existing tables
+
+`table(false)` also suits a model that maps to a table the suite already has,
+such as a legacy table or one that several models share. Set `self.table_name`
+in the model block, or leave it out to use the table Active Record names after
+the model (`phoenixes` for `Phoenix`):
+
+```ruby
+describe "with_model supports existing tables" do
+  with_table :legendary_creatures do |t|
+    t.string "name"
+  end
+
+  with_model :Phoenix do
+    table(false)
+
+    model do
+      self.table_name = "legendary_creatures"
+    end
+  end
+
+  it "uses the table it names" do
+    Phoenix.create!(name: "Fawkes")
+
+    expect(Phoenix.table_name).to eq "legendary_creatures"
+  end
+end
+```
+
+The table must exist before the model is set up, so declare `with_table` (or
+whatever creates it) first. It belongs to the suite, not the model, so its rows
+are left in place when the model goes away. Clean them up as you would the rest of that table, with
+transactional tests or otherwise.
+
+The superclass can be abstract, as a Rails app's `ApplicationRecord` is. An
+abstract model needs no table, so declare it with `table(false)` as well:
+
+```ruby
+with_model :LegendaryCreature do
+  table(false)
+
+  model do
+    self.abstract_class = true
+  end
+end
+
+with_model :Phoenix, superclass: :LegendaryCreature do
+  table(false)
+
+  model do
+    self.table_name = "legendary_creatures"
+  end
+end
+```
+
+Active Record never applies single table inheritance below an abstract class, so
+an abstract superclass's table, if it has one, needs no inheritance column.
+
 ## Foreign keys
 
 `foreign_key: true` asks Active Record to infer the table a foreign key points
@@ -252,7 +342,13 @@ the order they are declared, and destroyed in the reverse order.
 
 ## Requirements
 
-See the [gemspec metadata](https://rubygems.org/gems/with_model) for dependency requirements. RSpec and minitest are indirect dependencies, and `with_model` should support any maintained version of both.
+See the [gemspec metadata](https://rubygems.org/gems/with_model) for Ruby and
+Active Record requirements. RSpec, Minitest, and Test::Unit are optional
+consumer framework dependencies; install the framework used by its selected
+entrypoint. Requiring a selected entrypoint without its framework installed
+raises the framework's ordinary `LoadError`.
+
+`scope:` is RSpec-only and is silently ignored by Minitest and Test::Unit.
 
 ## Thread-safety
 

data/Rakefile

@@ -8,7 +8,13 @@ RSpec::Core::RakeTask.new
 require "minitest/test_task"
 Minitest::TestTask.create
 
+require "rake/testtask"
+Rake::TestTask.new(:test_unit) do |task|
+  task.libs << "lib" << "test_unit" << "test"
+  task.pattern = "test_unit/**/*_test.rb"
+end
+
 # standard rake task
 require "standard/rake"
 
-task default: %i[spec test standard]
+task default: %i[spec test test_unit standard]

data/docs/minitest.md

@@ -0,0 +1,45 @@
+# Minitest integration
+
+Load the Minitest entrypoint before defining tests:
+
+```ruby
+require "with_model/minitest"
+```
+
+This requires `minitest`, then `with_model`, selects the
+`:minitest` runner, and extends `Minitest::Test`. Its class-level DSL is
+inherited by `Minitest::Test` subclasses, including `Minitest::Spec` and
+`ActiveSupport::TestCase`. The entrypoint does not require or start Minitest's
+autorun — your process or test framework owns Minitest startup.
+
+## Lifecycle
+
+The Minitest runner creates declared models and tables in `before_setup` and
+destroys them in `after_teardown`. This makes them available to ordinary setup
+methods and keeps them available through teardown. `scope:` is silently ignored
+by Minitest because it is an RSpec-only option.
+
+## Manual setup
+
+If another process or tool owns Minitest configuration, configure manually:
+
+```ruby
+require "minitest"
+require "with_model"
+
+WithModel.runner = :minitest
+Minitest::Test.extend WithModel
+```
+
+Minitest is an optional consumer dependency. Requiring `with_model/minitest`
+without Minitest installed raises Minitest's ordinary `LoadError`.
+
+## Mixed runners
+
+Do not load multiple convenience entrypoints in one process: each changes the
+global runner, and the last one wins. For mixed runners, load plain
+`with_model`, extend each framework boundary directly, and select a runner per
+declaration with `runner:`.
+
+See the [general DSL reference](../README.md#usage) for declaring models and
+tables.

data/docs/rspec.md

@@ -0,0 +1,43 @@
+# RSpec integration
+
+Load the RSpec entrypoint before defining example groups:
+
+```ruby
+require "with_model/rspec"
+```
+
+The entrypoint requires `rspec/core` and `with_model`, selects the `:rspec`
+runner, and extends RSpec example groups through `RSpec.configure`. It does not
+start RSpec; the RSpec command-line runner remains in control.
+
+## Lifecycle
+
+`with_model` and `with_table` register RSpec `before` and `after` hooks. Models
+and tables are available to examples after setup and are removed after cleanup.
+Use `scope:` when RSpec hook scope is needed, including `scope: :all` for a
+model needed by `before(:all)`. `scope:` is an RSpec-only option.
+
+## Manual setup
+
+For runner-owned setup, require the framework and `with_model` separately:
+
+```ruby
+require "rspec/core"
+require "with_model"
+
+WithModel.runner = :rspec
+RSpec.configure { |config| config.extend WithModel }
+```
+
+RSpec is an optional consumer dependency. Requiring `with_model/rspec` without
+RSpec installed raises RSpec's ordinary `LoadError`.
+
+## Mixed runners
+
+Do not load multiple convenience entrypoints in one process: each changes the
+global runner, and the last one wins. For mixed runners, load plain
+`with_model`, extend each framework boundary directly, and select a runner per
+declaration with `runner:`.
+
+See the [general DSL reference](../README.md#usage) for declaring models and
+tables.

data/docs/test-unit.md

@@ -0,0 +1,73 @@
+# Test::Unit integration
+
+Load the Test::Unit entrypoint before defining tests:
+
+```ruby
+require "with_model/test_unit"
+```
+
+The entrypoint requires `test/unit`, then `with_model`, selects the
+`:test_unit` runner, and extends `Test::Unit::TestCase`. Test::Unit retains
+ownership of autorun and fixture execution.
+
+## Lifecycle
+
+`with_model` and `with_table` register Test::Unit fixture callbacks with exact
+placement: setup uses `before: :append`, while teardown uses `after: :prepend`.
+Declared models and tables therefore create in declaration order before user or
+inherited setup methods and callbacks. They destroy in reverse order after user
+or inherited teardown methods and callbacks.
+
+Test::Unit runs teardown when setup raises. `WithModel::Model#destroy`
+defensively handles creation that never assigned a model. `Table#destroy` checks
+whether its table exists before dropping it, so teardown does not raise solely
+because a reconnect replaced an in-memory database or the table otherwise
+already disappeared. It does not rescue other database, connection, or drop
+errors; those still propagate. This conditional drop check does not promise
+generic partial-creation recovery for bare `with_table`. `scope:` is silently
+ignored by Test::Unit because it is an RSpec-only option.
+
+## Errata and concerns
+
+Establish the Active Record connection before `with_model`'s setup callback
+creates tables and models. An ordinary `def setup` runs too late. Connect in
+your test helper before test classes load, or register a connection callback
+with `setup(before: :prepend)`.
+
+```ruby
+class PostTest < Test::Unit::TestCase
+  setup(before: :prepend) do
+    ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+  end
+
+  with_model :Post do
+    table
+  end
+end
+```
+
+## Manual setup
+
+For runner-owned setup, require Test::Unit and `with_model` separately:
+
+```ruby
+require "test/unit"
+require "with_model"
+
+WithModel.runner = :test_unit
+Test::Unit::TestCase.extend WithModel
+```
+
+Test::Unit is an optional consumer dependency. Requiring
+`with_model/test_unit` without Test::Unit installed raises Test::Unit's ordinary
+`LoadError`.
+
+## Mixed runners
+
+Do not load multiple convenience entrypoints in one process: each changes the
+global runner, and the last one wins. For mixed runners, load plain
+`with_model`, extend each framework boundary directly, and select a runner per
+declaration with `runner:`.
+
+See the [general DSL reference](../README.md#usage) for declaring models and
+tables.

data/lib/with_model/descendants_tracker.rb

@@ -74,14 +74,6 @@ module WithModel
   end
 end
 
-class ActiveRecord::Base
-  extend WithModel::DescendantsTracker::DestroyedClassesFiltering
-end
-
-module ActiveSupport
-  module DescendantsTracker
-    class << self
-      attr_reader :clear_disabled
-    end
-  end
-end
+ActiveRecord::Base.singleton_class.prepend(
+  WithModel::DescendantsTracker::DestroyedClassesFiltering
+)

data/lib/with_model/minitest.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "with_model"
+
+WithModel.runner = :minitest
+Minitest::Test.extend WithModel

data/lib/with_model/model/dsl.rb

@@ -13,7 +13,9 @@ module WithModel
       #
       # Pass `false` instead of options to create no table at all, so that the
       # model inherits its superclass's table as Rails Single Table Inheritance
-      # requires. `table(false)` takes no block.
+      # requires, or uses an existing table: the one its model block names with
+      # `self.table_name`, or else the one Active Record names after the model.
+      # An abstract model needs no table at all. `table(false)` takes no block.
       #
       # @see https://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-create_table
       def table(options = {}, &block)

data/lib/with_model/model.rb

@@ -73,11 +73,7 @@ module WithModel
       # Before `unstub_const`: a teardown that identifies this model's own rows
       # can only do so while the class still has its name.
       table.teardown(@model)
-      stubber.unstub_const
-      cleanup_descendants_tracking
-      reset_dependencies_cache
-      WithModel::DescendantsTracker.clear([@model])
-      @model = nil
+      discard_model
     end
 
     private
@@ -129,18 +125,24 @@ module WithModel
     def setup_model
       table.configure(@model)
       @model.class_eval(&@model_block) if @model_block
+      verify_model
       @model.reset_column_information
     end
 
-    def cleanup_descendants_tracking
-      ActiveSupport::DescendantsTracker.clear([@model]) \
-        unless ActiveSupport::DescendantsTracker.clear_disabled
+    # A model rejected here was never usable, so it is discarded at once rather
+    # than left for teardown: there are no rows to clean up, and a caller that
+    # does not tear down would otherwise be left with its constant.
+    def verify_model
+      table.verify(@model)
+    rescue InvalidSuperclass
+      discard_model
+      raise
     end
 
-    def reset_dependencies_cache
-      return unless defined?(ActiveSupport::Dependencies::Reference)
-
-      ActiveSupport::Dependencies::Reference.clear!
+    def discard_model
+      stubber.unstub_const
+      WithModel::DescendantsTracker.clear([@model])
+      @model = nil
     end
 
     def stubber