with_model 2.3.1 → 2.5.0

data/lib/with_model/null_table.rb

@@ -4,9 +4,11 @@ require "active_record"
 require "with_model/invalid_superclass"
 
 module WithModel
-  # Stands in for a {WithModel::Table} when a model should inherit its
-  # superclass's table instead of getting one of its own, as Rails Single Table
-  # Inheritance requires. Selected by `table(false)`.
+  # Stands in for a {WithModel::Table} when a model should not get a table of its
+  # own: either it inherits its superclass's table, as Rails Single Table
+  # Inheritance requires, or it uses an existing table: one its model block
+  # names with `self.table_name`, or the one Active Record names after the
+  # model. An abstract model needs neither. Selected by `table(false)`.
   #
   # In general, direct use of this class should be avoided. Instead use
   # either the {WithModel high-level API} or {WithModel::Model::DSL low-level API}.
@@ -21,7 +23,9 @@ module WithModel
     end
 
     # Creates nothing, but raises {WithModel::InvalidSuperclass} when the
-    # superclass cannot support single table inheritance.
+    # superclass has a table that cannot support single table inheritance.
+    # Whether a superclass with nothing to inherit is a problem depends on the
+    # model block, so that waits for {#verify}.
     #
     # Errors describe the model's situation rather than the call that produced
     # it. Any expression that evaluates to false selects a NullTable, so there
@@ -34,14 +38,13 @@ module WithModel
     # `StatementInvalid` naming the table if it never appears, so raising here
     # would only forbid working setups.
     #
-    # What is left is {WithModel::InvalidSuperclass}: both errors are permanent
-    # facts about the superclass passed in, not about when it was looked at, so no
-    # amount of waiting makes them work.
+    # What is left is {WithModel::InvalidSuperclass}: a missing inheritance
+    # column, like a missing table to inherit, is a permanent fact about the
+    # superclass passed in, not about when it was looked at, so no amount of
+    # waiting makes it work.
     def create
-      raise_invalid_superclass "#{@superclass} has none to inherit" unless table_name?
-
-      # Nothing more can be checked until there is a table to look at.
-      return unless table_exists?
+      # Nothing can be checked until there is a table to look at.
+      return unless inheritable_table? && table_exists?
       return if inheritance_column?
 
       raise_invalid_superclass "#{@superclass}'s table #{@superclass.table_name.inspect} has no " \
@@ -54,9 +57,33 @@ module WithModel
     def configure(klass)
     end
 
-    # Removes the rows this model wrote, which would otherwise outlive the
-    # constant that names them and make the superclass unloadable
-    # (`ActiveRecord::SubclassNotFound`).
+    # Raises {WithModel::InvalidSuperclass} when the superclass has no table to
+    # inherit (`ActiveRecord::Base`, or an abstract class) and the model's own
+    # table - the one its block named, or else the one Active Record names after
+    # the model - does not exist once its block has run. A model its block made
+    # abstract needs no table, so it always passes.
+    #
+    # Unlike a superclass's missing table, which {#create} lets through, this
+    # table must already exist. A model with nothing to inherit is far more
+    # likely a mistaken attempt at single table inheritance than a deliberate
+    # reference to a table that is yet to be created, and with nothing to point
+    # at, Active Record's own error would leave that mistake unexplained.
+    def verify(klass)
+      return if klass.abstract_class? || inheritable_table? || own_table_exists?(klass)
+
+      raise_invalid_superclass "#{@superclass} has none to inherit and there is no " \
+        "#{klass.table_name.inspect} table. To use an existing table, create it before " \
+        "the model or set `self.table_name` in its model block."
+    end
+
+    # Removes the rows a single table inheritance subclass wrote, which would
+    # otherwise outlive the constant that names them and make the superclass
+    # unloadable (`ActiveRecord::SubclassNotFound`).
+    #
+    # A model that is its own base class names a table that belongs to the
+    # suite, and its rows name no class, so they are left for the suite to clean
+    # up like the rest of that table - its table need not have an inheritance
+    # column to delete by, either.
     #
     # `unscoped` is required because a `default_scope` on the superclass would
     # otherwise hide rows from cleanup; the inheritance-column condition is
@@ -66,7 +93,7 @@ module WithModel
     # A table that does not exist holds no rows to remove, and failing here
     # would fail an example whose body had already passed.
     def teardown(klass)
