timecop-rspec 1.0.0

data/gemfiles/modular/documentation.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Documentation
+gem "kramdown", "~> 2.5", ">= 2.5.1" # Ruby >= 2.5
+gem "kramdown-parser-gfm", "~> 1.1" # Ruby >= 2.3
+gem "yard", "~> 0.9", ">= 0.9.37", :require => false
+gem "yard-junk", "~> 0.0", ">= 0.0.10", :github => "pboling/yard-junk", :branch => "next", :require => false
+gem "yard-relative_markdown_links", "~> 0.5.0"
+
+# Std Lib extractions
+gem "rdoc", "~> 6.11"

data/gemfiles/modular/style.gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# We run rubocop on the latest version of Ruby,
+#   but in support of the oldest supported version of Ruby
+
+gem "reek", "~> 6.4"
+gem "rubocop", "~> 1.73", ">= 1.73.2"
+gem "rubocop-lts", "~> 0.1", ">= 0.1.1" # Linting for Ruby >= 1.8
+gem "rubocop-packaging", "~> 0.6", ">= 0.6.0"
+gem "rubocop-rspec", "~> 3.2"
+gem "standard", ">= 1.50"
+
+# Std Lib extractions
+gem "benchmark", "~> 0.4", ">= 0.4.1" # Removed from Std Lib in Ruby 3.5

data/gemfiles/ruby_2_3.gemfile

@@ -0,0 +1,5 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gemspec :path => "../"

data/gemfiles/ruby_2_4.gemfile

@@ -0,0 +1,5 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gemspec :path => "../"

data/gemfiles/ruby_2_5.gemfile

@@ -0,0 +1,5 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gemspec :path => "../"

data/gemfiles/ruby_2_6.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gem "mutex_m", "~> 0.2"
+gem "stringio", "~> 3.0"
+
+gemspec :path => "../"

data/gemfiles/ruby_2_7.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gem "mutex_m", "~> 0.2"
+gem "stringio", "~> 3.0"
+
+gemspec :path => "../"

data/gemfiles/ruby_3_0.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gem "mutex_m", "~> 0.2"
+gem "stringio", "~> 3.0"
+
+gemspec :path => "../"

data/gemfiles/ruby_3_1.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gem "mutex_m", "~> 0.2"
+gem "stringio", "~> 3.0"
+
+gemspec :path => "../"

data/gemfiles/ruby_3_2.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gem "mutex_m", "~> 0.2"
+gem "stringio", "~> 3.0"
+
+gemspec :path => "../"

data/gemfiles/ruby_3_3.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gem "mutex_m", "~> 0.2"
+gem "stringio", "~> 3.0"
+
+gemspec :path => "../"

data/gemfiles/style.gemfile

@@ -0,0 +1,10 @@
+# This file was generated by Appraisal2
+
+source "https://rubygems.org"
+
+gem "mutex_m", "~> 0.2"
+gem "stringio", "~> 3.0"
+
+gemspec :path => "../"
+
+eval_gemfile("modular/style.gemfile")

data/lib/timecop/rspec/example_decorator.rb

@@ -0,0 +1,100 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014-2017 Avant
+
+# Author Zach Taylor
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+class Timecop
+  module Rspec
+    # Decorates an RSpec example to interpret timecop metadata.
+    #
+    # Recognized metadata keys:
+    # - :freeze => Time/Date/DateTime/String/Proc to freeze time to
+    # - :travel => Time/Date/DateTime/String/Proc to travel to (and optionally continue)
+    # - :skip_global_timecop => when present, disables global time for this example
+    class ExampleDecorator < SimpleDelegator
+      # @return [Boolean] whether any timecop behavior applies to the example
+      def timecop?
+        local_timecop? || global_timecop?
+      end
+
+      # Determines the timecop method to invoke.
+      # @return [Symbol, nil] :freeze, :travel, or nil
+      def timecop_method
+        local_timecop_method || global_timecop_method
+      end
+
+      # Determines the time to use for the chosen timecop method.
+      # @return [Object, nil] a time-like object or nil when not applicable
+      def timecop_time
+        local_timecop_time || global_timecop_time
+      end
+
+      # Whether the example has local timecop metadata.
+      # @return [Boolean]
+      def local_timecop?
+        local_timecop_method.present?
+      end
+
+      # Whether a global time is configured and not skipped by the example.
+      # @return [Boolean]
+      def global_timecop?
+        Rspec.global_time_configured? && !skip_global_timecop?
+      end
+
+      # Whether the example requested skipping global timecop behavior.
+      # @return [Boolean]
+      def skip_global_timecop?
+        metadata.key?(:skip_global_timecop)
+      end
+
+      private
+
+      # Reads the timecop method from example metadata.
+      # @return [Symbol, nil]
+      def local_timecop_method
+        metadata.keys.find do |key|
+          key == :freeze || key == :travel
+        end
+      end
+
+      # Evaluates local timecop time, supporting Proc values evaluated in the example context.
+      # @return [Object, nil]
+      def local_timecop_time
+        time = metadata[timecop_method]
+        return if time.nil?
+        time.respond_to?(:call) ? example.instance_exec(&time) : time
+      end
+
+      # Global time always uses :travel.
+      # @return [Symbol, nil]
+      def global_timecop_method
+        :travel if global_timecop?
+      end
+
+      # Global time value when applicable.
+      # @return [Time, nil]
+      def global_timecop_time
+        Rspec.global_time if global_timecop?
+      end
+    end
+  end
+end

