prop_check 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97011ef3b26afe799c5490e6de90bd9be9b0a97b1a028d2226dee5e333db692d
-  data.tar.gz: 36c5308c6da7a232c407fb8034528cabb21ba3f9c5a19076bc7265eea98d9b35
+  metadata.gz: 71879bc6575991fe6582a3f98213ee01fb5c9230cf042f95769eea801c366b1f
+  data.tar.gz: 9e351641ffb936461634a871cb984efff16c3ff5e9de0e60d411d33385786ec4
 SHA512:
-  metadata.gz: ac484a895221b1d8e7ab5a64c1282641526a310206e0ca5de46610b4d9fc02cf693c8af77a32ad026f610947f20609f3a09ea5833f7d97822dd958da536005c9
-  data.tar.gz: 367b87d861eb5fcd36dc4ffb0698bad05c6a3805595cf4e1508e276e755241dc415ff5e6f080121608200a4f8766e7ad0992c610a4af963193e4644e62c2b625
+  metadata.gz: 704ee74432f653b9993312d965ba1605ab366f67d564061a82522d8ac647b21689f47abdc836483dd82ffa4e3810882e33cccbd47c37e22cf8013d82147c2a20
+  data.tar.gz: 12535b39f7ff460bba0fb26bb3156f819e8d96ccf2ed7e2da28b6ab63472af3f42341a2c92e8fe437d5dccb56ce77ee7969e036c7484c833655ad5108e7fd3d9

data/CHANGELOG.md

