marsh_grass 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 75c25a9fd71d7bc9e868b9d82a590e6c98ec1d3b
-  data.tar.gz: 73e7f8bac791254293a91121b7f63850f438e440
+SHA256:
+  metadata.gz: ed2c3a6f128c38e323853492d7edb4708c28baa992d65dbe4a2eb9f12b0214ce
+  data.tar.gz: 6af8c822dd47d3453a1ff2c1a04f8d70243b9422e4278447ff7b0873559936ff
 SHA512:
-  metadata.gz: 746ab6c822be5085e6bde4152d27974ba55b9981ec8aee2fd24feef188b8f9744efdd6e7d290f888506c80f86a6b397ad62df49916bf5fcde19c81469dd1455a
-  data.tar.gz: a6ee7aae1fef25f098f76319047185c8760403c159500ff1496e0834eae2a3d681eae4786e59e8bb0d95a4094ff365d6cbedee1187aafc1812ec12b32de47105
+  metadata.gz: 0e160807e814ce374666835b7a8fa65411c294a892191fb32a4e6f75fd0c6740f694354d2d9028b59f31fe10278f8df0cdbaa67ecbad59b749a2a6ae483365fa
+  data.tar.gz: 14fb47d883f776c885cedf7d278ec7311f914423a8d1670d96146d1d183050bad816633ad7d2dd3a61b0a068f03fffbea48683ac0edc3638a3a6f6342952f823

data/.travis.yml

@@ -1,5 +1,5 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.3.4
-before_install: gem install bundler -v 1.15.3
+  - 2.3.6
+before_install: gem install bundler -v 1.16.1

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Wes Rich
+Copyright (c) 2017 RoleModel Software
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,8 +1,28 @@
 # MarshGrass
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/marsh_grass`. To experiment with that code, run `bin/console` for an interactive prompt.
+Finally! A way to examine the behavior of intermittent failures in RSpec.
 
-TODO: Delete this and the text above, and describe your gem
+This gem allows you to subject an intermittently failing test to a variety of circumstances in an attempt to discern what combination of events leads to failure.
+
+## Background
+
+Intermittent failures are challenging because the failure conditions are more difficult to pinpoint than with tests that fail 100% of the time.
+
+Intermittent failures are also more likely to make it into production. They often pass during CI testing and code review and then crop up days or weeks later.
+
+In programming, there is no such thing as a "random" failure. Every intermittent failure actually fails consistently, every single time... under the right set of circumstances. Perhaps your test only fails on Friday afternoons. Or, 10% of the time under race conditions. We once had a test that failed on every power of 2 run: on the 2nd, 4th, 8th, 16th run, etc. The more we ran it, the more elusive it became.
+
+Often, the first step in fixing such a failure is to make it fail consistently. That way, as you change your code, you can use the test to confirm when you've fixed the root cause. After all, that is the purpose of the test!
+
+## Features
+This gem subjects a given test to the following circumstances:
+- repetitions
+- range of speeds in execution
+- execution at all times of day
+- execution in all time zones
+- execution at all the milliseconds surrounding a particular time of day
+
+In our experience, repetitions is the option we use the most often. It gives the broadest feedback and is very effective at uncovering race conditions.
 
 ## Installation
 
@@ -21,18 +41,100 @@ Or install it yourself as:
     $ gem install marsh_grass
 
 ## Usage
+Feature use:
+- N repetitions (default: 1000, or specify integer)
+- Times of day (default: all hours, minutes, seconds or specify :hours, :minutes, :seconds)
+- Time zones (executes against each time zone offset from ActiveSupport::TimeZone)
+- Elapsed time during test execution (default: (1..10) execution slow-down multipliers or specify range)
+- Surrounding time, i.e., clock change over during the test (must specify hour: <integer>, minute: <integer>, second: <integer>)
+
+Surrounding time runs test at every millisecond from 1 sec before to 1 sec after specified time. This is particularly useful for discerning rate of failure near and at midnight.
+
+### Examples
+Simple examples:
+```ruby
+it 'uses default repetitions', :repetitions do
+ ...
+end
+
+it 'uses specific repetitions', repetitions: 20 do
+  ...
+end
+
+it 'uses just hours for default surrounding_time', :time_of_day do
+ ...
+end
+
+it 'uses each hour of day', time_of_day: :hours do
+  ...
+end
 
