consistent_random 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e59a824de4f8d0a629bf033a675d48f3f5d40b6ffda07f0cf32c8f39d50dc7a2
-  data.tar.gz: '08df13b6bbc9005e38fef21e05768b23eb1c1cbe36cda08694a0ce16bd800baa'
+  metadata.gz: 87b396dd6b089d0fb4c99777531eb0824a4d78b2180bce9eeee6484efd06ddbd
+  data.tar.gz: f5ade642f1222468d68ca326cfad4a206b9e74b97fe786e2497d13e9a67a0459
 SHA512:
-  metadata.gz: 31a8b9bb4996cefee885f4c2c3c251931b86db801443bbe9cafc383c882e7e4ae8be133a8d1d6b5032dcd1422c9906b33c2813ad1f857a0e81b2c81074a7a29d
-  data.tar.gz: 76ae572f27d9e1ca92216e77d878b75bd934f0c81a03abdb1e811181a49fdd0e22231ce1a236f019274701aa35d80c16d3e3e6a898a853df85294a82edb561bd
+  metadata.gz: 8ab235ba4d2b6b447e05614cd603c739461e1d3e0efad6c088ff07b966b6daf207f76c413a49dc00d78125ee12f1ca252b91cba01154d00441bc03dd00523628
+  data.tar.gz: 4a5ca92427978a6f496bc75b057c6982bf7a9eac870eef9139ab5e1cce36aab236c2da6acaf50b551d483d696ce6235d063ba4883a37110569b8f4395571e5e7

data/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.2.0
+
+### Added
+
+- Added `ConsistentRandom.testing` method to allow for deterministic testing of random values.
+- Added `ConsistentRandom#name` method to return the name used for seeding the random value.
+
 ## 2.1.1
 
 ### Fixed

data/README.md