@@ -0,0 +1 @@
+- 0.8.0 New syntax that is more explicit, passng generated values to blocks as parameters.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    prop_check (0.7.0)
+    prop_check (0.7.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -14,7 +14,7 @@ It features:
 - Shrinking to a minimal counter-example on failure.
 
 
-## TODOs before release
+## TODOs before stable release
 
 Before releasing this gem on Rubygems, the following things need to be finished:
 
@@ -30,7 +30,7 @@ Before releasing this gem on Rubygems, the following things need to be finished:
 
 # Nice-to-haves
  
-- [ ] Basic integration with RSpec. See also https://groups.google.com/forum/#!msg/rspec/U-LmL0OnO-Y/iW_Jcd6JBAAJ for progress on this.
+- [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.
@@ -66,8 +66,9 @@ _(to be precise: a method on the execution context is defined which returns the
 Raise an exception from the block if there is a problem. If there is no problem, just return normally.
 
 ```ruby
+include PropCheck::Generators
 # testing that Enumerable#sort sorts in ascending order
-PropCheck.forall(numbers: array(integer())) do
+PropCheck.forall(array(integer)) do |numbers|
   sorted_numbers = numbers.sort
   
   # Check that no number is smaller than the previous number
@@ -77,6 +78,50 @@ PropCheck.forall(numbers: array(integer())) do
 end
 ```
 
+
+Here is another example, using it inside a test case.
+Here we check if `naive_average` indeed always returns an integer for all arrays of numbers we can pass it:
+
+```ruby
+# Somewhere you have this function definition:
+def naive_average(array)
+  array.sum / array.length
+end
+
+# And then in a test case:
+include PropCheck::Generators
+PropCheck.forall(array(integer)) do |array|
+  result = naive_average(array)
+  unless result.is_a?(Integer) do
+    raise "Expected the average to be an integer!"
+  end
+end
+```
+
+When running this particular example PropCheck very quickly finds out that we have made a programming mistake:
+
+```ruby
+ZeroDivisionError: 
+(after 6 successful property test runs)
+Failed on: 
+`{
+    :array => []
+}`
+
+Exception message:
+---
+divided by 0
+---
+
+(shrinking impossible)
+---
+```
+
+Clearly we forgot to handle the case of an empty array being passed to the function.
+This is a good example of the kind of conceptual bugs that PropCheck (and property-based testing in general)
+are able to check for.
+
+
 #### Shrinking
 
 When a failure is found, PropCheck will re-run the block given to `forall` to test
@@ -106,21 +151,28 @@ A short summary:
 - Arrays and hashes shrink to fewer elements, as well as shrinking their elements.
 - Strings shrink to shorter strings, as well as characters earlier in their alphabet.
 
+### Builtin Generators
+
+PropCheck comes with [many builtin generators in the PropCheck::Generators](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck/Generators) module.
+
+It contains generators for:
+- (any, positive, negative, etc.) integers, 
+- (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.
+- 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.
 
 ### Writing Custom Generators
 
-PropCheck comes bundled with a bunch of common generators, for:
-- integers
-- floats
-- strings
-- symbols
-- arrays
-- hashes
-etc.
+As described in the previous section, PropCheck already comes bundled with a bunch of common generators.
 
 However, you can easily adapt them to generate your own datatypes:
 
-#### Generator#wrap
+#### Generators#constant / Generator#wrap
 
 Always returns the given value. No shrinking.
 

data/lib/prop_check/generator.rb

@@ -72,7 +72,7 @@ module PropCheck
       #   end.flatten
       # end
       Generator.new do |size, rng|
-        outer_result = generate(size, rng)
+        outer_result = self.generate(size, rng)
         outer_result.bind do |outer_val|
           inner_generator = generator_proc.call(outer_val)
           inner_generator.generate(size, rng)
@@ -91,5 +91,24 @@ module PropCheck
         result.map(&proc)
       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|
+        if condition.call(*result)
+          result
+        else
+          :"_PropCheck.filter_me"
+        end
+      end
+      # self.map do |*result|
+      #   if condition.call(*result)
+      #     result
+      #   else
+      #     :'_PropCheck.filter_me'
+      #   end
+      # end
+    end
   end
 end

data/lib/prop_check/lazy_tree.rb

@@ -73,7 +73,8 @@ module PropCheck
         [tree.root].lazy_append(new_children)
       end
 
-      squish.call(self, [])
+      squish
+        .call(self, [])
 
       # base = [root]
       # recursive = children.map(&:each)
@@ -99,7 +100,8 @@ module PropCheck
     #   >> LazyTree.new(1, [LazyTree.new(2, [LazyTree.new(3)]), LazyTree.new(4)]).to_a
     #   => [1, 4, 2, 3]
     def to_a
-      each.force
+      each
+        .force
     end
 
     # TODO: fix implementation

data/lib/prop_check/property.rb

@@ -2,24 +2,39 @@ require 'stringio'
 require "awesome_print"
 
 require 'prop_check/property/configuration'
-require 'prop_check/property/check_evaluator'
 module PropCheck
   ##
   # Run properties
   class Property
 
     ##
-    # Call this with a keyword argument list of (symbol => generators) and a block.
-    # The block will then be executed many times, with the respective symbol names
-    # being defined as having a single generated value.
+    # Main entry-point to create (and possibly immediately run) a property-test.
+    #
+    # This method accepts a list of generators and a block.
+    # The block will then be executed many times, passing the values generated by the generators
+    # as respective arguments:
+    #
+    # ```
+    # include PropCheck::Generators
+    # PropCheck.forall(integer(), float()) { |x, y| ... }
+    # ```
+    #
+    # It is also possible (and recommended when having more than a few generators) to use a keyword-list
+    # of generators instead:
+    #
+    # ```
+    # include PropCheck::Generators
+    # PropCheck.forall(x: integer(), y: float()) { |x:, y:| ... }
+    # ```
+    #
     #
     # If you do not pass a block right away,
     # a Property object is returned, which you can call the other instance methods
     # of this class on before finally passing a block to it using `#check`.
-    # (so `forall(a: Generators.integer) do ... end` and forall(a: Generators.integer).check do ... end` are the same)
-    def self.forall(**bindings, &block)
+    # (so `forall(Generators.integer) do |val| ... end` and forall(Generators.integer).check do |val| ... end` are the same)
+    def self.forall(*bindings, &block)
 
-      property = new(bindings)
+      property = new(*bindings)
 
       return property.check(&block) if block_given?
 
@@ -45,11 +60,12 @@ module PropCheck
 
     attr_reader :bindings, :condition
 
-    def initialize(**bindings)
-      raise ArgumentError, 'No bindings specified!' if bindings.empty?
+    def initialize(*bindings, **kwbindings)
+      raise ArgumentError, 'No bindings specified!' if bindings.empty? && kwbindings.empty?
 
       @bindings = bindings
-      @condition = -> { true }
+      @kwbindings = kwbindings
+      @condition = proc { true }
       @config = self.class.configuration
     end
 
@@ -87,7 +103,9 @@ module PropCheck
     # Only filter if you have few inputs to reject. Otherwise, improve your generators.
     def where(&condition)
       original_condition = @condition.dup
-      @condition = -> { instance_exec(&original_condition) && instance_exec(&condition) }
+      @condition = proc do |**kwargs|
+        original_condition.call(**kwargs) && condition.call(**kwargs)
+      end
 
       self
     end
@@ -95,7 +113,15 @@ module PropCheck
     ##
     # Checks the property (after settings have been altered using the other instance methods in this class.)
     def check(&block)
-      binding_generator = PropCheck::Generators.fixed_hash(bindings)
+      gens =
+        if @kwbindings != {}
+          kwbinding_generator = PropCheck::Generators.fixed_hash(**@kwbindings)
+          @bindings + [kwbinding_generator]
+        else
+          @bindings
+        end
+      binding_generator = PropCheck::Generators.tuple(*gens)
+      # binding_generator = PropCheck::Generators.fixed_hash(**@kwbindings)
 
       n_runs = 0
       n_successful = 0
@@ -113,6 +139,10 @@ module PropCheck
     private def ensure_not_exhausted!(n_runs)
       return if n_runs >= @config.n_runs
 
+      raise_generator_exhausted!
+    end
+
+    private def raise_generator_exhausted!()
       raise Errors::GeneratorExhaustedError, """
         Could not perform `n_runs = #{@config.n_runs}` runs,
         (exhausted #{@config.max_generate_attempts} tries)
@@ -124,7 +154,7 @@ module PropCheck
     end
 
     private def check_attempt(generator_result, n_successful, &block)
-      CheckEvaluator.new(generator_result.root, &block).call
+      block.call(*generator_result.root)
 
     # immediately stop (without shrinnking) for when the app is asked
     # to close by outside intervention
@@ -160,8 +190,8 @@ module PropCheck
       (0...@config.max_generate_attempts)
         .lazy
         .map { binding_generator.generate(size, rng) }
-        .reject { |val| val.root == :"_PropCheck.filter_me" }
-        .select { |val| CheckEvaluator.new(val.root, &@condition).call }
+        .reject { |val| val.root.any? { |elem| elem == :"_PropCheck.filter_me" }}
+        .select { |val| @condition.call(*val.root) }
         .map do |result|
           n_runs += 1
           size += 1
@@ -194,25 +224,29 @@ module PropCheck
     end
 
     private def post_output(output, n_shrink_steps, shrunken_result, shrunken_exception)
-      output.puts ''
-      output.puts "Shrunken input (after #{n_shrink_steps} shrink steps):"
-      output.puts "`#{print_roots(shrunken_result)}`"
-      output.puts ""
-      output.puts "Shrunken exception:\n---\n#{shrunken_exception}"
-      output.puts "---"
-      output.puts ""
-
+      if n_shrink_steps == 0
+        output.puts '(shrinking impossible)'
+      else
+        output.puts ''
+        output.puts "Shrunken input (after #{n_shrink_steps} shrink steps):"
+        output.puts "`#{print_roots(shrunken_result)}`"
+        output.puts ""
+        output.puts "Shrunken exception:\n---\n#{shrunken_exception}"
+        output.puts "---"
+        output.puts ""
+      end
       output
     end
 
-    private def print_roots(lazy_tree_hash)
-      # lazy_tree_hash.map do |name, val|
-      #   "#{name} = #{val.inspect}"
-      # end.join(", ")
-      lazy_tree_hash.ai
+    private def print_roots(lazy_tree_val)
+      if lazy_tree_val.is_a?(Array) && lazy_tree_val.length == 1 && lazy_tree_val[0].is_a?(Hash)
+        lazy_tree_val[0].ai
+      else
+        lazy_tree_val.ai
+      end
     end
 
-    private def shrink(bindings_tree, io, &fun)
+    private def shrink(bindings_tree, io, &block)
       io.puts 'Shrinking...' if @config.verbose
       problem_child = bindings_tree
       siblings = problem_child.children.lazy
@@ -234,7 +268,7 @@ module PropCheck
         io.print '.' if @config.verbose
 
         begin
-          CheckEvaluator.new(sibling.root, &fun).call
+          block.call(*sibling.root)
         rescue Exception => e
           problem_child = sibling
           parent_siblings = siblings

data/lib/prop_check/rspec.rb

@@ -1,17 +1,19 @@
 module PropCheck
   ##
   # Integration with RSpec
+  #
+  # Currently very basic; it does two things:
+  # 1. adds the local `forall` method to examples that calls `PropCheck.forall`
+  # 2. adds `include PropCheck::Generators` statement.
   module RSpec
     # To make it available within examples
     def self.extend_object(obj)
+      obj.instance_eval do
+        include PropCheck::Generators
+      end
+
       obj.define_method(:forall) do |*args, **kwargs, &block|
-        if block_given?
-          PropCheck::Property.forall(*args, **kwargs) do
-            instance_exec(self, &block)
-          end
-        else
-          PropCheck::Property.forall(*args, **kwargs)
-        end
+        PropCheck.forall(*args, **kwargs, &block)
       end
     end
   end

data/lib/prop_check/version.rb

@@ -1,3 +1,3 @@
 module PropCheck
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prop_check
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Qqwy/Wiebe-Marten Wijnja
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-19 00:00:00.000000000 Z
+date: 2020-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -84,7 +84,6 @@ files:
 - lib/prop_check/helper/lazy_append.rb
 - lib/prop_check/lazy_tree.rb
 - lib/prop_check/property.rb
-- lib/prop_check/property/check_evaluator.rb
 - lib/prop_check/property/configuration.rb
 - lib/prop_check/rspec.rb
 - lib/prop_check/version.rb

data/lib/prop_check/property/check_evaluator.rb

@@ -1,45 +0,0 @@
-module PropCheck
-  class Property
-    ##
-    # A wrapper class that implements the 'Cloaker' concept
-    # which allows us to refer to variables set in 'bindings',
-    # while still being able to access things that are only in scope
-    # in the creator of '&block'.
-    #
-    # This allows us to bind the variables specified in `bindings`
-    # one way during checking and another way during shrinking.
-    class CheckEvaluator
-      include RSpec::Matchers if Object.const_defined?('RSpec')
-
-      def initialize(bindings, &block)
-        @caller = block.binding.receiver
-        @block = block
-        define_named_instance_methods(bindings)
-      end
-
-      def call
-        self.instance_exec(&@block)
-      end
-
-      private def define_named_instance_methods(results)
-        results.each do |name, result|
-          define_singleton_method(name) { result }
-        end
-      end
-
-      ##
-      # Dispatches to caller whenever something is not part of `bindings`.
-      # (No need to invoke this method manually)
-      def method_missing(method, *args, &block)
-        @caller.__send__(method, *args, &block) || super
-      end
-
-      ##
-      # Checks respond_to of caller whenever something is not part of `bindings`.
-      # (No need to invoke this method manually)
-      def respond_to_missing?(*args)
-        @caller.respond_to?(*args) || super
-      end
-    end
-  end
-end