properb 0.0.1

data/README.md

@@ -0,0 +1,56 @@
+# Properb
+
+Property-based testing in Ruby, with RSpec integration.
+
+## Installation
+
+This project
+
+## Usage
+
+To install, add the following to your `spec/spec_helper.rb` file:
+
+```ruby
+RSpec.configure do |config|
+  Properb.rspec_install(config)
+end
+```
+
+Then you can use `generate` and `it_always` in your tests to create property-based tests:
+
+```ruby
+describe "#sort" do
+  generate(strings: array(string))
+
+  it_always "preserves the number of elements", num_tests: 200 do
+    expect(strings.sort.length).to be == strings.length
+  end
+
+  it_always "has the first and last elements in sorted order" do
+    assume(strings).to_not be_empty
+    sorted = strings.sort
+    expect(sorted[0]).to be <= sorted[-1]
+  end
+
+  it_always "creates pairwise sorted elements", num_tests: 200 do
+    # assume(strings.length).to be >= 2
+    assume(strings.uniq).to eq(strings)
+    sorted = strings.sort
+    (0...sorted.length - 1).each do |i|
+      expect(sorted[i]).to be < sorted[i + 1]
+    end
+  end
+end
+```
+
+## Development
+
+This project uses Guix as its main dependency management system. A development environment can be created by running:
+
+```sh
+guix shell --development --file=guix.scm
+```
+
+## Contributing
+
+Bug reports and changes are welcome on SourceHut at <https://sr.ht/~czan/properb/>.

data/lib/properb/generator.rb

@@ -0,0 +1,29 @@
+module Properb
+  class Generator
+    def to_properb_generator
+      self
+    end
+
+    def map(&block)
+      Generators::MappedGenerator.new(self, &block)
+    end
+
+    def select(num_attempts: 10, &block)
+      Generators::SelectedGenerator.new(self, num_attempts: num_attempts, &block)
+    end
+
+    def reject(num_attempts: 10, &block)
+      select(num_attempts: num_attempts) do |*args|
+        !block.call(*args)
+      end
+    end
+
+    def or(generator)
+      Generators::ChoiceGenerator.new([self, Generators.gen(generator)])
+    end
+
+    def sized(size)
+      Generators::SizedGenerator.new(self, size)
+    end
+  end
+end

data/lib/properb/generators/array_generator.rb

@@ -0,0 +1,75 @@
+module Properb
+  module Generators
+    class ArrayGenerator < Generator
+      def initialize(generator, length: 0...)
+        @generator = generator
+        @length = length
+      end
+
+      def generate_value(random, size)
+        if @length.is_a?(Range)
+          length = random.random_number(@length.min..(@length.end || (@length.min + size)))
+          min_length = @length.min
+        else
+          length = min_length = @length
+        end
+        values = (0...length).map { @generator.generate_value(random, size) }
+        ShrinkTree.new(
+          values.map(&:value),
+          shrink(values, min_length)
+        )
+      end
+
+      def shrink(values, min_length)
+        Enumerator.new do |out|
+          cutoff = (values.length / 2).ceil
+          if cutoff > min_length
+            out << ShrinkTree.new(
+              values[cutoff..].map(&:value),
+              shrink(values[cutoff..], min_length)
+            )
+            out << ShrinkTree.new(
+              values[...-cutoff].map(&:value),
+              shrink(values[...-cutoff], min_length)
+            )
+          end
+          if values.length > min_length
+            # Try removing individual items in the vector
+            (0...values.length).each do |i|
+              new_values = values[0...i] + values[i + 1...]
+              out << ShrinkTree.new(
+                new_values.map(&:value),
+                shrink(new_values, min_length)
+              )
+            end
+          end
+          # Try shrinking the individual items in the vector
+          (0...values.length).each do |i|
+            values[i].children.each do |value|
+              new_values = values[0...i] + [value] + values[i + 1...]
+              out << ShrinkTree.new(
+                new_values.map(&:value),
+                shrink(new_values, min_length)
+              )
+            end
+          end
+          # Try shrinking pairs of items in the vector
+          (0...values.length).each do |i| # rubocop:disable Style/CombinableLoops
+            values[i].children.each do |first_value|
+              new_values = values[0...i] + [first_value] + values[i + 1...]
+              (0...values.length).each do |j|
+                new_values[j].children.each do |second_value|
+                  newer_values = new_values[0...j] + [second_value] + new_values[j + 1...]
+                  out << ShrinkTree.new(
+                    newer_values.map(&:value),
+                    shrink(newer_values, min_length)
+                  )
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/properb/generators/choice_generator.rb

