prop_check 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e59cf670bcc8cf9720d6278e984925c50e75ca65023459174f8b511d6421fb71
-  data.tar.gz: '088e0eb8d2d301bc3c03cc63bf68196969e8653cad37ff0b9d5d10f9b417a1ae'
+  metadata.gz: ba078df3937d6f069a4ed24e9aaed9617dc1eb03139be0189e51b060b11a75ba
+  data.tar.gz: 0fe77f31d282754df6712aafae7995e82e99d9ee86f8ad12bd060596147dafe1
 SHA512:
-  metadata.gz: de5808bced970e0c474367bf125837ac0eefa4aa752acb31cd74e884fea858b98fb518e9fe15493c81f8238e5e0490f3cbc855eda3a9b687196ca7830daad0aa
-  data.tar.gz: 312957d1ab0f990985f43ae7e4b0793df583ff2d3d8bb95573c11fe3e4d9c5f964d91050fe9bafb98ceb92dd6790d2ffce04257b02b0c152d75d9b4772b7423a
+  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,6 @@
+- 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`.

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
@@ -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)

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.17.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.17.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