Add `time` option to `#touch`

Fixes #18905. `#touch` now takes time as an option. Setting the option
saves the record with the updated_at/on attributes set to the current time
or the time specified. Updated tests and documentation accordingly.

1 files changed, 21 insertions, 0 deletions

diff --git a/activerecord/test/cases/timestamp_test.rb b/activerecord/test/cases/timestamp_test.rb
index db474c63a4..c0c62527df 100644
--- a/activerecord/test/cases/timestamp_test.rb
+++ b/activerecord/test/cases/timestamp_test.rb
@@ -73,6 +73,15 @@ class TimestampTest < ActiveRecord::TestCase
     assert_equal @previously_updated_at, @developer.updated_at
   end
 
+  def test_touching_updates_timestamp_with_given_time
+    previously_updated_at = @developer.updated_at 
+    new_time = Time.utc(2015, 2, 16, 0, 0, 0) 
+    @developer.touch(time: new_time) 
+
+    assert_not_equal previously_updated_at, @developer.updated_at 
+    assert_equal new_time, @developer.updated_at 
+  end
+
   def test_touching_an_attribute_updates_timestamp
     previously_created_at = @developer.created_at
     @developer.touch(:created_at)
@@ -91,6 +100,18 @@ class TimestampTest < ActiveRecord::TestCase
     assert_in_delta Time.now, task.ending, 1
   end
 
+  def test_touching_an_attribute_updates_timestamp_with_given_time
+    previously_updated_at = @developer.updated_at 
+    previously_created_at = @developer.created_at
+    new_time = Time.utc(2015, 2, 16, 4, 54, 0) 
+    @developer.touch(:created_at, time: new_time)
+
+    assert_not_equal previously_created_at, @developer.created_at
+    assert_not_equal previously_updated_at, @developer.updated_at
+    assert_equal new_time, @developer.created_at
+    assert_equal new_time, @developer.updated_at
+  end
+
   def test_touching_many_attributes_updates_them
     task = Task.first
     previous_starting = task.starting