@@ -0,0 +1,26 @@
+module Properb
+  module Generators
+    class ChoiceGenerator < Generator
+      def initialize(generators)
+        @generators = generators
+      end
+
+      # Overriding the superclass method to make the distribution even
+      def or(generator)
+        ChoiceGenerator.new([*@generators, generator])
+      end
+
+      def generate_value(random, size)
+        integer = IntegerGenerator.new(0...@generators.length)
+                                  .generate_value(random, size)
+        saved_random = random.dup
+        integer.flat_map do |choice|
+          # We want all the sub-generators use the same random number
+          # sequence, so we duplicate the generator
+          new_random = saved_random.dup
+          @generators[choice].generate_value(new_random, size)
+        end
+      end
+    end
+  end
+end

data/lib/properb/generators/constant_generator.rb

@@ -0,0 +1,13 @@
+module Properb
+  module Generators
+    class ConstantGenerator < Generator
+      def initialize(value)
+        @value = value
+      end
+
+      def generate_value(_random, _size)
+        ShrinkTree.new(@value, [])
+      end
+    end
+  end
+end

data/lib/properb/generators/deferred_generator.rb

@@ -0,0 +1,15 @@
+module Properb
+  module Generators
+    class DeferredGenerator < Generator
+      def initialize(&block)
+        @block = block
+        @generator = nil
+      end
+
+      def generate_value(random, size)
+        @generator = Generators.gen(@block.call)
+        @generator.generate_value(random, size)
+      end
+    end
+  end
+end

data/lib/properb/generators/frequencies_generator.rb

@@ -0,0 +1,26 @@
+module Properb
+  module Generators
+    class FrequenciesGenerator < Generator
+      def initialize(frequencies)
+        @frequencies = frequencies
+      end
+
+      def generate_value(random, size)
+        integer = IntegerGenerator.new(0...@frequencies.values.sum)
+                                  .generate_value(random, size)
+        saved_random = random.dup
+        integer.flat_map do |choice|
+          new_random = saved_random.dup
+          running = 0
+          generator = @frequencies.find do |_generator, weight|
+            running += weight
+            running > choice
+          end.first
+          raise "No generator found in `frequencies' - insufficient weights?" unless generator
+
+          generator.generate_value(new_random, size)
+        end
+      end
+    end
+  end
+end

data/lib/properb/generators/integer_generator.rb

@@ -0,0 +1,30 @@
+module Properb
+  module Generators
+    class IntegerGenerator < Generator
+      def initialize(range = 0..)
+        @range = range
+      end
+
+      def generate_value(random, _size)
+        value = random.random_number(@range)
+        ShrinkTree.new(
+          value,
+          Enumerator.new do |out|
+            out << ShrinkTree.new(@range.min, [])
+            shrink(value, @range.min).each { out << _1 }
+          end
+        )
+      end
+
+      def shrink(value, min)
+        midpoint = ((value + min) / 2).floor
+        return [] if midpoint == min # termination
+
+        Enumerator.new do |out|
+          out << ShrinkTree.new(midpoint, shrink(midpoint, min))
+          shrink(value, midpoint).each { out << _1 }
+        end
+      end
+    end
+  end
+end

data/lib/properb/generators/mapped_generator.rb

@@ -0,0 +1,14 @@
+module Properb
+  module Generators
+    class MappedGenerator < Generator
+      def initialize(generator, &block)
+        @generator = generator
+        @block = block
+      end
+
+      def generate_value(random, size)
+        @generator.generate_value(random, size).map(&@block)
+      end
+    end
+  end
+end

data/lib/properb/generators/recursive_generator.rb

@@ -0,0 +1,15 @@
+module Properb
+  module Generators
+    class RecursiveGenerator < Generator
+      def initialize(&block)
+        @block = block
+      end
+
+      def generate_value(random, size)
+        @block
+          .call(size, RecursiveGenerator.new(&@block).sized((size / 2).floor))
+          .generate_value(random, size)
+      end
+    end
+  end
+end

data/lib/properb/generators/selected_generator.rb

