Deprecate with on define_enum_for in favor of with_values

We'll need to introduce some other `with_*` qualifiers and it won't look
right to have one qualifier called `with` and other qualifiers called
`with_something_else`.

lib/shoulda/matchers/active_record/define_enum_for_matcher.rb

@@ -20,10 +20,10 @@ module ActiveRecord
       #
       # #### Qualifiers
       #
-      # ##### with
+      # ##### with_values
       #
-      # Use `with` to test that the attribute has been defined with a certain
-      # set of known values.
+      # Use `with_values` to test that the attribute has been defined with a
+      # certain set of possible values.
       #
       #     class Process < ActiveRecord::Base
       #       enum status: [:running, :stopped, :suspended]
@@ -33,14 +33,14 @@ module ActiveRecord
       #     RSpec.describe Process, type: :model do
       #       it do
       #         should define_enum_for(:status).
-      #           with([:running, :stopped, :suspended])
+      #           with_values([:running, :stopped, :suspended])
       #       end
       #     end
       #
       #     # Minitest (Shoulda)
       #     class ProcessTest < ActiveSupport::TestCase
       #       should define_enum_for(:status).
-      #         with([:running, :stopped, :suspended])
+      #         with_values([:running, :stopped, :suspended])
       #     end
       #
       # ##### backed_by_column_of_type
@@ -60,7 +60,7 @@ module ActiveRecord
       #     RSpec.describe LoanApplication, type: :model do
       #       it do
       #         should define_enum_for(:status).
-      #           with(
+      #           with_values(
       #             active: "active",
       #             pending: "pending",
       #             rejected: "rejected"
@@ -72,7 +72,7 @@ module ActiveRecord
       #     # Minitest (Shoulda)
       #     class LoanApplicationTest < ActiveSupport::TestCase
       #       should define_enum_for(:status).
-      #         with(
+      #         with_values(
       #           active: "active",
       #           pending: "pending",
       #           rejected: "rejected"
@@ -94,11 +94,19 @@ def initialize(attribute_name)
           @options = {}
         end
 
-        def with(expected_enum_values)
+        def with_values(expected_enum_values)
           options[:expected_enum_values] = expected_enum_values
           self
         end
 
+        def with(expected_enum_values)
+          Shoulda::Matchers.warn_about_deprecated_method(
+            'The `with` qualifier on `define_enum_for`',
+            '`with_values`'
+          )
+          with_values(expected_enum_values)
+        end
+
         def backed_by_column_of_type(expected_column_type)
           options[:expected_column_type] = expected_column_type
           self

spec/unit/shoulda/matchers/active_record/define_enum_for_matcher_spec.rb

@@ -123,7 +123,7 @@ def self.statuses; end
           MESSAGE
 
           assertion = lambda do
-            expect(record).to define_enum_for(:attr).with(['open', 'close'])
+            expect(record).to define_enum_for(:attr).with_values(['open', 'close'])
           end
 
           expect(&assertion).to fail_with_message(message)
@@ -144,7 +144,7 @@ def self.statuses; end
             MESSAGE
 
             assertion = lambda do
-              expect(record).to define_enum_for(:attr).with(['open', 'close'])
+              expect(record).to define_enum_for(:attr).with_values(['open', 'close'])
             end
 
             expect(&assertion).to fail_with_message(message)
@@ -159,7 +159,7 @@ def self.statuses; end
             )
 
             expect(record).to define_enum_for(:attr).
-              with(['published', 'unpublished', 'draft'])
+              with_values(['published', 'unpublished', 'draft'])
           end
         end
       end
@@ -180,7 +180,7 @@ def self.statuses; end
           assertion = lambda do
             expect(record).
               to define_enum_for(:attr).
-              with(active: 5, archived: 10)
+              with_values(active: 5, archived: 10)
           end
 
           expect(&assertion).to fail_with_message(message)
@@ -203,7 +203,7 @@ def self.statuses; end
             assertion = lambda do
               expect(record).
                 to define_enum_for(:attr).
-                with(active: 5, archived: 10)
+                with_values(active: 5, archived: 10)
             end
 
             expect(&assertion).to fail_with_message(message)
@@ -220,7 +220,7 @@ def self.statuses; end
 
               expect(record).
                 to define_enum_for(:attr).
-                with(active: 0, archived: 1)
+                with_values(active: 0, archived: 1)
             end
           end
 
@@ -233,14 +233,32 @@ def self.statuses; end
 
               expect(record).
                 to define_enum_for(:attr).
-                with(['active', 'archived'])
+                with_values(['active', 'archived'])
             end
           end
         end
       end
     end
   end
 
+  context 'with values specified using #with' do
+    it 'produces a warning' do
+      record = build_record_with_array_values(
+        attribute_name: :attr,
+        values: [:foo, :bar],
+      )
+
+      assertion = lambda do
+        expect(record).to define_enum_for(:attr).with([:foo, :bar])
+      end
+
+      expect(&assertion).to deprecate(
+        'The `with` qualifier on `define_enum_for`',
+        '`with_values`',
+      )
+    end
+  end
+
   describe 'with the backing column specified to be of some type' do
     context 'if the column storing the attribute is of a different type' do
       it 'rejects with an appropriate failure message' do