-      return unless klass.table_exists?
+      return if klass.base_class? || !klass.table_exists?
 
       klass.unscoped.where(klass.inheritance_column => klass.sti_name).each(&:destroy!)
     end
@@ -79,10 +106,13 @@ module WithModel
 
     def inheritance_column = @superclass.inheritance_column
 
-    # `ActiveRecord::Base` and abstract classes alike have no `table_name`, so
-    # this is what "nothing to inherit" actually looks like - `abstract_class?`
-    # is false for `ActiveRecord::Base` and so does not describe both.
-    def table_name? = @superclass.table_name.present?
+    # `ActiveRecord::Base` has no `table_name`, and an abstract class has none to
+    # pass on through single table inheritance even when it has one: Active
+    # Record makes each of its subclasses a base class of its own. Neither test
+    # covers both, since `abstract_class?` is false for `ActiveRecord::Base`.
+    def inheritable_table? = !@superclass.abstract_class? && @superclass.table_name.present?
+
+    def own_table_exists?(klass) = klass.connection.data_source_exists?(klass.table_name)
 
     def table_exists? = @superclass.table_exists?
 

data/lib/with_model/rspec.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "with_model"
+
+WithModel.runner = :rspec
+
+RSpec.configure do |config|
+  config.extend WithModel
+end

data/lib/with_model/table.rb

@@ -30,6 +30,12 @@ module WithModel
       klass.table_name = @name
     end
 
+    # Accepts any model block: the table is the model's own. Present so that
+    # {WithModel::NullTable} - which checks the model once its block has run -
+    # can stand in here.
+    def verify(_klass)
+    end
+
     # Removes everything this table holds by dropping it. The model is not
     # needed, but is accepted so that {WithModel::NullTable} - which does need
     # it - can stand in here.
@@ -38,19 +44,13 @@ module WithModel
     end
 
     def destroy
-      connection.drop_table(@name)
+      connection.drop_table(@name) if exists?
     end
 
     private
 
     attr_reader :connection
 
-    def exists?
-      if connection.respond_to?(:data_source_exists?)
-        connection.data_source_exists?(@name)
-      else
-        connection.table_exists?(@name)
-      end
-    end
+    def exists? = connection.data_source_exists?(@name)
   end
 end

data/lib/with_model/test_unit.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "test/unit"
+require "with_model"
+
+WithModel.runner = :test_unit
+Test::Unit::TestCase.extend WithModel

data/lib/with_model/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WithModel
-  VERSION = "2.3.1"
+  VERSION = "2.5.0"
 end

data/lib/with_model.rb

@@ -113,8 +113,13 @@ module WithModel
       class_eval do
         include MiniTestLifeCycle.call(object)
       end
+    when :test_unit
+      # These options place creation before and destruction after user callbacks,
+      # preserving declaration and reverse order across inheritance.
+      setup(before: :append) { object.create }
+      teardown(after: :prepend) { object.destroy }
     else
-      raise ArgumentError, "Unsupported test runner set, expected :rspec or :minitest"
+      raise ArgumentError, "Unsupported test runner set, expected :rspec, :minitest, or :test_unit"
     end
   end
 end

data/spec/descendants_tracking_spec.rb

@@ -30,7 +30,6 @@ describe "Descendants tracking" do
 
   context "with ActiveSupport::DescendantsTracker (cache_classes: true)" do
     before do
-      expect(ActiveSupport::DescendantsTracker.clear_disabled).to be_falsey
       expect { ActiveSupport::DescendantsTracker.clear([]) }.not_to raise_exception
     end
 
@@ -40,10 +39,29 @@ describe "Descendants tracking" do
   context "without ActiveSupport::DescendantsTracker (cache_classes: false)" do
     before do
       ActiveSupport::DescendantsTracker.disable_clear!
-      expect(ActiveSupport::DescendantsTracker.clear_disabled).to be_truthy
       expect { ActiveSupport::DescendantsTracker.clear([]) }.to raise_exception(RuntimeError)
     end
 
     include_examples "clearing descendants between test runs"
   end
