prop_check 0.14.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd78cbcc636fbb2089c175708a6be52ebb8124b1f21758ee513f8a84fce33f97
-  data.tar.gz: d3bc244740e31fda8d3dbcdcafc3b7f2bd43676c13f945413bae852fbd82de6f
+  metadata.gz: c6d76933200bf114634aaa2d53f4c0832d6c362a2051e12d760d59a8ccae14e7
+  data.tar.gz: 452bcebdfb1b5c0113519840ce22aec73be64a5ab60c20dacd3a537eb860bb8e
 SHA512:
-  metadata.gz: eda47d7e95d30de4a4b12fe18063b4eb234d7e2bafa2c071613c12c882e71a777da288504330990edde061a8247db33bdb8a7a829419b2111912b7499cef9749
-  data.tar.gz: d44b56680e431af41f2df178795a576d25ccf42e0fb2af086398a18a8b39ccb39eb071acfd88323705346ce5fd528361d3e049509d924be44300a9951d1260e3
+  metadata.gz: aa86451cf41305a0c9cb511b39b210768365becd0494f83e285f8cb2b7b7abf667df87ed033fb1faf730037edc116747b75f9d0ab8efce834de6e3cf0b499d6a
+  data.tar.gz: 215c2f13f9523f93b550de01f48087385a6ae8892357248691e7556d80cea9b3fc06e7d1dd113a4d088fa4225c99247b8309614dab6ef8198c7dc96e635d7aba

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+- 0.15.0
+  - Features:
+    - Generators for `Date`, `Time` and `DateTime`.
+      - Basic work done by @Haniyya. Thank you very much!
+      - Extra functions to generate dates/times/datetimes in the future or the past.
+      - Allow overriding the epoch that is used.
+      - A new option in `PropCheck::Property::Configuration` to set the default epoch.
+    - Generator to generate `Set`s.
+    - New builtin float generators (positive, negative, nonzero, nonnegative, nonpositive). Both in 'normal' flavor and in 'real' flavor (that will never generate infinity or other special values).
+    - `PropCheck::Generator#with_config` which enables the possibility to inspect and act on the current `PropCheck::Property::Configuration` while generating values.
+  - Fixes:
+    - Preserve backwards compatibility with Ruby 2.5 by not using infinite ranges internally (c.f. #8, thank you, @hlaf!)
+    - Make a flaky test deterministic by fixing the RNG. (c.f. #9, thank you, @hlaf!)
+    - Fix a crash when using a hash where not all keys are symbols. (c.f. #7, thank you, @Haniyya!)
+    - Fix situations in which `PropCheck::Generators.array` would for certain config values never generate empty arrays.
 - 0.14.1 - Swap `awesome_print` for `amazing_print` which is a fork of the former that is actively maintained.
 - 0.14.0 - Adds `uniq: true` option to `Generators.array`. Makes `PropCheck::Property` an immutable object that returns copies that have changes whenever reconfiguring, allowing re-usable configuration.
 - 0.13.0 - Adds Generator#resize

data/README.md

@@ -9,16 +9,47 @@ PropCheck allows you to do Property Testing in Ruby.
 
 It features:
 
-- Generators for common datatypes.
-- An easy DSL to define your own generators (by combining existing ones, or completely custom).
+- Generators for most common Ruby datatypes.
+- An easy DSL to define your own generators (by combining existing ones, as well as completely custom ones).
 - Shrinking to a minimal counter-example on failure.
+- Hooks to perform extra set-up/cleanup logic before/after every example case.
 
+## What is PropCheck?
 
-## TODOs before stable release
+PropCheck is a Ruby library to create unit tests which are simpler to write and more powerful when run, finding edge-cases in your code you wouldn't have thought to look for.
 
-Before releasing this gem on Rubygems, the following things need to be finished:
+It works by letting you write tests that assert that something should be true for _every_ case, rather than just the ones you happen to think of.
 
-- [x]  Finalize the testing DSL.
+
+A normal unit test looks something like the following:
+
+1. Set up some data.
+2. Perform some operations on the data.
+3. Assert something about the result
+
+PropCheck lets you write tests which instead look like this:
+
+1. For all data matching some specification.
+2. Perform some operations on the data.
+3. Assert something about the result.
+
+This is often called property-based testing. It was popularised by the Haskell library [QuickCheck](https://hackage.haskell.org/package/QuickCheck). 
+PropCheck takes further inspiration from Erlang's [PropEr](https://hex.pm/packages/proper), Elixir's [StreamData](https://hex.pm/packages/stream_data) and Python's [Hypothesis](https://hypothesis.works/).
+
+It works by generating arbitrary data matching your specification and checking that your assertions still hold in that case. If it finds an example where they do not, it takes that example and shrinks it down, simplifying it to find the smallest example that still causes the problem.
+
+Writing these kinds of tests usually consists of deciding on guarantees that your code should have -- properties that should always hold true, regardless of wat the world throws at you. Some examples are:
+
+- Your code should not throw an exception, or only a particular type of exception.
+- If you remove an object, you can no longer see it
+- If you serialize and then deserializea value, you get the same value back.
+
+
+## Implemented and still missing features
+
+Before releasing v1.0, we want to finish the following:
+
+- [x] Finalize the testing DSL.
 - [x] Testing the library itself (against known 'true' axiomatically correct Ruby code.)
 - [x] Customization of common settings
  - [x] Filtering generators. 
@@ -28,15 +59,17 @@ Before releasing this gem on Rubygems, the following things need to be finished:
 - [x] Good, unicode-compliant, string generators.
 - [x] Filtering generator outputs.
 - [x] Before/after/around hooks to add setup/teardown logic to be called before/after/around each time a check is run with new data.
+- [x] Possibility to resize generators.
 - [x] `#instance` generator to allow the easy creation of generators for custom datatypes.
 - [ ] A usage guide.
+- [ ] A simple way to create recursive generators
+- [x] Builtin generation of `Set`s
+- [x] Builtin generation of `Date`s, `Time`s and `DateTime`s.
+- [ ] Configuration option to resize all generators given to a particular Property instance.
 
-# Nice-to-haves
+## Nice-to-haves
  
-- [x] Basic integration with RSpec. See also https://groups.google.com/forum/#!msg/rspec/U-LmL0OnO-Y/iW_Jcd6JBAAJ for progress on this.
- - [ ] `aggregate` , `resize` and similar generator-modifying calls (c.f. PropEr's variants of these) which will help with introspection/metrics.
- - [ ] Integration with other Ruby test frameworks.
- - Stateful property testing. If implemented at some point, will probably happen in a separate add-on library.
+- Stateful property testing. If implemented at some point, will probably happen in a separate add-on library.
 
 
 ## Installation
@@ -61,10 +94,8 @@ Or install it yourself as:
 ### Using PropCheck for basic testing
 
 Propcheck exposes the `forall` method.
-It takes generators as keyword arguments and a block to run.
-Inside the block, each of the names in the keyword-argument-list is available by its name.
-
-_(to be precise: a method on the execution context is defined which returns the current generated value for that name)_
+It takes any number of generators as arguments (or keyword arguments), as well as a block to run.
+The value(s) generated from the generator(s) passed to the `forall` will be given to the block as arguments.
 
 Raise an exception from the block if there is a problem. If there is no problem, just return normally.
 
@@ -257,3 +288,10 @@ Everyone interacting in the PropCheck project’s codebases, issue trackers, cha
 I want to thank the original creators of QuickCheck (Koen Claessen, John Hughes) as well as the authors of many great property testing libraries that I was/am able to use as inspiration.
 I also want to greatly thank Thomasz Kowal who made me excited about property based testing [with his great talk about stateful property testing](https://www.youtube.com/watch?v=q0wZzFUYCuM), 
 as well as Fred Herbert for his great book [Property-Based Testing with PropEr, Erlang and Elixir](https://propertesting.com/) which is really worth the read (regardless of what language you are using).
+
+The implementation and API of PropCheck takes a lot of inspiration from the following pre-existing libraries:
+
+- Haskell's [QuickCheck](https://hackage.haskell.org/package/QuickCheck) and [Hedgehog](https://hackage.haskell.org/package/hedgehog);
+- Erlang's [PropEr](https://hex.pm/packages/proper);
+- Elixir's [StreamData](https://hex.pm/packages/stream_data);
+- Python's [Hypothesis](https://hypothesis.works/).

data/lib/prop_check/generator.rb

@@ -11,7 +11,8 @@ module PropCheck
     @@default_size = 10
     @@default_rng = Random.new
     @@max_consecutive_attempts = 100
-    @@default_kwargs = {size: @@default_size, rng: @@default_rng, max_consecutive_attempts: @@max_consecutive_attempts}
+    @@default_kwargs = { size: @@default_size, rng: @@default_rng,
+                         max_consecutive_attempts: @@max_consecutive_attempts }
 
     ##
     # Being a special kind of Proc, a Generator wraps a block.
@@ -33,11 +34,11 @@ module PropCheck
         return res
       end
 
-      raise Errors::GeneratorExhaustedError, """
+      raise Errors::GeneratorExhaustedError, ''"
       Exhausted #{max_consecutive_attempts} consecutive generation attempts.
 
       Probably too few generator results were adhering to a `where` condition.
-      """
+      "''
     end
 
     ##
@@ -88,7 +89,7 @@ module PropCheck
       #   end.flatten
       # end
       Generator.new do |**kwargs|
-        outer_result = self.generate(**kwargs)
+        outer_result = generate(**kwargs)
         outer_result.bind do |outer_val|
           inner_generator = generator_proc.call(outer_val)
           inner_generator.generate(**kwargs)
@@ -103,15 +104,30 @@ module PropCheck
     #   => "S"
     def map(&proc)
       Generator.new do |**kwargs|
-        result = self.generate(**kwargs)
+        result = generate(**kwargs)
         result.map(&proc)
       end
     end
 
+    ##
+    # Turns a generator returning `x` into a generator returning `[x, config]`
+    # where `config` is the current `PropCheck::Property::Configuration`.
+    # This can be used to inspect the configuration inside a `#map` or `#where`
+    # and act on it.
+    #
+    #  >> Generators.choose(0..100).with_config.map { |int, conf| Date.jd(conf[:default_epoch].jd + int) }.call(size: 10, rng: Random.new(42), config: PropCheck::Property::Configuration.new)
+    #  => Date.new(2023, 01, 10)
+    def with_config
+      Generator.new do |**kwargs|
+        result = generate(**kwargs)
+        result.map { |val| [val, kwargs[:config]] }
+      end
+    end
+
     ##
     # Creates a new Generator that only produces a value when the block `condition` returns a truthy value.
     def where(&condition)
-      self.map do |result|
+      map do |result|
         # if condition.call(*result)
         if PropCheck::Helper.call_splatted(result, &condition)
           result
@@ -131,7 +147,7 @@ module PropCheck
     def resize(&proc)
       Generator.new do |size:, **other_kwargs|
         new_size = proc.call(size)
-        self.generate(**other_kwargs, size: new_size)
+        generate(**other_kwargs, size: new_size)
       end
     end
   end

data/lib/prop_check/generators.rb

@@ -1,6 +1,6 @@
-# coding: utf-8
 # frozen_string_literal: true
 
+require 'date'
 require 'prop_check/generator'
 require 'prop_check/lazy_tree'
 module PropCheck
@@ -136,7 +136,8 @@ module PropCheck
     # that is: no infinity, no NaN,
     # no numbers testing the limits of floating-point arithmetic.
     #
-    # Shrinks to numbers closer to zero.
+    # Shrinks towards zero.
+    # The shrinking strategy also moves towards 'simpler' floats (like `1.0`) from 'complicated' floats (like `3.76543`).
     #
     #    >> Generators.real_float().sample(10, size: 10, rng: Random.new(42))
     #    => [-2.2, -0.2727272727272727, 4.0, 1.25, -3.7272727272727275, -8.833333333333334, -8.090909090909092, 1.1428571428571428, 0.0, 8.0]
@@ -146,20 +147,130 @@ module PropCheck
       end
     end
 
-    @@special_floats = [Float::NAN, Float::INFINITY, -Float::INFINITY, Float::MAX, Float::MIN, 0.0.next_float, 0.0.prev_float]
+    ##
+    # Generates any real floating-point numbers,
+    # but will never generate zero.
+    # c.f. #real_float
+    #
+    #    >> Generators.real_nonzero_float().sample(10, size: 10, rng: Random.new(43))
+    #    => [-7.25, 7.125, -7.636363636363637, -3.0, -8.444444444444445, -6.857142857142857, 2.4545454545454546, 3.0, -7.454545454545455, -6.25]
+    def real_nonzero_float
+      real_float.where { |val| val != 0.0 }
+    end
+
+    ##
+    # Generates real floating-point numbers which are never negative.
+    # Shrinks towards 0
+    # c.f. #real_float
+    #
+    #    >> Generators.real_nonnegative_float().sample(10, size: 10, rng: Random.new(43))
+    #    => [7.25, 7.125, 7.636363636363637, 3.0, 8.444444444444445, 0.0, 6.857142857142857, 2.4545454545454546, 3.0, 7.454545454545455]
+    def real_nonnegative_float
+      real_float.map(&:abs)
+    end
+
+    ##
+    # Generates real floating-point numbers which are never positive.
+    # Shrinks towards 0
+    # c.f. #real_float
+    #
+    #    >> Generators.real_nonpositive_float().sample(10, size: 10, rng: Random.new(44))
+    #    => [-9.125, -2.3636363636363638, -8.833333333333334, -1.75, -8.4, -2.4, -3.5714285714285716, -1.0, -6.111111111111111, -4.0]
+    def real_nonpositive_float
+      real_nonnegative_float.map(&:-@)
+    end
+
+    ##
+    # Generates real floating-point numbers which are always positive
+    # Shrinks towards Float::MIN
+    #
+    # Does not consider denormals.
+    # c.f. #real_float
+    #
+    #    >> Generators.real_positive_float().sample(10, size: 10, rng: Random.new(42))
+    #    => [2.2, 0.2727272727272727, 4.0, 1.25, 3.7272727272727275, 8.833333333333334, 8.090909090909092, 1.1428571428571428, 2.2250738585072014e-308, 8.0]
+    def real_positive_float
+      real_nonnegative_float.map { |val| val + Float::MIN }
+    end
+
+    ##
+    # Generates real floating-point numbers which are always negative
+    # Shrinks towards -Float::MIN
+    #
+    # Does not consider denormals.
+    # c.f. #real_float
+    #
+    #    >> Generators.real_negative_float().sample(10, size: 10, rng: Random.new(42))
+    #    => [-2.2, -0.2727272727272727, -4.0, -1.25, -3.7272727272727275, -8.833333333333334, -8.090909090909092, -1.1428571428571428, -2.2250738585072014e-308, -8.0]
+    def real_negative_float
+      real_positive_float.map(&:-@)
+    end
+
+    @@special_floats = [Float::NAN,
+                        Float::INFINITY,
+                        -Float::INFINITY,
+                        Float::MAX,
+                        -Float::MAX,
+                        Float::MIN,
+                        -Float::MIN,
+                        Float::EPSILON,
+                        -Float::EPSILON,
+                        0.0.next_float,
+                        0.0.prev_float]
     ##
     # Generates floating-point numbers
     # Will generate NaN, Infinity, -Infinity,
     # as well as Float::EPSILON, Float::MAX, Float::MIN,
     # 0.0.next_float, 0.0.prev_float,
     # to test the handling of floating-point edge cases.
-    # Approx. 1/100 generated numbers is a special one.
+    # Approx. 1/50 generated numbers is a special one.
     #
     # Shrinks to smaller, real floats.
     #    >> Generators.float().sample(10, size: 10, rng: Random.new(42))
-    #    => [4.0, 9.555555555555555, 0.0, -Float::INFINITY, 5.5, -5.818181818181818, 1.1428571428571428, 0.0, 8.0, 7.857142857142858]
+    #    >>  Generators.float().sample(10, size: 10, rng: Random.new(4))
+    #    => [-8.0, 2.0, 2.7142857142857144, -4.0, -10.2, -6.666666666666667, -Float::INFINITY, -10.2, 2.1818181818181817, -6.2]
     def float
-      frequency(99 => real_float, 1 => one_of(*@@special_floats.map(&method(:constant))))
+      frequency(49 => real_float, 1 => one_of(*@@special_floats.map(&method(:constant))))
+    end
+
+    ##
+    # Generates any nonzerno floating-point number.
+    # Will generate special floats (except NaN) from time to time.
+    # c.f. #float
+    def nonzero_float
+      float.where { |val| val != 0.0 && val }
+    end
+
+    ##
+    # Generates nonnegative floating point numbers
+    # Will generate special floats (except NaN) from time to time.
+    # c.f. #float
+    def nonnegative_float
+      float.map(&:abs).where { |val| val != Float::NAN }
+    end
+
+    ##
+    # Generates nonpositive floating point numbers
+    # Will generate special floats (except NaN) from time to time.
+    # c.f. #float
+    def nonpositive_float
+      nonnegative_float.map(&:-@)
+    end
+
+    ##
+    # Generates positive floating point numbers
+    # Will generate special floats (except NaN) from time to time.
+    # c.f. #float
+    def positive_float
+      nonnegative_float.where { |val| val != 0.0 && val }
+    end
+
+    ##
+    # Generates positive floating point numbers
+    # Will generate special floats (except NaN) from time to time.
+    # c.f. #float
+    def negative_float
+      positive_float.map(&:-@).where { |val| val != 0.0 }
     end
 
     ##
@@ -269,7 +380,7 @@ module PropCheck
       if max.nil?
         nonnegative_integer.bind { |count| make_array(element_generator, min, count, uniq) }
       else
-        make_array(element_generator, min, max, uniq)
+        choose(min..max).bind { |count| make_array(element_generator, min, count, uniq) }
       end
     end
 
@@ -298,31 +409,57 @@ module PropCheck
         arr = []
         uniques = Set.new
         count = 0
-        (0..).lazy.map do
-          elem = element_generator.clone.generate(**kwargs)
-          if uniques.add?(uniq_fun.call(elem.root))
-            arr.push(elem)
-            count = 0
-          else
-            count += 1
-          end
 
-          if count > kwargs[:max_consecutive_attempts]
-            if arr.size >= min
-              # Give up and return shorter array in this case
-              amount = min
+        if amount == 0
+          LazyTree.new([])
+        else
+          0.step.lazy.map do
+            elem = element_generator.clone.generate(**kwargs)
+            if uniques.add?(uniq_fun.call(elem.root))
+              arr.push(elem)
+              count = 0
             else
-              raise Errors::GeneratorExhaustedError, "Too many consecutive elements filtered by 'uniq:'."
+              count += 1
+            end
+
+            if count > kwargs[:max_consecutive_attempts]
+              if arr.size >= min
+                # Give up and return shorter array in this case
+                amount = min
+              else
+                raise Errors::GeneratorExhaustedError, "Too many consecutive elements filtered by 'uniq:'."
+              end
             end
           end
-        end
-        .take_while { arr.size < amount }
-        .force
+           .take_while { arr.size < amount }
+           .force
 
-        LazyTree.zip(arr).map { |array| array.uniq(&uniq_fun) }
+          LazyTree.zip(arr).map { |array| array.uniq(&uniq_fun) }
+        end
       end
     end
 
+    ##
+    # Generates a set of elements, where each of the elements
+    # is generated by `element_generator`.
+    #
+    # Shrinks to smaller sets (with shrunken elements).
+    # Accepted keyword arguments:
+    #
+    # `empty:` When false, behaves the same as `min: 1`
+    # `min:` Ensures at least this many elements are generated. (default: 0)
+    # `max:` Ensures at most this many elements are generated. When nil, an arbitrary count is used instead. (default: nil)
+    #
+    # In the set, elements are always unique.
+    # If it is not possible to generate another unique value after the configured `max_consecutive_attempts`
+    # a `PropCheck::Errors::GeneratorExhaustedError` will be raised.
+    #
+    #    >> Generators.set(Generators.positive_integer).sample(5, size: 4, rng: Random.new(42))
+    #    => [Set[2, 4], Set[], Set[3, 4], Set[], Set[4]]
+    def set(element_generator, min: 0, max: nil, empty: true)
+      array(element_generator, min: min, max: max, empty: empty, uniq: true).map(&:to_set)
+    end
+
     ##
     # Generates a hash of key->values,
     # where each of the keys is made using the `key_generator`
@@ -559,8 +696,8 @@ module PropCheck
     #
     # Shrinks towards simpler terms, like `true`, an empty array, a single character or an integer.
     #
-    #    >> Generators.truthy.sample(5, size: 10, rng: Random.new(42))
-    #    => [[4, 0, -3, 10, -4, 8, 0, 0, 10], -3, [5.5, -5.818181818181818, 1.1428571428571428, 0.0, 8.0, 7.857142857142858, -0.6666666666666665, 5.25], [], ["\u{9E553}\u{DD56E}\u{A5BBB}\u{8BDAB}\u{3E9FC}\u{C4307}\u{DAFAE}\u{1A022}\u{938CD}\u{70631}", "\u{C4C01}\u{32D85}\u{425DC}"]]
+    #    >> Generators.truthy.sample(5, size: 2, rng: Random.new(42))
+    #    => [[2], {:gz=>0, :""=>0}, [1.0, 0.5], 0.6666666666666667, {"𦐺\u{9FDDB}"=>1, ""=>1}]
     def truthy
       one_of(constant(true),
              constant([]),
@@ -574,8 +711,7 @@ module PropCheck
              array(string),
              hash(simple_symbol, integer),
              hash(string, integer),
-             hash(string, string)
-            )
+             hash(string, string))
     end
 
     ##
@@ -588,6 +724,117 @@ module PropCheck
       frequency(9 => other_generator, 1 => constant(nil))
     end
 
+    ##
+    # Generates `Date` objects.
+    # DateTimes start around the given `epoch:`  and deviate more when `size` increases.
+    # when no epoch is set, `PropCheck::Property::Configuration.default_epoch` is used, which defaults to `DateTime.now.to_date`.
+    #
+    #   >> Generators.date(epoch: Date.new(2022, 01, 01)).sample(2, rng: Random.new(42))
+    #   => [Date.new(2021, 12, 28), Date.new(2022, 01, 10)]
+    def date(epoch: nil)
+      date_from_offset(integer, epoch: epoch)
+    end
+
+    ##
+    # variant of #date that only generates dates in the future (relative to `:epoch`).
+    #
+    #   >> Generators.future_date(epoch: Date.new(2022, 01, 01)).sample(2, rng: Random.new(42))
+    #   => [Date.new(2022, 01, 06), Date.new(2022, 01, 11)]
+    def future_date(epoch: Date.today)
+      date_from_offset(positive_integer, epoch: epoch)
+    end
+
+    ##
+    # variant of #date that only generates dates in the past (relative to `:epoch`).
+    #
+    #   >> Generators.past_date(epoch: Date.new(2022, 01, 01)).sample(2, rng: Random.new(42))
+    #   => [Date.new(2021, 12, 27), Date.new(2021, 12, 22)]
+    def past_date(epoch: Date.today)
+      date_from_offset(negative_integer, epoch: epoch)
+    end
+
+    private def date_from_offset(offset_gen, epoch:)
+      if epoch
+        offset_gen.map { |offset| Date.jd(epoch.jd + offset) }
+      else
+        offset_gen.with_config.map do |offset, config|
+          puts config.inspect
+          epoch = config.default_epoch.to_date
+          Date.jd(epoch.jd + offset)
+        end
+      end
+    end
+
+    ##
+    # Generates `DateTime` objects.
+    # DateTimes start around the given `epoch:`  and deviate more when `size` increases.
+    # when no epoch is set, `PropCheck::Property::Configuration.default_epoch` is used, which defaults to `DateTime.now`.
+    #
+    #   >> PropCheck::Generators.datetime.sample(2, rng: Random.new(42), config: PropCheck::Property::Configuration.new)
+    #   => [DateTime.parse("2022-11-17 07:11:59.999983907 +0000"), DateTime.parse("2022-11-19 05:27:16.363618076 +0000")]
+    def datetime(epoch: nil)
+      datetime_from_offset(real_float, epoch: epoch)
+    end
+
+    ##
+    # alias for `#datetime`, for backwards compatibility.
+    # Prefer using `datetime`!
+    def date_time(epoch: nil)
+      datetime(epoch: epoch)
+    end
+
+    ##
+    # Variant of `#datetime` that only generates datetimes in the future (relative to `:epoch`).
+    #
+    #   >> PropCheck::Generators.future_datetime.sample(2, rng: Random.new(42), config: PropCheck::Property::Configuration.new).map(&:inspect)
+    #   => ["#<DateTime: 2022-11-21T16:48:00+00:00 ((2459905j,60480s,16093n),+0s,2299161j)>", "#<DateTime: 2022-11-19T18:32:43+00:00 ((2459903j,66763s,636381924n),+0s,2299161j)>"]
+    def future_datetime(epoch: nil)
+      datetime_from_offset(real_positive_float, epoch: epoch)
+    end
+
+    ##
+    # Variant of `#datetime` that only generates datetimes in the past (relative to `:epoch`).
+    #
+    #   >> PropCheck::Generators.past_datetime.sample(2, rng: Random.new(42), config: PropCheck::Property::Configuration.new)
+    #   => [DateTime.parse("2022-11-17 07:11:59.999983907 +0000"), DateTime.parse("2022-11-19 05:27:16.363618076 +0000")]
+    def past_datetime(epoch: nil)
+      datetime_from_offset(real_negative_float, epoch: epoch)
+    end
+
+    ##
+    # Generates `Time` objects.
+    # Times start around the given `epoch:`  and deviate more when `size` increases.
+    # when no epoch is set, `PropCheck::Property::Configuration.default_epoch` is used, which defaults to `DateTime.now`.
+    #
+    #   >> PropCheck::Generators.time.sample(2, rng: Random.new(42), config: PropCheck::Property::Configuration.new)
+    #   => [DateTime.parse("2022-11-17 07:11:59.999983907 +0000").to_time, DateTime.parse("2022-11-19 05:27:16.363618076 +0000").to_time]
+    def time(epoch: nil)
+      datetime(epoch: epoch).map(&:to_time)
+    end
+
+    ##
+    # Variant of `#time` that only generates datetimes in the future (relative to `:epoch`).
+    def future_time(epoch: nil)
+      future_datetime(epoch: epoch).map(&:to_time)
+    end
+
+    ##
+    # Variant of `#time` that only generates datetimes in the past (relative to `:epoch`).
+    def past_time(epoch: nil)
+      past_datetime(epoch: epoch).map(&:to_time)
+    end
+
+    private def datetime_from_offset(offset_gen, epoch:)
+      if epoch
+        offset_gen.map { |offset| DateTime.jd(epoch.ajd + offset) }
+      else
+        offset_gen.with_config.map do |offset, config|
+          epoch = config.default_epoch.to_date
+          DateTime.jd(epoch.ajd + offset)
+        end
+      end
+    end
+
     ##
     # Generates an instance of `klass`
     # using `args` and/or `kwargs`

data/lib/prop_check/helper.rb

@@ -33,12 +33,9 @@ module PropCheck
     end
 
     def call_splatted(val, &block)
-      case val
-      when Hash
-        block.call(**val)
-      else
-        block.call(val)
-      end
+      return block.call(**val) if val.is_a?(Hash) && val.keys.all? { |k| k.is_a?(Symbol) }
+
+      block.call(val)
       # if kwval != {}
       #   block.call(**kwval)
       # else

data/lib/prop_check/property/configuration.rb

@@ -1,25 +1,45 @@
 module PropCheck
   class Property
+    ## Configure PropCheck
+    #
+    # Configurations can be set globally,
+    # but also overridden on a per-generator basis.
+    # c.f. PropCheck.configure, PropCheck.configuration and PropCheck::Property#with_config
+    #
+    # ## Available options
+    # - `verbose:` When true, shows detailed options of the data generation and shrinking process. (Default: false)
+    # - `n_runs:` The amount of iterations each `forall` is being run.
+    # - `max_generate_attempts:` The amount of times the library tries a generator in total
+    #    before raising `Errors::GeneratorExhaustedError`. c.f. `PropCheck::Generator#where`. (Default: 10_000)
+    # - `max_shrink_steps:` The amount of times shrinking is attempted. (Default: 10_000)
+    # - `max_consecutive_attempts:`
+    # - `max_consecutive_attempts:` The amount of times the library tries a filtered generator consecutively
+    #    again before raising `Errors::GeneratorExhaustedError`. c.f. `PropCheck::Generator#where`. (Default: 10_000)
+    # - `default_epoch:` The 'base' value to use for date/time generators like
+    #    `PropCheck::Generators#date` `PropCheck::Generators#future_date` `PropCheck::Generators#time`, etc.
+    #    (Default: `DateTime.now`)
     Configuration = Struct.new(
       :verbose,
       :n_runs,
       :max_generate_attempts,
       :max_shrink_steps,
       :max_consecutive_attempts,
-      keyword_init: true) do
-
+      :default_epoch,
+      keyword_init: true
+    ) do
       def initialize(
-            verbose: false,
-            n_runs: 100,
-            max_generate_attempts: 10_000,
-            max_shrink_steps: 10_000,
-            max_consecutive_attempts: 30
-          )
+        verbose: false,
+        n_runs: 100,
+        max_generate_attempts: 10_000,
+        max_shrink_steps: 10_000,
+        max_consecutive_attempts: 30,
+        default_epoch: DateTime.now
+      )
         super
       end
 
       def merge(other)
-        Configuration.new(**self.to_h.merge(other.to_h))
+        Configuration.new(**to_h.merge(other.to_h))
       end
     end
   end

data/lib/prop_check/property.rb

@@ -102,7 +102,7 @@ module PropCheck
     # you can immediately pass a block to this method.
     # (so `forall(a: Generators.integer).with_config(verbose: true) do ... end` is the same as `forall(a: Generators.integer).with_config(verbose: true).check do ... end`)
     def with_config(**config, &block)
-      duplicate = self.dup
+      duplicate = dup
       duplicate.instance_variable_set(:@config, @config.merge(config))
       duplicate.freeze
 
@@ -114,7 +114,7 @@ module PropCheck
     def with_bindings(*bindings, **kwbindings)
       raise ArgumentError, 'No bindings specified!' if bindings.empty? && kwbindings.empty?
 
-      duplicate = self.dup
+      duplicate = dup
       duplicate.instance_variable_set(:@gen, gen_from_bindings(bindings, kwbindings))
       duplicate.freeze
       duplicate
@@ -129,22 +129,24 @@ module PropCheck
     # you might encounter a GeneratorExhaustedError.
     # Only filter if you have few inputs to reject. Otherwise, improve your generators.
     def where(&condition)
-      raise ArgumentError, 'No generator bindings specified! #where should be called after `#forall` or `#with_bindings`.' unless @gen
+      unless @gen
+        raise ArgumentError,
+              'No generator bindings specified! #where should be called after `#forall` or `#with_bindings`.'
+      end
 
-      duplicate = self.dup
+      duplicate = dup
       duplicate.instance_variable_set(:@gen, @gen.where(&condition))
       duplicate.freeze
       duplicate
     end
 
-
     ##
     # Calls `hook` before each time a check is run with new data.
     #
     # This is useful to add setup logic
     # When called multiple times, earlier-added hooks will be called _before_ `hook` is called.
     def before(&hook)
-      duplicate = self.dup
+      duplicate = dup
       duplicate.instance_variable_set(:@hooks, @hooks.add_before(&hook))
       duplicate.freeze
       duplicate
@@ -156,7 +158,7 @@ module PropCheck
     # This is useful to add teardown logic
     # When called multiple times, earlier-added hooks will be called _after_ `hook` is called.
     def after(&hook)
-      duplicate = self.dup
+      duplicate = dup
       duplicate.instance_variable_set(:@hooks, @hooks.add_after(&hook))
       duplicate.freeze
       duplicate
@@ -176,7 +178,7 @@ module PropCheck
     # it is possible for the code after `yield` not to be called.
     # So make sure that cleanup logic is wrapped with the `ensure` keyword.
     def around(&hook)
-      duplicate = self.dup
+      duplicate = dup
       duplicate.instance_variable_set(:@hooks, @hooks.add_around(&hook))
       duplicate.freeze
       duplicate
@@ -223,15 +225,15 @@ c.f. https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-k
       raise_generator_exhausted!
     end
 
-    private def raise_generator_exhausted!()
-      raise Errors::GeneratorExhaustedError, """
+    private def raise_generator_exhausted!
+      raise Errors::GeneratorExhaustedError, ''"
         Could not perform `n_runs = #{@config.n_runs}` runs,
         (exhausted #{@config.max_generate_attempts} tries)
         because too few generator results were adhering to
         the `where` condition.
 
         Try refining your generators instead.
-        """
+        "''
     end
 
     private def check_attempt(generator_result, n_successful, &block)
@@ -246,7 +248,8 @@ c.f. https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-k
     # so we can shrink to find their cause.
     # don't worry: they all get reraised
     rescue Exception => e
-      output, shrunken_result, shrunken_exception, n_shrink_steps = show_problem_output(e, generator_result, n_successful, &block)
+      output, shrunken_result, shrunken_exception, n_shrink_steps = show_problem_output(e, generator_result,
+                                                                                        n_successful, &block)
       output_string = output.is_a?(StringIO) ? output.string : e.message
 
       e.define_singleton_method :prop_check_info do
@@ -264,7 +267,7 @@ c.f. https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-k
     end
 
     private def attempts_enum(binding_generator)
-        @hooks
+      @hooks
         .wrap_enum(raw_attempts_enum(binding_generator))
         .lazy
         .take(@config.n_runs)
@@ -275,7 +278,14 @@ c.f. https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-k
       size = 1
       (0...@config.max_generate_attempts)
         .lazy
-        .map { binding_generator.generate(size: size, rng: rng, max_consecutive_attempts: @config.max_consecutive_attempts) }
+        .map do
+        binding_generator.generate(
+          size: size,
+          rng: rng,
+          max_consecutive_attempts: @config.max_consecutive_attempts,
+          config: @config
+        )
+      end
         .map do |result|
           size += 1
 
@@ -287,7 +297,8 @@ c.f. https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-k
       output = @config.verbose ? STDOUT : StringIO.new
       output = PropCheck::Property::OutputFormatter.pre_output(output, n_successful, generator_results.root, problem)
       shrunken_result, shrunken_exception, n_shrink_steps = shrink(generator_results, output, &block)
-      output = PropCheck::Property::OutputFormatter.post_output(output, n_shrink_steps, shrunken_result, shrunken_exception)
+      output = PropCheck::Property::OutputFormatter.post_output(output, n_shrink_steps, shrunken_result,
+                                                                shrunken_exception)
 
       [output, shrunken_result, shrunken_exception, n_shrink_steps]
     end

data/lib/prop_check/version.rb

@@ -1,3 +1,3 @@
 module PropCheck
-  VERSION = '0.14.1'
+  VERSION = '0.15.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prop_check
 version: !ruby/object:Gem::Version
-  version: 0.14.1
+  version: 0.15.0
 platform: ruby
 authors:
 - Qqwy/Wiebe-Marten Wijnja
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-09 00:00:00.000000000 Z
+date: 2022-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amazing_print
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: PropCheck allows you to do property-based testing, including shrinking.