prop_check 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 912a84633a6ab5b7f209555be0086e4dcafd371f337b289113003edf765fb668
-  data.tar.gz: 92146dcaf693c20f4cb3021178e881495de8b63f3819c254aea186a3780891c0
+  metadata.gz: ba078df3937d6f069a4ed24e9aaed9617dc1eb03139be0189e51b060b11a75ba
+  data.tar.gz: 0fe77f31d282754df6712aafae7995e82e99d9ee86f8ad12bd060596147dafe1
 SHA512:
-  metadata.gz: 192ed9c6887dc19f29fc3d8aba9278eeb0fd389aab9fae546c940e2831833ea8064ea53e1e903c599d7d7ec2a8fe5bdc04a2c3122c2374a2d1d933b2184a2ab0
-  data.tar.gz: 63005af74e5f0d1757930f64ce031f5cc922e34b4e876cdaebbbf139280e9e923d134440f20ab63129c4fd1647d1e524b07b6ed3800828b29d22ad7e2cc5e394
+  metadata.gz: e49791f3e5a380e822f4d86f39444a09e26828c4b1ea7c90d298c9eedcc14d8c6fdc05864439e1984b0cead4183beb1ae108bee82c7ce6dccbe11aae5efbd248
+  data.tar.gz: cddd15cf550e166ec93d15fa2ffdf07a68646aa6750d544b6a5cf64c9bfb44177b638e6ff1df2ce25e28105df05aa838534e6eaafadefb7688aed32dae9d3bbc

data/.github/workflows/run_tests.yaml

@@ -2,9 +2,9 @@ name: Ruby RSpec tests
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
 
 permissions:
   contents: read

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+- 0.18.0
+  - Features:
+    - Allows calling `PropCheck::Property#check` without a block, which will just return `self`. This is useful for writing wrapper functions that use `before/after/around/with_config` etc hooks which might themselves optionally want a block so they can be chained. (See the `forall_with_db` snippet in the README for an example)
+- 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.

data/README.md

@@ -40,9 +40,9 @@ It works by generating arbitrary data matching your specification and checking t
 
 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.
+- Your code should never crash.
 - If you remove an object, you can no longer see it
-- If you serialize and then deserializea value, you get the same value back.
+- If you serialize and then deserialize a value, you get the same value back.
 
 
 ## Implemented and still missing features
@@ -64,7 +64,7 @@ Before releasing v1.0, we want to finish the following:
 - [x] Builtin generation of `Set`s
 - [x] Builtin generation of `Date`s, `Time`s and `DateTime`s.
 - [x] Configuration option to resize all generators given to a particular Property instance.
-- [ ] A simple way to create recursive generators
+- [x] A simple way to create recursive generators
 - [ ] A usage guide.
 
 ## Nice-to-haves
@@ -107,7 +107,7 @@ PropCheck.forall(G.array(G.integer)) do |numbers|
   
   # Check that no number is smaller than the previous number
   sorted_numbers.each_cons(2) do |former, latter| 
-    raise "Elements are not sorted! #{latter} is < #{former}" if latter < former
+    raise "Elements are not sorted! #{latter} is < #{former}" if latter > former
   end
 end
 ```
@@ -122,32 +122,53 @@ def naive_average(array)
   array.sum / array.length
 end
 ```
-```ruby
-# And then in a test case:
-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!"
-  end
-end
 
-# Or if you e.g. are using RSpec:
-describe "#naive_average" do
-  include PropCheck
+The test case, using RSpec:
+``` ruby
+require 'rspec'
+
+RSpec.describe "#naive_average" do
   G = PropCheck::Generators
 
   it "returns an integer for any input" do