+
+  it "keeps filtering ahead of later class method extensions" do
+    raw_subclasses = Class.instance_method(:subclasses).super_method
+    raw_descendants = Class.instance_method(:descendants).super_method
+    override = Module.new do
+      define_method(:subclasses) { raw_subclasses.bind_call(self) }
+      define_method(:descendants) { raw_descendants.bind_call(self) }
+    end
+    destroyed_model = stub_const("DestroyedModel", Class.new(ActiveRecord::Base))
+    WithModel::DescendantsTracker.clear([destroyed_model])
+
+    ActiveRecord::Base.extend override
+
+    expect(ActiveRecord::Base.descendants).not_to include(destroyed_model)
+  ensure
+    override&.module_eval do
+      remove_method :subclasses
+      remove_method :descendants
+    end
+  end
 end

data/spec/readme_spec.rb

@@ -145,6 +145,26 @@ describe "with_model supports Single Table Inheritance" do
   end
 end
 
+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
+
 describe "with_model supports foreign keys" do
   with_model :Author do
     table

data/spec/runner_entrypoints_spec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+require "tmpdir"
+
+RSpec.describe "runner integration entrypoints" do
+  def run_ruby(source, load_paths: ["lib"])
+    Open3.capture3(
+      RbConfig.ruby,
+      *load_paths.map { |path| "-I#{path}" },
+      "-e",
+      source
+    )
+  end
+
+  def expect_native_runner_to_pass(source, load_paths: ["lib"])
+    stdout, stderr, status = run_ruby(source, load_paths:)
+
+    expect(status).to be_success, <<~MESSAGE
+      subprocess failed with status #{status.exitstatus}
+      stdout:
+      #{stdout}
+      stderr:
+      #{stderr}
+    MESSAGE
+  end
+
+  it "configures RSpec and extends new example groups" do
+    expect_native_runner_to_pass(<<~'RUBY')
+      require "with_model/rspec"
+      abort "runner: #{WithModel.runner.inspect}" unless WithModel.runner == :rspec
+
+      RSpec.describe "entrypoint" do
+        it "installs the DSL" do
+          expect(self.class).to respond_to(:with_model)
+        end
+      end
+
+      exit RSpec::Core::Runner.run([])
+    RUBY
+  end
+
+  it "configures Minitest and extends new test subclasses" do
+    expect_native_runner_to_pass(<<~'RUBY')
+      require "with_model/minitest"
+      abort "runner: #{WithModel.runner.inspect}" unless WithModel.runner == :minitest
+
+      # Assert that minitest/autorun is not loaded
+      autorun_loaded = $LOADED_FEATURES.any? { |f| f.end_with?("/minitest/autorun.rb") }
+      abort "autorun should not be loaded; loaded features: #{$LOADED_FEATURES.inspect}" if autorun_loaded
+
+      class MinitestEntrypointTest < Minitest::Test
+        def test_installs_the_dsl
+          assert_respond_to self.class, :with_model
+        end
+      end
+
+      exit(Minitest.run ? 0 : 1)
+    RUBY
+  end
+
+  it "configures Test::Unit and extends new test subclasses" do
+    expect_native_runner_to_pass(<<~'RUBY')
+      require "with_model/test_unit"
+      abort "runner: #{WithModel.runner.inspect}" unless WithModel.runner == :test_unit
+
+      class TestUnitEntrypointTest < Test::Unit::TestCase
+        def test_installs_the_dsl
+          assert_respond_to self.class, :with_model
+        end
+      end
+    RUBY
+  end
+
+  it "propagates Test::Unit's LoadError when the framework is unavailable" do
+    Dir.mktmpdir do |directory|
+      Dir.mkdir(File.join(directory, "test"))
+      File.write(
+        File.join(directory, "test/unit.rb"),
+        'raise LoadError, "distinctive test/unit LoadError"'
+      )
+
+      expect_native_runner_to_pass(<<~'RUBY', load_paths: [directory, "lib"])
+        begin
+          require "with_model/test_unit"
+        rescue LoadError => error
+          abort "unexpected LoadError: #{error.message.inspect}" unless
+            error.message == "distinctive test/unit LoadError"
+        else
+          abort "expected a LoadError"
+        end
+      RUBY
+    end
+  end
+
+  it "retains manual Test::Unit setup with plain with_model" do
+    expect_native_runner_to_pass(<<~'RUBY')
+      require "test/unit"
+      require "with_model"
+
+      WithModel.runner = :test_unit
+      Test::Unit::TestCase.extend WithModel
+      abort "runner: #{WithModel.runner.inspect}" unless WithModel.runner == :test_unit
+
+      class PlainWithModelTestUnitTest < Test::Unit::TestCase
+        def test_installs_the_dsl
+          assert_respond_to self.class, :with_model
+        end
+      end
+    RUBY
+  end
+
+  it "retains manual RSpec setup with plain with_model" do
+    expect_native_runner_to_pass(<<~'RUBY')
+      require "rspec"
+      require "with_model"
+
+      WithModel.runner = :rspec
+      RSpec.configure do |config|
+        config.extend WithModel
+      end
+      abort "runner: #{WithModel.runner.inspect}" unless WithModel.runner == :rspec
+
+      RSpec.describe "entrypoint" do
+        it "installs the DSL" do
+          expect(self.class).to respond_to(:with_model)
+        end
+      end
+
+      exit RSpec::Core::Runner.run([])
+    RUBY
+  end
+
+  it "retains manual Minitest setup with plain with_model" do
+    expect_native_runner_to_pass(<<~'RUBY')
+      require "minitest"
+      require "with_model"
+
+      WithModel.runner = :minitest
+      Minitest::Test.extend WithModel
+      abort "runner: #{WithModel.runner.inspect}" unless WithModel.runner == :minitest
+
+      class PlainWithModelMinitestTest < Minitest::Test
+        def test_installs_the_dsl
+          assert_respond_to self.class, :with_model
+        end
+      end
+
+      exit(Minitest.run ? 0 : 1)
+    RUBY
+  end
+end

