Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add #unfreeze_time to ActiveSupport::Testing::TimeHelpers #33813

Merged
merged 1 commit into from Sep 10, 2018

Conversation

@ghost
Copy link

@ghost ghost commented Sep 7, 2018

  • 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
Copy link

@rails-bot rails-bot commented Sep 7, 2018

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
Copy link
Member

@fxn fxn commented Sep 8, 2018

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
Copy link
Author

@ghost ghost commented Sep 8, 2018

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
Copy link
Author

@ghost ghost commented Sep 8, 2018

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
Copy link
Author

@ghost ghost commented Sep 8, 2018

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

@fxn
Copy link
Member

@fxn fxn commented Sep 8, 2018

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
Copy link
Author

@ghost ghost commented Sep 10, 2018

@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
Copy link
Author

@ghost ghost commented Sep 10, 2018

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
# +travel+ and +travel_to+.
# +travel+, +travel_to+ and +freeze_time+.
#
# +travel_back+ is also aliased as +unfreeze_time+.

This comment has been minimized.

@rafaelfranca

rafaelfranca Sep 10, 2018
Member

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

This comment has been minimized.

@ghost

ghost Sep 10, 2018
Author

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

@@ -1,3 +1,10 @@
* 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

This comment has been minimized.

@fxn

fxn Sep 10, 2018
Member

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.

This comment has been minimized.

@ghost

ghost Sep 10, 2018
Author

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

@@ -1,3 +1,10 @@
* Add `unfreeze_time` alias method to `travel_back` in `ActiveSupport::Testing::TimeHelpers`.

This comment has been minimized.

@fxn

fxn Sep 10, 2018
Member

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.

This comment has been minimized.

@ghost

ghost Sep 10, 2018
Author

That grammar change is now updated in the CHANGELOG.

@@ -186,4 +186,8 @@ def test_time_helper_freeze_time_with_block

assert_operator expected_time.to_s(:db), :<, Time.now.to_s(:db)
end

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

This comment has been minimized.

@fxn

fxn Sep 10, 2018
Member

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.

This comment has been minimized.

@ghost

ghost Sep 10, 2018
Author

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.

@@ -1,3 +1,9 @@
* Define `unfreeze_time` alias method of `travel_back` in `ActiveSupport::Testing::TimeHelpers`.

The alias is provided for symmetry with `freeze_time`

This comment has been minimized.

@fxn

fxn Sep 10, 2018
Member

This sentence is missing a full stop.

This comment has been minimized.

@ghost

ghost Sep 10, 2018
Author

Punctuation is important too - now added.

@@ -1,3 +1,9 @@
* Define `unfreeze_time` alias method of `travel_back` in `ActiveSupport::Testing::TimeHelpers`.

This comment has been minimized.

@fxn

fxn Sep 10, 2018
Member

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.

This comment has been minimized.

@ghost

ghost Sep 10, 2018
Author

Right, it now reads:

  • Define unfreeze_time as an alias of travel_back in ActiveSupport::Testing::TimeHelpers.
@fxn
Copy link
Member

@fxn fxn commented Sep 10, 2018

@ryanwhocodes almost there!

@ghost
Copy link
Author

@ghost ghost commented Sep 10, 2018

@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
Copy link
Member

@fxn fxn commented Sep 10, 2018

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/. ❤️

@fxn fxn merged commit 621a4e7 into rails:master Sep 10, 2018
1 check passed
1 check passed
codeclimate All good!
Details
suketa added a commit to suketa/rails_sandbox that referenced this pull request May 24, 2019
Add #unfreeze_time to ActiveSupport::Testing::TimeHelpers
rails/rails#33813
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants
You can’t perform that action at this time.