data/lib/timecop/rspec/sequential_time_machine.rb

@@ -0,0 +1,80 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014-2017 Avant
+
+# Author Zach Taylor
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative "example_decorator"
+require_relative "traveler"
+require_relative "travel_log"
+
+class Timecop
+  module Rspec
+    # Executes examples while allowing time travel to continue across examples.
+    #
+    # Uses TravelLog to coalesce sequential :travel operations when the same
+    # method and start time are reused, enabling long-running time journeys
+    # across multiple examples.
+    class SequentialTimeMachine
+      # Singleton instance accessor.
+      # @return [Timecop::Rspec::SequentialTimeMachine]
+      def self.instance
+        @instance ||= new
+      end
+
+      # Run an example with either local or global travel, or without any timecop.
+      # @param example [#run,#metadata]
+      # @return [Object]
+      def run(example)
+        example = ExampleDecorator.new(example)
+
+        runner_for(example).run
+      end
+
+      private
+
+      # Selects the appropriate runner for the example.
+      # @param example [ExampleDecorator]
+      # @return [#run]
+      def runner_for(example)
+        if example.local_timecop?
+          Traveler.new(example, local_travel_log)
+        elsif example.global_timecop?
+          Traveler.new(example, global_travel_log)
+        else
+          example
+        end
+      end
+
+      # Local travel log used for examples that specify local timecop metadata.
+      # @return [TravelLog]
+      def local_travel_log
+        @local_travel_log ||= TravelLog.new
+      end
+
+      # Global travel log used when a global time is configured.
+      # @return [TravelLog]
+      def global_travel_log
+        @global_travel_log ||= TravelLog.new(:travel, Rspec.global_time)
+      end
+    end
+  end
+end

data/lib/timecop/rspec/time_machine.rb

@@ -0,0 +1,58 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014-2017 Avant
+
+# Author Zach Taylor
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require "timecop"
+
+require_relative "example_decorator"
+
+class Timecop
+  module Rspec
+    # Executes an example using Timecop for a single, isolated time operation.
+    class TimeMachine
+      # Singleton instance accessor.
+      # @return [Timecop::Rspec::TimeMachine]
+      def self.instance
+        @instance ||= new
+      end
+
+      # Run an RSpec example, applying local timecop metadata if present.
+      #
+      # @param example [#run,#metadata] An RSpec example or object responding to
+      #   the example protocol that will be wrapped by ExampleDecorator.
+      # @return [Object] the result of running the example
+      def run(example)
+        example = ExampleDecorator.new(example)
+
+        return example.run unless example.timecop?
+
+        method = example.timecop_method
+        time = example.timecop_time
+
+        Timecop.public_send(method, time) do
+          example.run
+        end
+      end
+    end
+  end
+end

data/lib/timecop/rspec/travel_log.rb

@@ -0,0 +1,103 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014-2017 Avant
+
+# Author Zach Taylor
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+class Timecop
+  module Rspec
+    # Tracks details about a time travel operation that can be resumed later.
+    class TravelLog
+      # @param travel_method [Symbol, nil] :travel or :freeze (or nil)
+      # @param start_time [Object, nil] a time-like object or string
+      def initialize(travel_method = nil, start_time = nil)
+        new_trip(travel_method, start_time)
+      end
+
+      # Either resumes a previous trip or starts a new one.
+      # @param travel_method [Symbol] :travel or :freeze
+      # @param start_time [Object] a time-like object or string
+      # @return [Object] the computed starting time for the trip
+      def resume_or_new_trip(travel_method, start_time)
+        if resume_trip?(travel_method, start_time)
+          resume_trip
+        else
+          new_trip(travel_method, start_time)
+        end
+      end
+
+      # Pauses the current trip, recording its duration.
+      # @return [void]
+      def pause_trip
+        self.trip_duration = Time.current - coalesced_start_time
+      end
+
+      private
+
+      attr_accessor :travel_method, :start_time, :trip_duration
+
+      # Starts a new trip tracking session.
+      # @param travel_method [Symbol, nil]
+      # @param start_time [Object, nil]
+      # @return [void]
+      def new_trip(travel_method, start_time)
+        reset_duration
+        self.travel_method = travel_method
+        self.start_time = start_time
+      end
+
+      # Determines whether the provided method/time match the current trip.
+      # @return [Boolean]
+      def resume_trip?(other_travel_method, other_start_time)
+        travel_method == other_travel_method &&
+          start_time == other_start_time &&
+          start_time.class == other_start_time.class
+      end
+
+      # The start time for resuming a trip including the elapsed duration.
+      # @return [Object]
+      def resume_trip
+        coalesced_start_time + trip_duration.seconds
+      end
+
+      # Coerces various time-like inputs into a Time-like baseline.
+      # @return [Object]
+      def coalesced_start_time
+        case start_time
+        when DateTime
+          start_time
+        when Date
+          start_time.at_beginning_of_day
+        when String
+          Time.parse(start_time)
+        else
+          start_time
+        end
+      end
+
+      # Resets the recorded duration.
+      # @return [void]
+      def reset_duration
+        self.trip_duration = 0
+      end
+    end
+  end
+end