data/spec/table_false_spec.rb

@@ -21,10 +21,6 @@ RSpec.describe "table(false)" do
     classes = @stubbed_active_record_classes
     next unless classes
 
-    ActiveSupport::DescendantsTracker.clear(classes) \
-      unless ActiveSupport::DescendantsTracker.clear_disabled
-    ActiveSupport::Dependencies::Reference.clear! \
-      if defined?(ActiveSupport::Dependencies::Reference)
     WithModel::DescendantsTracker.clear(classes)
   end
 
@@ -437,6 +433,135 @@ RSpec.describe "table(false)" do
     end
   end
 
+  # Not single table inheritance at all: the model is its own base class and
+  # names an existing table, such as a legacy table or one several models share.
+  describe "with a model that sets its own table_name" do
+    with_table :legendary_creatures do |t|
+      t.string :name
+    end
+
+    # Declared between the two so that it runs after the model is torn down but
+    # before the table is dropped.
+    after do
+      expect(ActiveRecord::Base.connection.select_value("SELECT COUNT(*) FROM legendary_creatures"))
+        .to eq @rows_written.to_i
+    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")
+      @rows_written = 1
+
+      expect(Phoenix.table_name).to eq "legendary_creatures"
+      expect(Phoenix.count).to eq 1
+    end
+
+    it "creates no table of its own" do
+      expect(ActiveRecord::Base.connection.tables.grep(/with_model_phoenix/)).to be_empty
+    end
+
+    it "is its own base class" do
+      expect(Phoenix.base_class).to eq Phoenix
+    end
+
+    # The table belongs to the suite, which is left to clean it up - with
+    # transactional tests, or however it cleans up its other tables. Deleting by
+    # type would fail outright here, since there is no type column.
+    it "leaves its rows alone when torn down" do
+      Phoenix.create!(name: "Fawkes")
+      Phoenix.create!(name: "Buckbeak")
+      @rows_written = 2
+    end
+
+    # An abstract model needs no table, so `table(false)` suits it too.
+    context "with an abstract superclass that has no table" do
+      with_model :ApplicationRecord do
+        table(false)
+        model do
+          self.abstract_class = true
+        end
+      end
+
+      with_model :Griffin, superclass: :ApplicationRecord do
+        table(false)
+        model do
+          self.table_name = "legendary_creatures"
+        end
+      end
+
+      it "uses the table it names" do
+        Griffin.create!(name: "Buckbeak")
+        @rows_written = 1
+
+        expect(Griffin.table_name).to eq "legendary_creatures"
+        expect(Griffin.count).to eq 1
+      end
+
+      it "leaves the abstract superclass without a table" do
+        expect(ApplicationRecord.table_name).to be_nil
+      end
+    end
+
+    # Active Record never applies single table inheritance below an abstract
+    # class, so its table needs no inheritance column.
+    context "with an abstract superclass that has a table" do
+      with_model :LegendaryCreature do
+        table
+        model do
+          self.abstract_class = true
+        end
+      end
+
+      with_model :Sphinx, superclass: :LegendaryCreature do
+        table(false)
+        model do
+          self.table_name = "legendary_creatures"
+        end
+      end
+
+      it "uses the table it names" do
+        Sphinx.create!(name: "Phix")
+        @rows_written = 1
+
+        expect(Sphinx.table_name).to eq "legendary_creatures"
+        expect(Sphinx.count).to eq 1
+      end
+
+      it "is its own base class" do
+        expect(Sphinx.base_class).to eq Sphinx
+      end
+    end
+  end
+
+  # Active Record's naming convention picks the table, so the model block need
+  # not name it.
+  describe "with a model named after an existing table" do
+    with_table :dragons do |t|
+      t.string :name
+    end
+
+    with_model :Dragon do
+      table(false)
+    end
+
+    it "uses that table" do
+      Dragon.create!(name: "Norbert")
+
+      expect(Dragon.table_name).to eq "dragons"
+      expect(Dragon.count).to eq 1
+    end
+
+    it "creates no table of its own" do
+      expect(ActiveRecord::Base.connection.tables.grep(/with_model_dragon/)).to be_empty
+    end
+  end
+
   describe "invalid configurations" do
     # Creates immediately the same tableless subclass normally generated by:
     #
