prop_check 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6d76933200bf114634aaa2d53f4c0832d6c362a2051e12d760d59a8ccae14e7
-  data.tar.gz: 452bcebdfb1b5c0113519840ce22aec73be64a5ab60c20dacd3a537eb860bb8e
+  metadata.gz: e59cf670bcc8cf9720d6278e984925c50e75ca65023459174f8b511d6421fb71
+  data.tar.gz: '088e0eb8d2d301bc3c03cc63bf68196969e8653cad37ff0b9d5d10f9b417a1ae'
 SHA512:
-  metadata.gz: aa86451cf41305a0c9cb511b39b210768365becd0494f83e285f8cb2b7b7abf667df87ed033fb1faf730037edc116747b75f9d0ab8efce834de6e3cf0b499d6a
-  data.tar.gz: 215c2f13f9523f93b550de01f48087385a6ae8892357248691e7556d80cea9b3fc06e7d1dd113a4d088fa4225c99247b8309614dab6ef8198c7dc96e635d7aba
+  metadata.gz: de5808bced970e0c474367bf125837ac0eefa4aa752acb31cd74e884fea858b98fb518e9fe15493c81f8238e5e0490f3cbc855eda3a9b687196ca7830daad0aa
+  data.tar.gz: 312957d1ab0f990985f43ae7e4b0793df583ff2d3d8bb95573c11fe3e4d9c5f964d91050fe9bafb98ceb92dd6790d2ffce04257b02b0c152d75d9b4772b7423a

data/.github/workflows/run_tests.yaml

@@ -0,0 +1,31 @@
+name: Ruby RSpec tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.5', '2.6', '2.7', '3.0']
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@0a29871fe2b0200a17a4497bae54fe5df0d973aa # v1.115.3
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+- 0.17.0
+  - Features:
+    - Recursive generation using `PropCheck::Generators.tree`.
+- 0.16.0
+  - Features:
+    - New option in `PropCheck::Property::Configuration` to resize all generators at once.
+    - Wrapper functions to modify this easily in `PropCheck::Property` called `#resize`, `#grow_fast`, `#grow_slowly`, `#grow_exponentially`, `#grow_quadratically`, `#grow_logarithmically`.
 - 0.15.0
   - Features:
     - Generators for `Date`, `Time` and `DateTime`.

data/README.md