-TODO: Write usage instructions here
+it 'uses each hour and minute of the day', time_of_day: [:hours, :minutes] do
+ ...
+end
 
-## Development
+it 'uses each second of current minute', time_of_day: :seconds do
+  ...
+end
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+it 'uses current time for default surrounding_time', :surrounding_time do
+ ...
+end
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+it 'uses each millisecond around hour of day', surrounding_time: { hour: 17 } do
+  ...
+end
+
+it 'uses each millisecond around specified time (noon)', surrounding_time: { hour: 12, minute: 0, second: 0 } do
+ ...
+end
+
+it 'uses 10 different speeds for default elapsed_time', :elapsed_time do
+  ...
+end
+
+it 'uses array of different speeds for elapsed_time', elapsed_time: [1, 5, 10] do
+  ...
+end
+
+it 'uses range of different speeds for elapsed_time', elapsed_time: (1..5) do
+  ...
+end
+
+it 'uses 34 different timezones for default time_zones', :time_zones do
+  ...
+end
+
+it 'uses single named timezone for time_zone (singular)', time_zone: 'Eastern Time (US & Canada)' do
+  ...
+end
+
+it 'uses a specific frozen time with a string', frozen_time: '2025-08-22 17:00:00' do
+  ...
+end
+
+it 'uses a specific frozen time with a Time', frozen_time: Time.new(2025, 8, 22, 17) do
+  ...
+end
+
+it 'uses a specific moving time with a string', moving_time: '2025-08-22 17:00:00' do
+  ...
+end
+
+it 'uses a specific moving time with a Time', moving_time: Time.new(2025, 8, 22, 17) do
+  ...
+end
+
+it 'uses a specific time scalar', scaling_time: 8 do
+  ...
+end
+
+```
+[Further Examples](./spec/marsh_grass_spec.rb) of tests using each feature.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/wesrich/marsh_grass.
+Bug reports and pull requests are welcome on GitHub at https://github.com/RoleModel/marsh_grass.
 
 ## License
 

data/lib/marsh_grass/rspec.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
 require 'rspec'
+require 'time'
 require 'timecop'
-require 'pry'
 
 RSpec.configure do |config|
   def untag_example(example, tag)
     example.example_group.metadata.delete(tag) if example.metadata[:turnip]
-    example.metadata.delete(tag)
+    return_value = example.metadata[tag]
+    example.metadata[tag] = false # Set to false to avoid recursive nested repetitions
+    return_value
+  end
+
+  def add_example_to_group(original_example, test_description, metadata_overrides = {})
+    repetition = original_example.duplicate_with(metadata_overrides)
+    repetition.metadata[:description] = test_description
+    original_example.example_group.context.add_example(repetition)
   end
 
   def run_example_or_duplicate(original_example, test_description)
@@ -16,9 +24,7 @@ RSpec.configure do |config|
       original_example.metadata[:description] = test_description
       original_example.run
     else
-      repetition = original_example.duplicate_with
-      repetition.metadata[:description] = test_description
-      original_example.example_group.context.add_example(repetition)
+      add_example_to_group(original_example, test_description)
     end
   end
 
@@ -27,7 +33,7 @@ RSpec.configure do |config|
 
     now = Time.now
     time_of_day = untag_example(original_example, :time_of_day)
-    test_segments = time_of_day.is_a?(Array) ? time_of_day : [time_of_day]
+    test_segments = Array(time_of_day)
     test_segments = [:hours] if test_segments == [true]
     hours_to_run = test_segments.include?(:hours) ? (0..23) : [now.hour]
     minutes_to_run = test_segments.include?(:minutes) ? (0..59) : [now.min]
@@ -36,13 +42,12 @@ RSpec.configure do |config|
     hours_to_run.each do |hour|
       minutes_to_run.each do |minute|
         seconds_to_run.each do |second|
-          # Freeze time at the specified hour, minute, and/or second.
-          # We need to run the test within the Timecop.freeze block,
-          # in order to actually be affected by Timecop.
-          Timecop.freeze(now.year, now.month, now.day, hour, minute, second) do
-            test_description = "Run Time #{hour}:#{minute}:#{second}: #{shared_description}"
-            run_example_or_duplicate(original_example, test_description)
-          end
+          frozen_time = Time.new(now.year, now.month, now.day, hour, minute, second)
+          test_description = "Run Time #{frozen_time.strftime('%H:%M:%S')}: #{shared_description}"
+          add_example_to_group(original_example, test_description, frozen_time: frozen_time)
+
+          # To avoid the original example being shown as "PENDING", mark it as executed
+          original_example.instance_variable_set(:@executed, true)
         end
       end
     end
@@ -62,30 +67,27 @@ RSpec.configure do |config|
     (-1000..1000).each do |millisecond|
       # Travel to the specified hour, minute, second, and millisecond, allowing
       # for time to elapse.
-      # We need to run the test within the Timecop.freeze block,
-      # in order to actually be affected by Timecop.
-      test_time = Time.at(test_time_float + millisecond.to_f / 1000)
-      Timecop.travel(test_time) do
-        test_description = "Run Time #{test_time.strftime('%H:%M:%S:%L')}: #{shared_description}"
-        run_example_or_duplicate(original_example, test_description)
-      end
+      moving_time = Time.at(test_time_float + millisecond.to_f / 1000)
+      test_description = "Run Time #{moving_time.strftime('%H:%M:%S:%L')}: #{shared_description}"
+      add_example_to_group(original_example, test_description, moving_time: moving_time)
+
+      # To avoid the original example being shown as "PENDING", mark it as executed
+      original_example.instance_variable_set(:@executed, true)
     end
   end
 
   config.around(elapsed_time: true) do |original_example|
     shared_description = original_example.metadata[:description]
 
-    # Freeze time at the specified hour, minute, and/or second.
-    # We need to run the test within the Timecop.freeze block,
-    # in order to actually be affected by Timecop.
     time_multipliers = untag_example(original_example, :elapsed_time)
     time_multipliers = (1..10) unless time_multipliers.respond_to?(:each)
 
     time_multipliers.each do |seconds_multiplier|
-      Timecop.scale(seconds_multiplier) do
-        test_description = "Run Speed #{seconds_multiplier}x Slower: #{shared_description}"
-        run_example_or_duplicate(original_example, test_description)
-      end
+      test_description = "Run Speed #{seconds_multiplier}x Slower: #{shared_description}"
+      add_example_to_group(original_example, test_description, scaling_time: seconds_multiplier)
+
+      # To avoid the original example being shown as "PENDING", mark it as executed
+      original_example.instance_variable_set(:@executed, true)
     end
   end
 
@@ -93,21 +95,16 @@ RSpec.configure do |config|
     shared_description = original_example.metadata[:description]
     untag_example(original_example, :time_zones)
 
-    utc = Time.now.utc
-    time_zone_hours = %w[-12 -11 -10 -09 -08 -07 -06 -05 -04 -03 -02 -01 +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +10 +11 +12 +13 +14]
-    time_zone_minutes = %w[00 30]
-
-    time_zone_hours.each do |time_zone_hour|
-      time_zone_minutes.each do |time_zone_minute|
-        # We need to run the test within the Timecop.freeze block,
-        # in order to actually be affected by Timecop.
-        adjustment = "#{time_zone_hour}:#{time_zone_minute}"
-        adjusted_time = Time.new(utc.year, utc.month, utc.day, utc.hour, utc.min, utc.sec, adjustment)
-        Timecop.travel(adjusted_time) do
-          test_description = "Time Zone Offset #{time_zone_hour}:#{time_zone_minute}: #{shared_description}"
-          run_example_or_duplicate(original_example, test_description)
-        end
-      end
+    timezone_hash = ActiveSupport::TimeZone.all.each_with_object({}) do |tz, memo|
+      memo[tz.formatted_offset] = tz.name
+    end
+
+    timezone_hash.each do |time_zone_offset, time_zone_name|
+      test_description = "Time Zone Offset #{time_zone_offset}: #{shared_description}"
+      add_example_to_group(original_example, test_description, time_zone: time_zone_name)
+
+      # To avoid the original example being shown as "PENDING", mark it as executed
+      original_example.instance_variable_set(:@executed, true)
     end
   end
 
@@ -122,4 +119,46 @@ RSpec.configure do |config|
       run_example_or_duplicate(original_example, test_description)
     end
   end
+
+  config.before(:each, frozen_time: true) do |example|
+    time = example.metadata[:frozen_time]
+    time = Time.parse(example.metadata[:frozen_time]) if time.is_a?(String)
+    # Freeze time at the specified hour, minute, and/or second.
+    Timecop.freeze(time)
+  end
+
+  config.after(:each, frozen_time: true) do
+    Timecop.return
+  end
+
+  config.before(:each, moving_time: true) do |example|
+    time = example.metadata[:moving_time]
+    time = Time.parse(example.metadata[:moving_time]) if time.is_a?(String)
+    # Travel to time at the specified hour, minute, and/or second.
+    Timecop.travel(time)
+  end
+
+  config.after(:each, moving_time: true) do
+    Timecop.return
+  end
+
+  config.before(:each, scaling_time: true) do |example|
+    time_multiplier = example.metadata[:scaling_time]
+    # Scale time by the specified multiplier.
+    Timecop.scale(time_multiplier)
+  end
+
+  config.after(:each, scaling_time: true) do
+    Timecop.return
+  end
+
+  config.before(:each, time_zone: true) do |example|
+    ENV['OLD_TIME_ZONE'] = Time.zone&.name
+    # Switch to the given time zone for the duration of the example.
+    Time.zone = example.metadata[:time_zone]
+  end
+
+  config.after(:each, time_zone: true) do
+    Time.zone = ENV['OLD_TIME_ZONE']
+  end
 end

data/lib/marsh_grass/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MarshGrass
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'
 end

data/marsh_grass.gemspec

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'marsh_grass/version'
@@ -10,16 +9,16 @@ Gem::Specification.new do |spec|
   spec.version       = MarshGrass::VERSION
   spec.authors       = [
     'Wes Rich',
-    'Amanda Simon'
+    'Amanda Pouget'
   ]
   spec.email         = [
     'wes.rich@rolemodelsoftware.com',
-    'amanda.simon@rolemodelsoftware.com'
+    'amanda.pouget@rolemodelsoftware.com'
   ]
 
-  spec.summary       = %q{A set of tools to help diagnose random test failures.}
-  spec.description   = %q{Currently works with RSpec tags to run against possible test failure scenarios.}
-  spec.homepage      = ""
+  spec.summary       = 'A set of tools to help diagnose random test failures.'
+  spec.description   = 'Currently works with RSpec tags to run against possible test failure scenarios.'
+  spec.homepage      = 'https://github.com/RoleModel/marsh_grass'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
@@ -29,10 +28,13 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.required_ruby_version = '>= 3.0'
+
+  spec.add_development_dependency 'bundler', '>= 2.0', '< 5.0'
   spec.add_development_dependency 'pry-byebug', '~> 3'
-  spec.add_development_dependency 'pry-doc', '~> 0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_dependency 'activesupport', '>= 7.1', '< 8.1'
   spec.add_dependency 'rspec', '~> 3.6'
-  spec.add_dependency 'timecop', '~> 0'
+  spec.add_dependency 'rspec-rails', '~> 6'
+  spec.add_dependency 'timecop', '~> 0.9'
 end

metadata

@@ -1,72 +1,83 @@
 --- !ruby/object:Gem::Specification
 name: marsh_grass
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Wes Rich
-- Amanda Simon
-autorequire: 
+- Amanda Pouget
 bindir: exe
 cert_chain: []
-date: 2017-10-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '3'
 - !ruby/object:Gem::Dependency
-  name: pry-byebug
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: pry-doc
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -81,25 +92,39 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6'
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
 description: Currently works with RSpec tags to run against possible test failure
   scenarios.
 email:
 - wes.rich@rolemodelsoftware.com
-- amanda.simon@rolemodelsoftware.com
+- amanda.pouget@rolemodelsoftware.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -115,11 +140,10 @@ files:
 - lib/marsh_grass/rspec.rb
 - lib/marsh_grass/version.rb
 - marsh_grass.gemspec
-homepage: ''
+homepage: https://github.com/RoleModel/marsh_grass
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -127,16 +151,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.13
-signing_key: 
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A set of tools to help diagnose random test failures.
 test_files: []