with_model 2.2.0 → 2.3.0

data/lib/with_model/model.rb

@@ -7,6 +7,9 @@ require "English"
 require "with_model/constant_stubber"
 require "with_model/descendants_tracker"
 require "with_model/methods"
+require "with_model/invalid_superclass"
+require "with_model/missing_superclass"
+require "with_model/null_table"
 require "with_model/table"
 
 module WithModel
@@ -16,17 +19,43 @@ module WithModel
     attr_writer :model_block, :table_block, :table_options
 
     # @param [Symbol] name The constant name to assign the model class to.
-    # @param [Class] superclass The superclass for the created class. Should
-    #   have `ActiveRecord::Base` as an ancestor.
+    # @param superclass The superclass for the created class. Either a Class
+    #   having `ActiveRecord::Base` as an ancestor, a String naming one, or a
+    #   callable returning one. A String or callable is resolved afresh for
+    #   every example, which is what allows another `with_model` model - whose
+    #   constant does not exist when this line is read - to be the superclass.
     def initialize(name, superclass: ActiveRecord::Base)
       @name = name.to_sym
       @model_block = nil
       @table_block = nil
       @table_options = {}
-      @superclass = superclass
+      @table_specified = false
+      @skip_table = false
+      @superclass_spec = superclass
     end
 
+    # Records what {WithModel::Model::DSL#table} was asked for, including the
+    # fact that it was asked for at all.
+    def specify_table(options, block)
+      @table_specified = true
+
+      if options == false
+        raise ArgumentError, "table does not take a block when its first argument is falsy" if block
+
+        @skip_table = true
+      else
+        @table_options = options
+        @table_block = block
+      end
+    end
+
+    # Whether a table was specified at all. A `table` call with no arguments
+    # counts, so this cannot be inferred from the options and block alone.
+    def table_specified? = @table_specified
+
     def create
+      @superclass = resolve_superclass
+      @table = nil
       table.create
       @model = Class.new(@superclass) do
         extend WithModel::Methods
@@ -36,22 +65,69 @@ module WithModel
     end
 
     def destroy
+      # Test runners tear down even when setup raised, so `create` may not have
+      # reached the point of building the model. Nothing was stubbed and nothing
+      # wrote rows, so there is nothing to undo.
+      return unless @model
+
+      # 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
-      table.destroy
       WithModel::DescendantsTracker.clear([@model])
       @model = nil
     end
 
     private
 
+    def resolve_superclass
+      spec = @superclass_spec
+      spec = spec.call if spec.respond_to?(:call)
+      spec = constantize_superclass(spec) if class_name?(spec)
+
+      unless spec.is_a?(Class) && spec <= ActiveRecord::Base
+        raise InvalidSuperclass,
+          "superclass must be a Class descending from ActiveRecord::Base, but was #{spec.inspect}. " \
+          "To refer to another with_model class, or anything else that is only defined once the " \
+          "test is running, name it with a String or a Symbol, or pass a callable returning it."
+      end
+
+      spec
+    end
+
+    # A Symbol reads naturally here, since with_model names its own models with
+    # them. Anything else has to answer to `to_str`, which only real strings do:
+    # every object has a `to_s`, so accepting that would quietly look up a
+    # constant named "42".
+    def class_name?(spec)
+      spec.is_a?(Symbol) || spec.respond_to?(:to_str)
+    end
+
+    # `to_s` is safe here where `class_name?` has already vouched for the value,
+    # and it keeps the Symbol intact for the message below, which reports what was
+    # passed in rather than what it was converted to.
+    #
+    # The NameError is worth quoting rather than replacing: for a namespaced name
+    # it reports which segment was missing, which this message cannot work out.
+    # Raising inside the rescue leaves it as the `cause` for anything that wants
+    # the backtrace.
+    def constantize_superclass(name)
+      name.to_s.constantize
+    rescue NameError => e
+      raise MissingSuperclass,
+        "superclass #{name.inspect} could not be resolved: #{e.message}. Names are resolved while " \
+        "the test is running, so a with_model superclass has to be declared before the models " \
+        "that inherit it."
+    end
+
     def const_name
       @name.to_s.camelize.to_sym
     end
 
     def setup_model
-      @model.table_name = table_name
+      table.configure(@model)
       @model.class_eval(&@model_block) if @model_block
       @model.reset_column_information
     end
@@ -72,7 +148,11 @@ module WithModel
     end
 
     def table
-      @table ||= Table.new table_name, @table_options, connection: @superclass.connection, &@table_block
+      @table ||= if @skip_table
+        NullTable.new(@superclass, @name)
+      else
+        Table.new table_name, @table_options, connection: @superclass.connection, &@table_block
+      end
     end
 
     def table_name

