Add #unfreeze_time to ActiveSupport::Testing::TimeHelpers

[ghost]

• Add unfreeze_time alias method to travel_back in ActiveSupport::Testing::TimeHelpers.

  The method unstubs Time.now and provides a method with a verb symmetry
  to the existing freeze_time method that stubs it.

  Ryan Davidson

This feature was discussed and approved in the Ruby on Rails > Core google group
https://groups.google.com/forum/#!topic/rubyonrails-core/cObTSEWG7XY
[ActiveSupport] feature proposal: Create #unfreeze_time to complement #freeze_time in ActiveSupport::Testing::TimeHelpers

[rails-bot]

Thanks for the pull request, and welcome! The Rails team is excited to review your changes, and you should hear from @kaspth (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

This repository is being automatically checked for code quality issues using Code Climate. You can see results for this analysis in the PR status below. Newly introduced issues should be fixed before a Pull Request is considered ready to review.

Please see the contribution instructions for more information.

[fxn]

Hey!

The motivation for this method is that users can write freeze/unfreeze instead of the equivalent freeze/travel_back, because it reads better.

In that sense, I believe we'd need just an alias here, no need to duplicate code and docs.

[ghost]

Hey @fxn, if I make it an alias how is this recognised in the documentation generated? My concern that to do something like the following may mean the method unfreeze_time may not receive documentation for users to understand it and how to use it. Do you know how Rails handles documenting aliases?

# Returns the current time back to its original state, by removing the stubs added by
      # +travel+ and +travel_to+.
      #
      #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
      #   travel_to Time.zone.local(2004, 11, 24, 01, 04, 44)
      #   Time.current # => Wed, 24 Nov 2004 01:04:44 EST -05:00
      #   travel_back
      #   Time.current # => Sat, 09 Nov 2013 15:34:49 EST -05:00
      def travel_back
        simple_stubs.unstub_all!
      end

      alias_method :unfreeze_time, :travel_back

[ghost]

After having a look at the rdoc documentation I see that it should hopefully just reference the original method in the docs. For example: https://api.rubyonrails.org/classes/ActiveSupport/TimeWithZone.html#method-i-kind_of-3F

[ghost]

I will plan to make the change to use an alias sometime this week and update this PR.

[fxn]

Aliases are extensively used for cases like this when you want to provide the same implementation under a different name for the sake of having a different name. The documentation says the method is an alias of another method, and links to that one. Users understand. See for example titlecase.

You can grep the project for alias_method and see other examples.

[ghost]

@fxn That was helpful to point me to an existing alias example in the rails codebase. I have now updated the code in this PR with an alias for unfreeze_time.

[ghost]

In order to test the aliased method, I used a simple method comparison in the test suite. How does this suit the existing way of testing alias methods in rails?

  def test_time_helper_unfreeze_time
    assert_equal method(:unfreeze_time), method(:travel_back)
  end

[rafaelfranca]

Don't need to document this, our docs generator will automatically add it

[ghost]

That's good to know, this line is now removed from time_helpers.rb

[fxn]

Better to keep this brief.

Since the first line says unfreeze_time is an alias of travel_back, the functionality is already known (as far as what to include in the CHANGELOG is concerned). You can include the rationale though, something like

The alias is provided for symmetry with freeze_time.

would be enough.

[ghost]

I can understand that readers could look up the functionality. This more succinct explanation is now added.

[fxn]

I think "alias method to" is not correct grammatically (though I am not a native speaker). Could be something like

Define unfreeze_time as an alias of travel_back in ActiveSupport::Testing::TimeHelpers.

for example.

[ghost]

That grammar change is now updated in the CHANGELOG.

[fxn]

I believe this is good, and better than duplicating the suite of travel_back. A purist would argue that we are testing the implementation, but the trade-off is great in my view and it trivially guarantees that the suite of travel_back passes for unfreeze_time.

The only detail is that the arguments would conventionally go the other way around, because in minitest the expected value comes first. So, it would be

assert_equal method(:travel_back), method(:unfreeze_time)

instead.

[ghost]

Following syntax conventions are important to avoid potential confusion for someone coming to the test suite at a later date. This has now been changed.

I was initially concerned this might be too simple of a testing approach, but glad you liked the method comparison strategy for testing. I like things like this because if the test suite for travel_back changes, then you don't need to worry about keeping tests for unfreeze in parallel.

[fxn]

This sentence is missing a full stop.

[ghost]

Punctuation is important too - now added.

[fxn]

The idea here was

Define unfreeze_time as an alias of travel_back in ActiveSupport::Testing::TimeHelpers.

"alias method" doesn't sound well because "alias" is actually a noun.

[ghost]

Right, it now reads:

• Define unfreeze_time as an alias of travel_back in ActiveSupport::Testing::TimeHelpers.

[fxn]

@ryanwhocodes almost there!

[ghost]

@fxn Hope we're getting closer now! I've learnt a lot through this process about rails and its workflow, you've been amazing at supporting me thought it all. Look forward to seeing it included in rails (hopefully 🤞)

[fxn]

Perfect!

My pleasure, thanks a lot for your patience and good attitude revising the patch several times with our feedback, and thanks for contributing to Rails. In a few minutes you'll be in https://contributors.rubyonrails.org/. ❤️