@@ -0,0 +1,19 @@
+module Properb
+  module Generators
+    class SelectedGenerator < Generator
+      def initialize(generator, num_attempts: 10, &block)
+        @generator = generator
+        @num_attempts = num_attempts
+        @block = block
+      end
+
+      def generate_value(random, size)
+        @num_attempts.times do
+          generated = @generator.generate_value(random, size)
+          return generated.select(&@block).first if @block.call(generated.value)
+        end
+        raise "Could not generate a value after #{@num_attempts} attempts"
+      end
+    end
+  end
+end

data/lib/properb/generators/sized_generator.rb

@@ -0,0 +1,14 @@
+module Properb
+  module Generators
+    class SizedGenerator < Generator
+      def initialize(generator, size)
+        @generator = generator
+        @size = size
+      end
+
+      def generate_value(random, _size)
+        @generator.generate_value(random, @size)
+      end
+    end
+  end
+end

data/lib/properb/generators/tuple_generator.rb

@@ -0,0 +1,41 @@
+module Properb
+  module Generators
+    class TupleGenerator < Generator
+      def initialize(generators)
+        @generators = generators
+      end
+
+      def generate_value(random, size)
+        values = @generators.map { _1.generate_value(random, size) }
+        ShrinkTree.new(values.map(&:value), shrink(values))
+      end
+
+      def shrink(values)
+        Enumerator.new do |out|
+          # Try shrinking the individual items in the vector
+          (0...values.length).each do |i|
+            values[i].children.each do |value|
+              new_values = values[0...i] + [value] + values[i + 1...]
+              out << ShrinkTree.new(new_values.map(&:value), shrink(new_values))
+            end
+          end
+          # Try shrinking pairs of items in the vector
+          (0...values.length).each do |i|
+            values[i].children.each do |value|
+              new_values = values[0...i] + [value] + values[i + 1...]
+              (0...values.length).each do |j|
+                new_values[j].children.each do |value|
+                  newer_values = new_values[0...j] + [value] + new_values[j + 1...]
+                  out << ShrinkTree.new(
+                    newer_values.map(&:value),
+                    shrink(newer_values)
+                  )
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/properb/generators.rb

@@ -0,0 +1,83 @@
+require_relative "generators/array_generator"
+require_relative "generators/choice_generator"
+require_relative "generators/constant_generator"
+require_relative "generators/deferred_generator"
+require_relative "generators/frequencies_generator"
+require_relative "generators/integer_generator"
+require_relative "generators/mapped_generator"
+require_relative "generators/recursive_generator"
+require_relative "generators/selected_generator"
+require_relative "generators/sized_generator"
+require_relative "generators/tuple_generator"
+
+module Properb
+  module Generators
+    extend Generators # Bring all these methods onto the module itself
+
+    def defer(&block)
+      DeferredGenerator.new(&block)
+    end
+
+    def gen(object)
+      if object.respond_to?(:to_properb_generator)
+        object.to_properb_generator
+      else
+        const(object)
+      end
+    end
+
+    def one_of(*options)
+      ChoiceGenerator.new(options.map { gen(_1) })
+    end
+
+    def int(range = 0..(2 << 32))
+      IntegerGenerator.new(range)
+    end
+
+    # By default, generate printable ASCII characters
+    def string(char_generator = int(32..126).map { _1.chr }, length: 0..)
+      array(char_generator, length: length).map { _1.join }
+    end
+
+    def const(value)
+      ConstantGenerator.new(value)
+    end
+
+    def boolean
+      const(false).or(const(true))
+    end
+
+    def maybe(generator)
+      ChoiceGenerator.new([const(nil), gen(generator)])
+    end
+
+    def frequencies(**generators_and_weights)
+      FrequenciesGenerator.new(generators_and_weights.transform_values { gen(_1) })
+    end
+
+    def array(generator, length: 0..)
+      ArrayGenerator.new(gen(generator), length: length)
+    end
+
+    def tuple(*generators)
+      TupleGenerator.new(generators.map { gen(_1) })
+    end
+
+    def hashmap(key_generator, value_generator = nil)
+      if value_generator.nil?
+        unless key_generator.is_a?(Hash)
+          raise "Single argument to `hashmap' must be a hash with generator values, not #{key_generator || "nil"}"
+        end
+
+        tuple(*key_generator.values.map { gen(_1) })
+          .map { key_generator.keys.zip(_1).to_h }
+      else
+        array(tuple(key_generator, value_generator)).map(&:to_h)
+      end
+    end
+
+    def recursive(&block)
+      RecursiveGenerator.new(&block)
+    end
+  end
+end