data/lib/with_model/null_table.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+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)`.
+  #
+  # 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}.
+  class NullTable
+    # @param [Class] superclass The resolved superclass whose table will be
+    #   inherited.
+    # @param [Symbol, String] name The model's name, so that a refusal can say
+    #   which model it is talking about.
+    def initialize(superclass, name)
+      @superclass = superclass
+      @name = name
+    end
+
+    # Creates nothing, but refuses a superclass that cannot support single
+    # table inheritance.
+    #
+    # Refusals describe the model's situation rather than the call that produced
+    # it. Any expression that evaluates to false selects a NullTable, so there
+    # is no call spelling to quote - and in with_model 3.0, omitting `table`
+    # will arrive here too.
+    #
+    # A superclass whose table does not exist *yet* is deliberately allowed: the
+    # table may be created later in the example, and a test may legitimately
+    # want a model whose table is missing. Active Record raises a clear
+    # `StatementInvalid` naming the table if it never appears, so refusing here
+    # would only forbid working setups.
+    #
+    # What is left is {WithModel::InvalidSuperclass}: both refusals are permanent
+    # facts about the superclass passed in, not about when it was looked at, so no
+    # amount of waiting makes them work.
+    def create
+      refuse "#{@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?
+      return if inheritance_column?
+
+      refuse "#{@superclass}'s table #{@superclass.table_name.inspect} has no " \
+             "#{inheritance_column.inspect} column, so Active Record cannot tell its rows " \
+             "apart from a subclass's"
+    end
+
+    # Deliberately does nothing: leaving `table_name` unassigned is what lets
+    # Active Record's own inheritance supply the superclass's table.
+    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`).
+    #
+    # `unscoped` is required because a `default_scope` on the superclass would
+    # otherwise hide rows from the delete; the inheritance-column condition is
+    # then reapplied explicitly, since `unscoped` also discards the type
+    # condition that keeps this from touching the superclass's own rows.
+    #
+    # 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?
+
+      klass.unscoped.where(klass.inheritance_column => klass.sti_name).delete_all
+    end
+
+    # Drops nothing; there is no table of our own to drop.
+    def destroy
+    end
+
+    private
+
+    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?
+
+    def table_exists? = @superclass.table_exists?
+
+    def inheritance_column?
+      inheritance_column.present? && @superclass.columns_hash.key?(inheritance_column)
+    end
+
+    def refuse(problem)
+      raise InvalidSuperclass,
+        "with_model #{@name.inspect} has no table of its own, but #{problem}"
+    end
+  end
+end

data/lib/with_model/table.rb

@@ -25,6 +25,18 @@ module WithModel
       connection.create_table(@name, **@options, &@block)
     end
 
+    # Points the model at this table.
+    def configure(klass)
+      klass.table_name = @name
+    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.
+    def teardown(_klass)
+      destroy
+    end
+
     def destroy
       connection.drop_table(@name)
     end

data/lib/with_model/version.rb

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

data/lib/with_model.rb

@@ -1,16 +1,24 @@
 # frozen_string_literal: true
 
+require "active_support/deprecation"
+require "with_model/invalid_superclass"
+require "with_model/missing_superclass"
 require "with_model/model"
 require "with_model/model/dsl"
+require "with_model/null_table"
 require "with_model/table"
 require "with_model/version"
 
 module WithModel
   class MiniTestLifeCycle < Module
     def initialize(object)
+      # Each with_model includes a fresh module, so the last one declared sits
+      # earliest in the ancestor chain. Calling super() first means setup runs
+      # in declaration order while teardown unwinds in reverse, which is what
+      # lets one with_model refer to another declared above it.
       define_method :before_setup do
-        object.create
         super() if defined?(super)
+        object.create
       end
 
       define_method :after_teardown do
@@ -32,6 +40,14 @@ module WithModel
     @runner ||= :rspec
   end
 
+  # The deprecator used for with_model's own deprecation warnings. Callers can
+  # silence it (`WithModel.deprecator.silenced = true`) or escalate it
+  # (`behavior = :raise`) while migrating, and Rails applications can register
+  # it in `Rails.application.deprecators`.
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("3.0", "with_model")
+  end
+
   # @param [Symbol] name The constant name to assign the model class to.
   # @param scope Passed to `before`/`after` in the test context. RSpec only.
   # @param options Passed to {WithModel::Model#initialize}.
@@ -41,6 +57,8 @@ module WithModel
     model = Model.new name, **options
     dsl = Model::DSL.new model
     dsl.instance_exec(&block) if block
+    # caller_locations(1) is this method's caller: the `with_model` line itself.
+    WithModel.warn_omitted_table(name, caller_locations(1)) unless model.table_specified?
 
     setup_object(model, scope: scope, runner: runner)
   end
@@ -56,6 +74,26 @@ module WithModel
     setup_object(table, scope: scope, runner: runner)
   end
 