data/lib/timecop/rspec/traveler.rb

@@ -0,0 +1,68 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014-2017 Avant
+
+# Author Zach Taylor
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+class Timecop
+  module Rspec
+    # Runs an example, optionally continuing a travel across invocations.
+    class Traveler
+      # @param example [ExampleDecorator]
+      # @param travel_log [TravelLog]
+      def initialize(example, travel_log)
+        @example = example
+        @travel_log = travel_log
+      end
+
+      # Executes the example within the appropriate Timecop context.
+      # If the method is :travel, the starting time may be adjusted based on
+      # prior trips recorded in the travel log.
+      #
+      # @return [Object]
+      def run
+        method = example.timecop_method
+        time = example.timecop_time
+
+        if method == :travel
+          time = travel_log.resume_or_new_trip(
+            example.timecop_method, example.timecop_time
+          )
+        end
+
+        ::Timecop.public_send(method, time) do
+          begin
+            example.run
+          ensure
+            travel_log.pause_trip if method == :travel
+          end
+        end
+      end
+
+      private
+
+      # @return [ExampleDecorator]
+      attr_reader :example
+      # @return [TravelLog]
+      attr_reader :travel_log
+    end
+  end
+end

data/lib/timecop/rspec/version.rb

@@ -0,0 +1,37 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014-2017 Avant
+
+# Author Zach Taylor
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+class Timecop
+  module Rspec
+    # Version namespace for Timecop::Rspec.
+    module Version
+      # The gem version.
+      # @return [String]
+      VERSION = "1.0.0"
+    end
+    # Convenience constant aliasing Version::VERSION
+    # @return [String]
+    VERSION = Version::VERSION
+  end
+end

data/lib/timecop/rspec.rb

@@ -0,0 +1,78 @@
+# The MIT License (MIT)
+
+# Copyright (c) 2014-2017 Avant
+
+# Author Zach Taylor
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require "timecop/rspec/version"
+require "active_support/all"
+
+Dir.glob(File.join(__dir__, "rspec", "**", "*.rb")).each { |file| require file }
+
+# Top-level namespace for Timecop helpers.
+class Timecop
+  # RSpec integration for the timecop gem.
+  #
+  # Provides helpers to run examples with frozen or traveling time, and an
+  # optional global time that applies across examples when configured via ENV.
+  #
+  # Environment variables:
+  # - GLOBAL_TIME_TRAVEL_TIME: String representation of a time (preferred)
+  # - GLOBAL_TIME_TRAVEL_DATE: String representation of a date (fallback)
+  module Rspec
+    class << self
+      # Selects a time machine strategy.
+      #
+      # @param sequential [Boolean] when true, uses a sequential strategy that
+      #   can continue a travel across examples; when false, uses a simple per
+      #   example strategy.
+      # @return [Timecop::Rspec::SequentialTimeMachine, Timecop::Rspec::TimeMachine]
+      def time_machine(sequential: false)
+        if sequential
+          SequentialTimeMachine.instance
+        else
+          TimeMachine.instance
+        end
+      end
+
+      # Whether a global time has been configured via ENV.
+      # @return [Boolean]
+      def global_time_configured?
+        global_time_travel_string.present?
+      end
+
+      # The globally configured time parsed from ENV.
+      # @return [Time] the parsed time
+      # @raise [ArgumentError] if ENV contains an unparsable time/date string
+      def global_time
+        @global_time ||= Time.parse(global_time_travel_string)
+      end
+
+      private
+
+      # The raw ENV value used to determine the global time.
+      # @return [String, nil]
+      def global_time_travel_string
+        ENV["GLOBAL_TIME_TRAVEL_TIME"] || ENV["GLOBAL_TIME_TRAVEL_DATE"]
+      end
+    end
+  end
+end