-    forall(numbers: G.array(G.integer)) do |numbers:|
-      result = naive_average(numbers)      
+    PropCheck.forall(G.array(G.integer)) do |numbers|
+      result = naive_average(numbers)
+
       expect(result).to be_a(Integer)
     end
   end
 end
 ```
 
-When running this particular example PropCheck very quickly finds out that we have made a programming mistake:
+The test case, using MiniTest:
+``` ruby
+require 'minitest/autorun'
+class NaiveAverageTest < MiniTest::Unit::TestCase
+  G = PropCheck::Generators
+
+  def test_that_it_returns_an_integer_for_any_input()
+    PropCheck.forall(G.array(G.integer)) do |numbers|
+      result = naive_average(numbers)
+
+      assert_instance_of(Integer, result)
+    end
+  end
+end
+```
 
+The test case, using only vanilla Ruby:
+```ruby
+# And then in a test case:
+G = PropCheck::Generators
+
+PropCheck.forall(G.array(G.integer)) do |numbers|
+  result = naive_average(numbers)
+
+  raise "Expected the average to be an integer!" unless result.is_a?(Integer)
+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)
@@ -270,6 +291,26 @@ although above are the most generally useful ones.
 [PropCheck::Generator documentation](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck/Generator)
 [PropCheck::Generators documentation](https://www.rubydoc.info/github/Qqwy/ruby-prop_check/master/PropCheck/Generators)
 
+
+## Usage within Rails / with a database
+
+Using PropCheck for unit tests in a Rails, Sinatra, Hanami, etc. project is very easy.
+Here are some simple recommendations for the best results:
+- Tests that do not need to use the DB at all are usually 10x-100x faster. Faster tests means that you can configure PropCheck to do more test runs.
+- If you do need to use the database, use the [database_cleaner](https://github.com/DatabaseCleaner/database_cleaner) gem, preferibly with the fast `:transaction` strategy if your RDBMS supports it. To make sure the DB is cleaned around each generated example, you can write the following helper:
+``` ruby
+  # Version of PropCheck.forall
+  # which ensures records persisted to the DB in one generated example
+  # do not affect any other
+  def forall_with_db(*args, **kwargs, &block)
+      PropCheck.forall(*args, **kwargs)
+               .before { DatabaseCleaner.start }
+               .after { DatabaseCleaner.clean }
+               .check(&block)
+  end
+```
+- Other setup/cleanup should also usually happen around each generated example rather than around the whole test: Instead of using the hooks exposed by RSpec/MiniTest/etc., use the before/after/around hooks exposed by PropCheck.
+
 ## Development
 
 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.
@@ -286,7 +327,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the PropCheck project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/prop_check/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the PropCheck project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/Qqwy/ruby-prop_check/blob/master/CODE_OF_CONDUCT.md).
 
 ## Attribution and Thanks
 
@@ -294,7 +335,7 @@ I want to thank the original creators of QuickCheck (Koen Claessen, John Hughes)
 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:
+The implementation and API of PropCheck takes a lot of inspiration from the following projects:
 
 - 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);

data/lib/prop_check/generator.rb

@@ -116,7 +116,7 @@ module PropCheck
     # 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)
+    #  => Date.new(2023, 01, 12)
     def with_config
       Generator.new do |**kwargs|
         result = generate(**kwargs)

data/lib/prop_check/generators.rb

@@ -769,7 +769,7 @@ module PropCheck
     # 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)
+    #   >> PropCheck::Generators.datetime(epoch: Date.new(2022, 11, 20)).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)
@@ -785,7 +785,7 @@ module PropCheck
     ##
     # 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)
+    #   >> PropCheck::Generators.future_datetime(epoch: Date.new(2022, 11, 20)).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)
@@ -794,7 +794,7 @@ module PropCheck
     ##
     # 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)
+    #   >> PropCheck::Generators.past_datetime(epoch: Date.new(2022, 11, 20)).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)
@@ -805,7 +805,7 @@ module PropCheck
     # 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)
+    #   >> PropCheck::Generators.time(epoch: Date.new(2022, 11, 20)).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)
@@ -872,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/property.rb

@@ -42,11 +42,8 @@ module PropCheck
     # of this class on before finally passing a block to it using `#check`.
     # (so `forall(Generators.integer) do |val| ... end` and forall(Generators.integer).check do |val| ... end` are the same)
     def self.forall(*bindings, **kwbindings, &block)
-      property = new(*bindings, **kwbindings)
-
-      return property.check(&block) if block_given?
-
-      property
+      new(*bindings, **kwbindings)
+        .check(&block)
     end
 
     ##
@@ -106,9 +103,7 @@ module PropCheck
       duplicate.instance_variable_set(:@config, @config.merge(config))
       duplicate.freeze
 
-      return duplicate.check(&block) if block_given?
-
-      duplicate
+      duplicate.check(&block)
     end
 
     ##
@@ -248,6 +243,8 @@ module PropCheck
     ##
     # Checks the property (after settings have been altered using the other instance methods in this class.)
     def check(&block)
+      return self unless block_given?
+
       n_runs = 0
       n_successful = 0
 

data/lib/prop_check/version.rb

@@ -1,3 +1,3 @@
 module PropCheck
-  VERSION = '0.16.0'
+  VERSION = '0.18.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prop_check
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Qqwy/Wiebe-Marten Wijnja
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-11-20 00:00:00.000000000 Z
+date: 2022-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amazing_print