+  # Warns once per call site, at definition time, rather than once per example.
+  # The horizon is stated in the message because `Deprecation#warn` does not
+  # interpolate the deprecator's `deprecation_horizon`.
+  #
+  # The callstack has to be handed in. `ActiveSupport::Deprecation` skips Rails'
+  # own frames and the standard library when working out where a warning came
+  # from, but with_model's frames look like anyone else's to it, so left to itself
+  # it reports this file for every omission in a suite.
+  #
+  # @param callstack Frames to blame, beginning with the caller to report.
+  def self.warn_omitted_table(name, callstack)
+    deprecator.warn(
+      "with_model #{name.inspect} was called without a `table`, which creates a table with only " \
+      "an id column. In with_model 3.0 no table will be created. Call `table` (with no " \
+      "arguments or an empty block) to keep a table, or `table(false)` to inherit the " \
+      "superclass's table (single table inheritance).",
+      callstack
+    )
+  end
+
   private
 
   # @param [Object] object The new model object instance to create

data/spec/active_record_behaviors_spec.rb

@@ -69,6 +69,7 @@ describe "ActiveRecord behaviors" do
       with_table :animals
 
       with_model :StuffedAnimal do
+        table
         model do
           has_many :tea_cups, as: :pet
         end
@@ -101,7 +102,9 @@ describe "ActiveRecord behaviors" do
       end
     end
 
-    with_model :Country
+    with_model :Country do
+      table
+    end
 
     context "in earlier examples" do
       it "works as normal" do

data/spec/descendants_tracking_spec.rb

@@ -4,6 +4,7 @@ require "spec_helper"
 
 describe "Descendants tracking" do
   with_model :BlogPost do
+    table
     model do
       def self.inspect
         "BlogPost class #{object_id}"

data/spec/readme_spec.rb

@@ -2,21 +2,25 @@
 
 require "spec_helper"
 
-describe "A blog post" do
-  before do
-    stub_const("MyModule", Module.new)
-  end
+module MyModule; end
+
+# A pre-existing model
+class Car < ActiveRecord::Base
+  self.abstract_class = true
+end
 
+describe "A blog post" do
   with_model :BlogPost do
-    # The table block works just like a migration.
+    # The table block (and an options hash) is passed to Active Record migration’s `create_table`.
     table do |t|
       t.string :title
       t.timestamps null: false
     end
 
-    # The model block works just like the class definition.
+    # The model block is the Active Record model’s class body.
     model do
       include MyModule
+
       has_many :comments
       validates_presence_of :title
 
@@ -70,15 +74,15 @@ describe "A blog post" do
     expect(record.comments.count).to eq 1
   end
 
-  # with_model classes can have inheritance.
-  class Car < ActiveRecord::Base # standard:disable Lint/ConstantDefinitionInBlock
-    self.abstract_class = true
+  # with_model classes can have inheritance. Car is abstract, so it has no table
+  # and Ford gets one of its own. To inherit a concrete superclass's table
+  # instead, see "Single table inheritance" below.
+  with_model :Ford, superclass: Car do
+    table
   end
 
-  with_model :Ford, superclass: Car
-
   it "has a specified superclass" do
-    expect(Ford < Car).to be true
+    expect(Ford.new).to be_a(Car)
   end
 end
 
@@ -116,3 +120,48 @@ describe "with table options" do
     expect(WithOptions.columns.map(&:name)).not_to include("id")
   end
 end
+
+describe "with_model supports Single Table Inheritance" do
+  with_model :Sandwich do
+    table do |t|
+      t.string "type"
+      t.string "bread"
+    end
+  end
+
+  with_model :ChunkyBacon, superclass: :Sandwich do
+    table(false)
+  end
+
+  it "shares the superclass's table" do
+    expect(ChunkyBacon.table_name).to eq Sandwich.table_name
+  end
+
+  it "stores its own type" do
+    sandwich = ChunkyBacon.create!(bread: "rye")
+
+    expect(sandwich.reload.type).to eq "ChunkyBacon"
+    expect(Sandwich.first).to be_a ChunkyBacon
+  end
+end
+
+describe "with_model supports foreign keys" do
+  with_model :Author do
+    table
+  end
+
+  with_model :Book do
+    table do |t|
+      t.references :author, foreign_key: {to_table: Author.table_name}
+    end
+
+    model do
+      belongs_to :author
+    end
+  end
+
+  it "has a foreign key" do
+    expect { Book.create!(author_id: 0) }
+      .to raise_error ActiveRecord::InvalidForeignKey
+  end
+end

data/spec/spec_helper.rb

@@ -3,6 +3,8 @@
 require "bundler/setup"
 require "with_model"
 
+WithModel.deprecator.behavior = :raise
+
 RSpec.configure do |config|
   config.extend WithModel