@@ -465,6 +590,46 @@ RSpec.describe "table(false)" do
         .to raise_error(WithModel::InvalidSuperclass, /ActiveRecord::Base has none to inherit/)
     end
 
+    it "names the table it looked for" do
+      expect { create_tableless_subclass(superclass: ActiveRecord::Base) }
+        .to raise_error(WithModel::InvalidSuperclass, /there is no "tableless_subclasses" table/)
+    end
+
+    it "suggests creating that table first or naming another" do
+      expect { create_tableless_subclass(superclass: ActiveRecord::Base) }
+        .to raise_error(
+          WithModel::InvalidSuperclass,
+          /create it before the model or set `self.table_name` in its model block/
+        )
+    end
+
+    # Builds the model by hand so that, should the check let it through, the
+    # example can still destroy it rather than leak its constant.
+    it "looks for the table the model block names" do
+      subclass = WithModel::Model.new(:TablelessSubclass, superclass: ActiveRecord::Base)
+      WithModel::Model::DSL.new(subclass).instance_eval do
+        table(false)
+        model { self.table_name = "missing_furniture" }
+      end
+
+      begin
+        expect { subclass.create }
+          .to raise_error(WithModel::InvalidSuperclass, /there is no "missing_furniture" table/)
+      ensure
+        subclass.destroy if Object.const_defined?(:TablelessSubclass, false)
+      end
+    end
+
+    # The check needs the model block to have run, so the constant already
+    # exists when it fails. A test runner tears down after a failed setup, but
+    # nothing else does, and a leftover constant would leak into later tests.
+    it "leaves no constant behind" do
+      expect { create_tableless_subclass(superclass: ActiveRecord::Base) }
+        .to raise_error(WithModel::InvalidSuperclass)
+
+      expect(Object.const_defined?(:TablelessSubclass, false)).to be false
+    end
+
     context "with an abstract superclass" do
       with_model :TablelessSuperclass do
         table

data/spec/table_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe WithModel::Table do
+  let(:connection_owner) do
+    klass = Class.new(ActiveRecord::Base)
+    stub_const("TableSpecConnection", klass)
+    klass.abstract_class = true
+    klass.establish_connection(adapter: "sqlite3", database: ":memory:")
+    klass
+  end
+  let(:connection) { connection_owner.connection }
+  let(:table) { described_class.new(:temporary_records, connection:) }
+
+  after { connection_owner.connection_pool.disconnect! }
+
+  describe "#destroy" do
+    it "does not raise after its connection reconnects before teardown" do
+      table.create
+
+      connection.disconnect!
+      connection.reconnect!
+
+      expect(connection.data_source_exists?(:temporary_records)).to be false
+      expect { table.destroy }.not_to raise_error
+    end
+
+    it "drops an existing table" do
+      table.create
+
+      table.destroy
+
+      expect(connection.data_source_exists?(:temporary_records)).to be false
+    end
+  end
+end