@@ -3,9 +3,9 @@
 PropCheck allows you to do Property Testing in Ruby.
 
 [![Gem](https://img.shields.io/gem/v/prop_check.svg)](https://rubygems.org/gems/prop_check)
-[![Build Status](https://travis-ci.org/Qqwy/ruby-prop_check.svg?branch=master)](https://travis-ci.org/Qqwy/ruby-prop_check)
+[![Ruby RSpec tests build status](https://github.com/Qqwy/ruby-prop_check/actions/workflows/run_tests.yaml/badge.svg)](https://github.com/Qqwy/ruby-prop_check/actions/workflows/run_tests.yaml)
 [![Maintainability](https://api.codeclimate.com/v1/badges/71897f5e6193a5124a53/maintainability)](https://codeclimate.com/github/Qqwy/ruby-prop_check/maintainability)
-[![RubyDoc](https://img.shields.io/badge/%F0%9F%93%9ARubyDoc-documentation-informational.svg)](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck)
+[![RubyDoc](https://img.shields.io/badge/%F0%9F%93%9ARubyDoc-documentation-informational.svg)](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/)
 
 It features:
 
@@ -61,11 +61,11 @@ Before releasing v1.0, we want to finish the following:
 - [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.
+- [x] Configuration option to resize all generators given to a particular Property instance.
+- [x] A simple way to create recursive generators
+- [ ] A usage guide.
 
 ## Nice-to-haves
  
@@ -100,9 +100,9 @@ The value(s) generated from the generator(s) passed to the `forall` will be give
 Raise an exception from the block if there is a problem. If there is no problem, just return normally.
 
 ```ruby
-include PropCheck::Generators
+G = PropCheck::Generators
 # testing that Enumerable#sort sorts in ascending order
-PropCheck.forall(array(integer)) do |numbers|
+PropCheck.forall(G.array(G.integer)) do |numbers|
   sorted_numbers = numbers.sort
   
   # Check that no number is smaller than the previous number
@@ -124,8 +124,8 @@ end
 ```
 ```ruby
 # And then in a test case:
-include PropCheck::Generators
-PropCheck.forall(numbers: array(integer)) do |numbers:|
+G = PropCheck::Generators
+PropCheck.forall(numbers: G.array(G.integer)) do |numbers:|
   result = naive_average(numbers)
   unless result.is_a?(Integer) do
     raise "Expected the average to be an integer!"
@@ -135,10 +135,10 @@ end
 # Or if you e.g. are using RSpec:
 describe "#naive_average" do
   include PropCheck
-  include PropCheck::Generators
+  G = PropCheck::Generators
 
   it "returns an integer for any input" do
-    forall(numbers: array(integer)) do |numbers:|
+    forall(numbers: G.array(G.integer)) do |numbers:|
       result = naive_average(numbers)      
       expect(result).to be_a(Integer)
     end
@@ -208,11 +208,12 @@ It contains generators for:
 - (any, only real-valued) floats, 
 - (any, printable only, alphanumeric only, etc) strings and symbols
 - fixed-size arrays and hashes 
-- as well as varying-size arrays and hashes.
+- as well as varying-size arrays, hashes and sets.
+- dates, times, datetimes.
 - and many more!
 
-It is common to call `include PropCheck::Generators` in e.g. your testing-suite files to be able to use these.
-If you want to be more explicit (but somewhat more verbose) when calling these functions. feel free to e.g. create a module-alias (like `PG = PropCheck::Generators`) instead.
+It is common and recommended to set up a module alias by using `G = PropCheck::Generators` in e.g. your testing-suite files to be able to refer to all of them.
+_(Earlier versions of the library recommended including the module instead. But this will make it very simple to accidentally shadow a generator with a local variable named `float` or `array` and similar.)_
 
 ### Writing Custom Generators
 
@@ -228,33 +229,37 @@ Always returns the given value. No shrinking.
 
 Allows you to take the result of one generator and transform it into something else.
     
-    >> Generators.choose(32..128).map(&:chr).call(10, Random.new(42))
-    => "S"
+    >> G.choose(32..128).map(&:chr).sample(1, size: 10, Random.new(42))
+    => ["S"]
 
 #### Generator#bind
 
 Allows you to create one or another generator conditionally on the output of another generator.
 
-    >> Generators.integer.bind { |a| Generators.integer.bind { |b| Generator.wrap([a , b]) } }.call(100, Random.new(42))
-    => [2, 79]
+    >> G.integer.bind { |a| G.integer.bind { |b| G.constant([a , b]) } }.sample(1, size: 100, rng: Random.new(42)
+    => [[2, 79]]
+
+This is an advanced feature. Often, you can use a combination of `Generators.tuple` and `Generator#map` instead:
 
+    >> G.tuple(integer, integer).sample(1, size: 100, rng: Random.new(42)
+    => [[2, 79]]
 
 #### Generators.one_of
 
 Useful if you want to be able to generate a value to be one of multiple possibilities:
 
     
-    >> Generators.one_of(Generators.constant(true), Generators.constant(false)).sample(5, size: 10, rng: Random.new(42))
+    >> G.one_of(G.constant(true), G.constant(false)).sample(5, size: 10, rng: Random.new(42))
     => [true, false, true, true, true]
 
-(note that for this example, you can also use `Generators.boolean`. The example happens to show how it is implemented under the hood.)
+(Note that for this example, you can also use `G.boolean`. The example happens to show how it is implemented under the hood.)
 
 #### Generators.frequency
 
 If `one_of` does not give you enough flexibility because you want some results to be more common than others,
 you can use `Generators.frequency` which takes a hash of (integer_frequency => generator) keypairs.
 
-    >> Generators.frequency(5 => Generators.integer, 1 => Generators.printable_ascii_char).sample(size: 10, rng: Random.new(42))
+    >> G.frequency(5 => G.integer, 1 => G.printable_ascii_char).sample(size: 10, rng: Random.new(42))
     => [4, -3, 10, 8, 0, -7, 10, 1, "E", 10]
 
 #### Others

data/lib/prop_check/generators.rb

@@ -758,7 +758,6 @@ module PropCheck
         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
@@ -873,5 +872,75 @@ module PropCheck
         end
       end
     end
+
+    ##
+    # Helper to build recursive generators
+    #
+    # Given a `leaf_generator`
+    # and a block which:
+    #  - is given a generator that generates subtrees.
+    #  - it should return the generator for intermediate tree nodes.
+    #
+    # This is best explained with an example.
+    # Say we want to generate a binary tree of integers.
+    #
+    # If we have a struct representing internal nodes:
+    #  ```ruby
+    #  Branch = Struct.new(:left, :right, keyword_init: true)
+    #  ```
+    #  we can generate trees like so:
+    #  ```ruby
+    #  Generators.tree(Generators.integer) do |subtree_gen|
+    #    G.instance(Branch, left: subtree_gen, right: subtree_gen)
+    #  end
+    #  ```
+    #
+    # As another example, consider generating lists of integers:
+    #
+    #     >> G = PropCheck::Generators
+    #     >> G.tree(G.integer) {|child_gen| G.array(child_gen) }.sample(5, size: 37, rng: Random.new(42))
+    #     => [[7, [2, 3], -10], [[-2], [-2, [3]], [[2, 3]]], [], [0, [-2, -3]], [[1], -19, [], [1, -1], [1], [-1, -1], [1]]]
+    #
+    # And finally, here is how one could create a simple generator for parsed JSON data:
+    #
+    # ```ruby`
+    #  G = PropCheck::Generators
+    #  def json
+    #    G.tree(G.one_of(G.boolean, G.real_float, G.ascii_string)) do |json_gen|
+    #      G.one_of(G.array(json_gen), G.hash_of(G.ascii_string, json_gen))
+    #    end
+    #  end
+    # ```
+    #
+    def tree(leaf_generator, &block)
+      # Implementation is based on
+      # https://hexdocs.pm/stream_data/StreamData.html#tree/2
+      Generator.new do |size:, rng:, **other_kwargs|
+        nodes_on_each_level = random_pseudofactors(size.pow(1.1).to_i, rng)
+        result = nodes_on_each_level.reduce(leaf_generator) do |subtree_generator, nodes_on_this_level|
+          frequency(1 => subtree_generator,
+                    2 => block.call(subtree_generator).resize { |_size| nodes_on_this_level })
+        end
+
+        result.generate(size: size, rng: rng, **other_kwargs)
+      end
+    end
+
+    private def random_pseudofactors(size, rng)
+      return [size].to_enum if size < 2
+
+      Enumerator.new do |yielder|
+        loop do
+          factor = rng.rand(1..(Math.log2(size).to_i))
+          if factor == 1
+            yielder << size
+            break
+          else
+            yielder << factor
+            size /= factor
+          end
+        end
+      end
+    end
   end
 end

data/lib/prop_check/helper.rb

@@ -36,11 +36,6 @@ module PropCheck
       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
-      #   block.call(*val)
-      # end
     end
   end
 end

data/lib/prop_check/property/configuration.rb

@@ -18,6 +18,9 @@ module PropCheck
     # - `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`)
+    # - `resize_function` A proc that can be used to resize _all_ generators.
+    #    Takes the current size as integer and should return a new integer.
+    #   (Default: `proc { |size| size }`)
     Configuration = Struct.new(
       :verbose,
       :n_runs,
@@ -25,6 +28,7 @@ module PropCheck
       :max_shrink_steps,
       :max_consecutive_attempts,
       :default_epoch,
+      :resize_function,
       keyword_init: true
     ) do
       def initialize(
@@ -33,7 +37,8 @@ module PropCheck
         max_generate_attempts: 10_000,
         max_shrink_steps: 10_000,
         max_consecutive_attempts: 30,
-        default_epoch: DateTime.now
+        default_epoch: DateTime.now,
+        resize_function: proc { |size| size }
       )
         super
       end

data/lib/prop_check/property.rb

@@ -111,6 +111,67 @@ module PropCheck
       duplicate
     end
 
+    ##
+    # Resizes all generators in this property with the given function.
+    #
+    # Shorthand for manually wrapping `PropCheck::Property::Configuration.resize_function` with the new function.
+    def resize(&block)
+      raise '#resize called without a block' unless block_given?
+
+      orig_fun = @config.resize_function
+      with_config(resize_function: block)
+    end
+
+    ##
+    # Resizes all generators in this property. The new size is `2.pow(orig_size)`
+    #
+    # c.f. #resize
+    def growing_exponentially(&block)
+      orig_fun = @config.resize_function
+      fun = proc { |size| 2.pow(orig_fun.call(size)) }
+      with_config(resize_function: fun, &block)
+    end
+
+    ##
+    # Resizes all generators in this property. The new size is `orig_size * orig_size`
+    #
+    # c.f. #resize
+    def growing_quadratically(&block)
+      orig_fun = @config.resize_function
+      fun = proc { |size| orig_fun.call(size).pow(2) }
+      with_config(resize_function: fun, &block)
+    end
+
+    ##
+    # Resizes all generators in this property. The new size is `2 * orig_size`
+    #
+    # c.f. #resize
+    def growing_fast(&block)
+      orig_fun = @config.resize_function
+      fun = proc { |size| orig_fun.call(size) * 2 }
+      with_config(resize_function: fun, &block)
+    end
+
+    ##
+    # Resizes all generators in this property. The new size is `0.5 * orig_size`
+    #
+    # c.f. #resize
+    def growing_slowly(&block)
+      orig_fun = @config.resize_function
+      fun = proc { |size| orig_fun.call(size) * 0.5 }
+      with_config(resize_function: fun, &block)
+    end
+
+    ##
+    # Resizes all generators in this property. The new size is `Math.log2(orig_size)`
+    #
+    # c.f. #resize
+    def growing_logarithmically(&block)
+      orig_fun = @config.resize_function
+      fun = proc { |size| Math.log2(orig_fun.call(size)) }
+      with_config(resize_function: fun, &block)
+    end
+
     def with_bindings(*bindings, **kwbindings)
       raise ArgumentError, 'No bindings specified!' if bindings.empty? && kwbindings.empty?
 
@@ -279,8 +340,9 @@ c.f. https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-k
       (0...@config.max_generate_attempts)
         .lazy
         .map do
+        generator_size = @config.resize_function.call(size).to_i
         binding_generator.generate(
-          size: size,
+          size: generator_size,
           rng: rng,
           max_consecutive_attempts: @config.max_consecutive_attempts,
           config: @config

data/lib/prop_check/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prop_check
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Qqwy/Wiebe-Marten Wijnja
@@ -35,11 +35,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/run_tests.yaml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".tool-versions"
-- ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -53,7 +53,6 @@ files:
 - lib/prop_check/generator.rb
 - lib/prop_check/generators.rb
 - lib/prop_check/helper.rb
-- lib/prop_check/helper/lazy_append.rb
 - lib/prop_check/hooks.rb
 - lib/prop_check/lazy_tree.rb
 - lib/prop_check/property.rb
@@ -84,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: PropCheck allows you to do property-based testing, including shrinking.

data/.travis.yml

@@ -1,18 +0,0 @@
----
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-  - 2.6.5
-before_install: gem install bundler -v 2.0.2
-env:
-  global:
-    - CC_TEST_REPORTER_ID=9d18f5b43e49eecd6c3da64d85ea9c765d3606c129289d7c8cadf6d448713311
-before_script:
-  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-  - chmod +x ./cc-test-reporter
-  - ./cc-test-reporter before-build
-script:
-  - bundle exec rspec
-after_script:
-  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/lib/prop_check/helper/lazy_append.rb

@@ -1,18 +0,0 @@
-# module PropCheck
-#   module Helper
-#     ##
-#     # A refinement for enumerators
-#     # to allow lazy appending of two (potentially lazy) enumerators:
-#     #   >> [1,2,3].lazy_append([4,5.6]).to_a
-#     #   => [1,2,3,4,5,6]
-#     module LazyAppend
-#       refine Enumerable do
-#         ##   >> [1,2,3].lazy_append([4,5.6]).to_a
-#         ##   => [1,2,3,4,5,6]
-#         def lazy_append(other_enumerator)
-#           [self, other_enumerator].lazy.flat_map(&:lazy)
-#         end
-#       end
-#     end
-#   end
-# end