data/lib/properb/rspec/example_group_methods.rb

@@ -0,0 +1,64 @@
+module Properb
+  module RSpec
+    module ExampleGroupMethods
+      class PropertyExample < ::RSpec::Core::Example
+        private
+
+        def with_around_and_singleton_context_hooks
+          Properb.for_all(metadata[:generators], **metadata.slice(:size, :num_tests, :assumption_limit)) do |data|
+            @example_group_instance.instance_variable_set("@properb_generated_data", data)
+            super
+            if display_exception
+              ex = display_exception
+              self.display_exception = nil
+              raise ex
+            end
+          ensure
+            @example_group_instance.instance_variable_set("@properb_generated_data", nil)
+          end
+        end
+      end
+
+      def generate(**methods_and_generators)
+        @properb_generators ||= {}
+        @properb_generators.merge!(methods_and_generators)
+        @properb_generators.keys.each do |key|
+          define_method(key) do
+            raise "Cannot call #{key} outside of a property" unless @properb_generated_data
+
+            @properb_generated_data[key]
+          end
+        end
+      end
+
+      def it_always(description, **options, &block)
+        PropertyExample.new(self,
+                            description,
+                            { property: true,
+                              generators: @properb_generators,
+                              **options },
+                            block)
+      end
+
+      def fit_always(description, **options, &block)
+        PropertyExample.new(self,
+                            description,
+                            { property: true,
+                              generators: @properb_generators,
+                              focus: true,
+                              **options },
+                            block)
+      end
+
+      def xit_always(description, **options, &block)
+        PropertyExample.new(self,
+                            description,
+                            { property: true,
+                              generators: @properb_generators,
+                              skip: "Temporarily skipped with xit_always",
+                              **options },
+                            block)
+      end
+    end
+  end
+end

data/lib/properb/rspec/example_methods.rb

@@ -0,0 +1,40 @@
+module Properb
+  module RSpec
+    module ExampleMethods
+      class AssumptionViolated < StandardError; end
+
+      class Assumption
+        def initialize(target)
+          @target = target
+        end
+
+        def to(matcher = nil, message = nil, &block)
+          handle_positive_matcher(@target, matcher, message, &block)
+        end
+
+        def to_not(matcher = nil, message = nil, &block)
+          handle_negative_matcher(@target, matcher, message, &block)
+        end
+        alias not_to to_not
+
+        private
+
+        def handle_positive_matcher(actual, matcher, custom_message, &block)
+          return if matcher.matches?(actual, &block)
+
+          raise AssumptionViolated, custom_message || matcher.failure_message
+        end
+
+        def handle_negative_matcher(actual, matcher, custom_message, &block)
+          return unless matcher.matches?(actual, &block)
+
+          raise AssumptionViolated, custom_message || matcher.failure_message
+        end
+      end
+
+      def assume(value)
+        Assumption.new(value)
+      end
+    end
+  end
+end

data/lib/properb/rspec.rb

@@ -0,0 +1,2 @@
+require_relative "rspec/example_methods"
+require_relative "rspec/example_group_methods"

data/lib/properb/shrink_tree.rb

@@ -0,0 +1,44 @@
+module Properb
+  class ShrinkTree
+    attr_reader :value, :children
+
+    def initialize(value, children)
+      @value = value
+      @children = children.lazy
+    end
+
+    def map(&block)
+      ShrinkTree.new(
+        block.call(@value),
+        @children.map { _1.map(&block) }
+      )
+    end
+
+    def flat_map(&block)
+      result = block.call(@value)
+      # First try to shrink the parent generator, then try to shrink
+      # the child.
+      combined_children = (children.map { _1.flat_map(&block) } + result.children)
+      ShrinkTree.new(result.value, combined_children)
+    end
+
+    # Return an array of nodes to use to replace the current node,
+    # filtered by calling the provided block on the node's values.
+    def select(&block)
+      if block.call(@value)
+        [
+          ShrinkTree.new(
+            @value,
+            @children.flat_map { _1.select(&block) }
+          )
+        ]
+      else
+        @children.flat_map { _1.select(&block) }
+      end
+    end
+
+    def debug
+      { @value => @children.map(&:debug).to_a }
+    end
+  end
+end