@@ -18,6 +18,7 @@ For example, consider rolling out a new feature to a subset of requests. You may
   - [Rack Middleware](#rack-middleware)
   - [Sidekiq Middleware](#sidekiq-middleware)
   - [ActiveJob](#activejob)
+- [Testing](#testing)
 - [Installation](#installation)
 - [Contributing](#contributing)
 - [License](#license)
@@ -206,6 +207,36 @@ class MyJob < ApplicationJob
 end
 ```
 
+## Testing
+
+The gem provides a `ConsistentRandom.testing` method to allow for deterministic testing of random values. This method can be used to set fixed values within the block so that your tests will produce consistent results.
+
+```ruby
+# Specify that all random values should be 0.5
+ConsistentRandom.testing.rand(0.5) do
+  expect(ConsistentRandom.new("foo").rand).to eq(0.5)
+  expect(ConsistentRandom.new("bar").rand).to eq(0.5)
+
+  # The rand value must be between 0 and 1, but it will be scaled to fit
+  # any size or range specified for `rand`.
+  expect(ConsistentRandom.new("foo").rand(10)).to eq(5)
+end
+
+# You can also specify values for specific names.
+# If a values isn't specified, it will return a random value.
+ConsistentRandom.testing(foo: 0.5, bar: 0.8) do
+  expect(ConsistentRandom.new("foo").rand).to eq(0.5)
+  expect(ConsistentRandom.new("bar").rand).to eq(0.8)
+end
+
+# You can also specify values for the `bytes` and `seed` methods. The methods
+# for setting test valus can be chained together.
+ConsistentRandom.testing.bytes(foo: "bar").seed(baz: 123) do
+  expect(ConsistentRandom.new("foo").bytes(6)).to eq("barbar")
+  expect(ConsistentRandom.new("baz").seed).to eq(123)
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-2.1.1
+2.2.0

data/lib/consistent_random/testing.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+class ConsistentRandom
+  # This class returns an object that can be used to generate deterministic values
+  # for use in testing.
+  #
+  # @example
+  #  ConsistentRandom.testing.rand(foo: 0.5).bytes(foo: "foobar").seed(123) do
+  #    expect(ConsistentRandom.new("foo").rand).to eq(0.5)
+  #    expect(ConsistentRandom.new("bar").rand).not_to eq(0.5)
+  #
+  #    expect(ConsistentRandom.new("foo").bytes(12)).to eq("foobarfoobar")
+  #
+  #    expect(ConsistentRandom.new("foo").seed).to eq(123)
+  #  end
+  class ConsistentRandom::Testing
+    class << self
+      # Get the testing object if any for the current block.
+      #
+      # @return [ConsistentRandom::Testing, nil] the testing object or nil if not set
+      # @api private
+      def current
+        Thread.current[:consistent_random_testing]
+      end
+    end
+
+    def initialize
+      @rand_hash = {}
+      @bytes_hash = {}
+      @seed_hash = {}
+    end
+
+    # Set the random value returned by ConsistentRandom#rand.
+    #
+    # param options [Float, Hash<String, Float>] the value to return for rand. If a Float is given
+    #  then it will be used as the value for all calls to rand. If a Hash is given then the value
+    #  will only be returned for ConsitentRandom objects with the names specified in the keys.
+    # @yield block of code to execute with the test values.
+    # @return [ConsistentRandom::Testing, Object] If a block is specified, then the result
+    #   of the block is returned. Otherwise the testing object is returned so that you can
+    #   chain calls to set up more test values.
+    def rand(options, &block)
+      options = validate_rand(options)
+      unless options
+        raise ArgumentError.new("Argument must be a Float between 0 and 1 or a Hash with Float values")
+      end
+
+      @rand_hash = options.default ? options.merge(@rand_hash) : @rand_hash.merge(options)
+      if block
+        use(&block)
+      else
+        self
+      end
+    end
+
+    # Set the random bytes returned by ConsistentRandom#bytes.
+    #
+    # param options [String, Hash<String, String>] the value to return for bytes. If a String is given
+    #  then it will be used as the value for all calls to bytes. If a Hash is given then the value
+    #  will only be returned for ConsitentRandom objects with the names specified in the keys.
+    # @yield block of code to execute with the test values.
+    # @return [ConsistentRandom::Testing, Object] If a block is specified, then the result
+    #   of the block is returned. Otherwise the testing object is returned so that you can
+    #   chain calls to set up more test values.
+    def bytes(options, &block)
+      options = validate_bytes(options)
+      unless options
+        raise ArgumentError.new("Argument must be a String or a Hash with String values")
+      end
+
+      @bytes_hash = options.default ? options.merge(@bytes_hash) : @bytes_hash.merge(options)
+      if block
+        use(&block)
+      else
+        self
+      end
+    end
+
+    # Set the seed value returned by ConsistentRandom#seed.
+    #
+    # param options [Integer, Hash<String, Integer>] the value to return for seed. If an Integer is given
+    #   then it will be used as the value for all calls to seed. If a Hash is given then the value
+    #   will only be returned for ConsitentRandom objects with the names specified in the keys.
+    # @yield block of code to execute with the test values.
+    # @return [ConsistentRandom::Testing, Object] If a block is specified, then the result
+    #   of the block is returned. Otherwise the testing object is returned so that you can
+    #   chain calls to set up more test
+    def seed(options, &block)
+      options = validate_seed(options)
+      unless options
+        raise ArgumentError.new("Argument must be an Integer or a Hash with Integer values")
+      end
+
+      @seed_hash = options.default ? options.merge(@seed_hash) : @seed_hash.merge(options)
+      if block
+        use(&block)
+      else
+        self
+      end
+    end
+
+    # Use the test values within a block of code.
+    #
+    # @yield block of code to execute with the test values.
+    # @return [Object] the result of the block
+    def use(&block)
+      save_val = Thread.current[:consistent_random_testing]
+      begin
+        Thread.current[:consistent_random_testing] = self
+        yield
+      ensure
+        Thread.current[:consistent_random_testing] = save_val
+      end
+    end
+
+    # Get the test value for rand.
+    #
+    # @param name [String] the name of the ConsistentRandom object
+    # @return [Float, nil] the test value for rand if there is a test value for the name
+    # @api private
+    def rand_for(name)
+      @rand_hash[name]
+    end
+
+    # Get the test value for bytes.
+    #
+    # @param name [String] the name of the ConsistentRandom object
+    # @return [String, nil] the test value for bytes if there is a test value for the name
+    # @api private
+    def bytes_for(name)
+      @bytes_hash[name]
+    end
+
+    # Get the test value for seed.
+    #
+    # @param name [String] the name of the ConsistentRandom object
+    # @return [Integer, nil] the test value for seed if there is a test value for the name
+    # @api private
+    def seed_for(name)
+      @seed_hash[name]
+    end
+
+    private
+
+    def validate_rand(options)
+      if options.is_a?(Hash) && options.values.all? { |value| value.is_a?(Float) && (0...1).cover?(value) }
+        options.each_with_object({}) { |(key, value), hash| hash[key.to_s] = value }
+      elsif options.is_a?(Float) && (0...1).cover?(options)
+        Hash.new(options)
+      end
+    end
+
+    def validate_bytes(options)
+      if options.is_a?(Hash) && options.values.all? { |value| value.is_a?(String) }
+        options.each_with_object({}) { |(key, value), hash| hash[key.to_s] = value.encode(Encoding::ASCII_8BIT) }
+      elsif options.is_a?(String)
+        Hash.new(options)
+      end
+    end
+
+    def validate_seed(options)
+      if options.is_a?(Hash) && options.values.all? { |value| value.is_a?(Integer) }
+        options.each_with_object({}) { |(key, value), hash| hash[key.to_s] = value }
+      elsif options.is_a?(Integer)
+        Hash.new(options)
+      end
+    end
+  end
+end

data/lib/consistent_random.rb

@@ -51,11 +51,17 @@ class ConsistentRandom
     def current_seed
       Thread.current[:consistent_random_seed]
     end
+
+    def testing
+      Testing.new
+    end
   end
 
+  attr_reader :name
+
   # @param name [Object] a name used to identifuy a consistent random value
   def initialize(name)
-    @name = name
+    @name = (name.is_a?(String) ? name.dup : name.to_s).freeze
   end
 
   # Generate a random number. The same number will be generated within a scope block.
@@ -68,7 +74,7 @@ class ConsistentRandom
   #   a number in that range. If max is an number, then it will be an integer between 0 and that
   #   value. Otherwise, it will be a float between 0 and 1.
   def rand(max = nil)
-    value = seed / SEED_DIVISOR
+    value = Testing.current&.rand_for(name) || seed / SEED_DIVISOR
     case max
     when nil
       value
@@ -85,8 +91,14 @@ class ConsistentRandom
   # @param size [Integer] the number of bytes to generate.
   # @return [String] a string of random bytes.
   def bytes(size)
+    test_bytes = Testing.current&.bytes_for(name)
+    test_bytes = nil if test_bytes&.empty?
+    chunk_size = (test_bytes ? test_bytes.length : 20)
+
     bytes = []
-    ((size + 19) / 20).times { |i| bytes << seed_hash("#{@name}#{i}").to_s }
+    (size / chunk_size.to_f).ceil.times do |i|
+      bytes << (test_bytes || seed_hash("#{name}#{i}").to_s)
+    end
     bytes.join[0, size]
   end
 
@@ -95,13 +107,17 @@ class ConsistentRandom
   #
   # @return [Integer] a 64 bit integer for seeding random values
   def seed
-    hash = seed_hash(@name)
+    test_seed = Testing.current&.seed_for(name)
+    return test_seed if test_seed
+
+    hash = seed_hash(name)
     hash.byteslice(0, 8).unpack1("Q>")
   end
 
   # @return [Boolean] true if the other object is a ConsistentRandom that returns
   #   the same random number generator. If called outside of a scope, then it will
-  #   always return false.
+  #   always return false. The functionality is designed to be similar to the
+  #   same behavior as Random.
   def ==(other)
     other.is_a?(self.class) && other.seed == seed
   end
@@ -138,3 +154,5 @@ class ConsistentRandom
     int_range ? val.to_i : val
   end
 end
+
+require_relative "consistent_random/testing"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: consistent_random
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Brian Durand
@@ -41,6 +41,7 @@ files:
 - lib/consistent_random/rack_middleware.rb
 - lib/consistent_random/sidekiq_client_middleware.rb
 - lib/consistent_random/sidekiq_middleware.rb
+- lib/consistent_random/testing.rb
 homepage: https://github.com/bdurand/consistent_random
 licenses:
 - MIT