zizek 0.1.0

data/examples/database_workflow.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# The example database: a counterexample that outlives the run that found it.
+#
+# Demonstrates:
+#   - `database:` storing a shrunk failure's raw choice stream on disk;
+#   - the next run replaying the stored entry before generating anything, so
+#     yesterday's bug reproduces on the first attempt — no search, no seed;
+#   - the fixed bug cleaning itself up: the entry that no longer reproduces
+#     is deleted by the replay that failed to reproduce it; and
+#   - the on-disk layout (`<key digest>/<stream digest>`), which the Python
+#     and Go packages write identically, so a directory can be shared.
+#
+# The whole run works in a temporary directory and leaves nothing behind.
+
+require "tmpdir"
+require "zizek"
+
+module DatabaseWorkflowExample
+  # A name both sides of a shared directory agree on. Left unset, the key is
+  # derived from where the property was written — stable across runs, but
+  # meaningless to another language's suite.
+  DATABASE_KEY = "sorted_merge_keeps_every_element"
+
+  module_function
+
+  # Merge two sorted arrays. Deliberate bug: the loop stops at the end of the
+  # shorter input, dropping whatever the longer one still holds.
+  def merge_buggy(left, right)
+    merged = []
+    a = 0
+    b = 0
+    while a < left.length && b < right.length
+      if left[a] <= right[b]
+        merged << left[a]
+        a += 1
+      else
+        merged << right[b]
+        b += 1
+      end
+    end
+    merged # BUG: the unconsumed tail of the longer input is lost
+  end
+
+  # The property, parameterized on the merge under test so the same one can
+  # first find the bug and then verify the fix.
+  def property(merge)
+    sorted = Zizek::Generators.lists(
+      Zizek::Generators.integers(0..9), max: 4
+    ).map(&:sort)
+
+    lambda do |test_case|
+      left = test_case.draw(sorted, name: :left)
+      right = test_case.draw(sorted, name: :right)
+      merged = merge.call(left, right)
+      unless merged.length == left.length + right.length
+        raise "merged #{left.inspect} and #{right.inspect} into #{merged.inspect}"
+      end
+    end
+  end
+
+  def stored_entries(root)
+    Dir.glob(File.join(root, "*", "*")).reject { |path| File.basename(path).start_with?(".") }
+  end
+
+  def run_workflow
+    Dir.mktmpdir("zizek-example-db") do |root|
+      # Run 1: the search finds the bug, shrinks it, and stores the shrunk
+      # choice stream under the database key.
+      first =
+        begin
+          Zizek.check(property(method(:merge_buggy)),
+                      examples: 300, seed: 1,
+                      database: root, database_key: DATABASE_KEY)
+          raise "the dropped-tail bug should be discovered"
+        rescue Zizek::Failure => failure
+          failure
+        end
+      entries = stored_entries(root)
+      raise "one counterexample should be stored" unless entries.length == 1
+
+      # Run 2: a different seed, but the stored entry is replayed before any
+      # generation — the bug reproduces on the first attempt.
+      second =
+        begin
+          Zizek.check(property(method(:merge_buggy)),
+                      examples: 300, seed: 999,
+                      database: root, database_key: DATABASE_KEY)
+          raise "the stored counterexample should reproduce"
+        rescue Zizek::Failure => failure
+          failure
+        end
+      raise "the stored entry should be the first attempt" unless second.examples_run == 1
+      raise "both runs should report the same blob" unless second.blob == first.blob
+
+      # Run 3: the bug is fixed (a correct merge keeps every element, and for
+      # this property concatenation is one). The stored entry no longer
+      # reproduces, so the run deletes it and explores normally — the
+      # directory keeps itself current.
+      Zizek.check(property(->(left, right) { left + right }),
+                  examples: 100, seed: 1,
+                  database: root, database_key: DATABASE_KEY)
+      unless stored_entries(root).empty?
+        raise "the fixed bug's entry should have been collected"
+      end
+
+      [first, second]
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  first, second = DatabaseWorkflowExample.run_workflow
+  puts "== run 1: found, shrunk, and stored =="
+  puts first.message
+  puts "\n== run 2 (different seed): replayed from the database on attempt " \
+       "#{second.examples_run} =="
+  puts second.message
+  puts "\n== run 3 (bug fixed): the stale entry collected itself =="
+end

data/examples/die_hard.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Port of Hegel's Die Hard water-jug state machine. The "failure" is a solution:
+# generation finds operations leaving exactly four litres in the five-litre jug,
+# then structural shrinking removes every unnecessary operation.
+
+require "zizek"
+
+module DieHardExample
+  LEGACY_ZIZEK_DIE_HARD_FAILURE =
+    "AAwAAAABAAAKAQAAAAEBAAAKAQAAAAUBAAAKAQAAAAIBAAAKAQAAAAUBAAAKAQAAAAEBAAAKAQAAAAU="
+  SHRUNK_DIE_HARD_FAILURE =
+    "AXicbYo5CgAwDMPkQpeu/f9fc0AIgXixLfQBiSciWX6L3J5npdM1FrQAhg=="
+  HEGEL_ZLIB_DIE_HARD_FAILURE =
+    "AXicbYoxCgBACMPSg1tc/f9fdRBFcCgNIQ4ILEed1OYPvtPuNgAVzACA"
+
+  class DieHard
+    def initialize
+      @small = 0
+      @big = 0
+    end
+
+    def fill_small(_test_case)
+      @small = 3
+    end
+
+    def fill_big(_test_case)
+      @big = 5
+    end
+
+    def empty_small(_test_case)
+      @small = 0
+    end
+
+    def empty_big(_test_case)
+      @big = 0
+    end
+
+    def pour_small_into_big(_test_case)
+      previous_big = @big
+      @big = [5, @big + @small].min
+      @small -= @big - previous_big
+    end
+
+    def pour_big_into_small(_test_case)
+      previous_small = @small
+      @small = [3, @small + @big].min
+      @big -= @small - previous_small
+    end
+
+    def physics_of_jugs(_test_case)
+      raise "small jug escaped its capacity" unless @small.between?(0, 3)
+      raise "big jug escaped its capacity" unless @big.between?(0, 5)
+    end
+
+    def die_hard_problem_not_solved(test_case)
+      test_case.note("small / big = #{@small} / #{@big}")
+      raise "the five-litre jug contains four litres" if @big == 4
+    end
+
+    def rules
+      %i[
+        fill_small fill_big empty_small empty_big
+        pour_small_into_big pour_big_into_small
+      ].map do |name|
+        Zizek::Stateful::Rule.new(name.to_s, ->(machine, test_case) { machine.public_send(name, test_case) })
+      end
+    end
+
+    def invariants
+      [
+        Zizek::Stateful::Rule.new(
+          "physics_of_jugs",
+          ->(machine, test_case) { machine.physics_of_jugs(test_case) }
+        ),
+        Zizek::Stateful::Rule.new(
+          "die_hard_problem_not_solved",
+          ->(machine, test_case) { machine.die_hard_problem_not_solved(test_case) }
+        )
+      ]
+    end
+  end
+
+  module_function
+
+  def property(test_case)
+    Zizek::Stateful.run(DieHard.new, test_case)
+  end
+
+  def find_and_replay_solution
+    found =
+      begin
+        Zizek.check(method(:property), examples: 2_000, seed: 0)
+        raise "the four-litre solution should be discovered"
+      rescue Zizek::Failure => failure
+        raise unless failure.property_cause.message.include?("four litres")
+        raise unless failure.blob == SHRUNK_DIE_HARD_FAILURE
+
+        failure
+      end
+
+    begin
+      Zizek.check(method(:property), reproduce: found.blob)
+    rescue Zizek::Failure => replayed
+      raise unless replayed.notes.last == "small / big = 3 / 4"
+    else
+      raise "the shrunk jug solution must replay"
+    end
+    [LEGACY_ZIZEK_DIE_HARD_FAILURE, HEGEL_ZLIB_DIE_HARD_FAILURE].each do |blob|
+      begin
+        Zizek.check(method(:property), reproduce: blob)
+      rescue Zizek::Failure => compatible
+        raise unless compatible.notes.last == "small / big = 3 / 4"
+        next
+      end
+      raise "a compatible jug solution did not replay"
+    end
+    found
+  end
+end
+
+puts DieHardExample.find_and_replay_solution if $PROGRAM_NAME == __FILE__

data/examples/hypothesis_quickstart.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Port of Hypothesis's introductory bounded-integer example. The property is
+# deliberately false from 50 onward, so shrinking should report the first
+# failing boundary rather than merely the random value which exposed it.
+
+require "zizek"
+
+module HypothesisQuickstartExample
+  SHRUNK_BOUNDARY_FAILURE = "AAEAAAAACgEAAAAy"
+
+  module_function
+
+  def property(test_case)
+    value = test_case.draw(
+      Zizek::Generators.integers.min_value(0).max_value(200)
+    )
+    raise "#{value} is not less than 50" unless value < 50
+  end
+
+  def find_and_replay_boundary
+    found =
+      begin
+        Zizek.check(method(:property), examples: 100, seed: 1)
+        raise "the boundary bug should be discovered"
+      rescue Zizek::Failure => failure
+        raise unless failure.property_cause.message == "50 is not less than 50"
+        raise unless failure.blob == SHRUNK_BOUNDARY_FAILURE
+
+        failure
+      end
+
+    begin
+      Zizek.check(method(:property), reproduce: found.blob)
+    rescue Zizek::Failure => replayed
+      raise unless replayed.property_cause.message == found.property_cause.message
+
+      return found
+    end
+    raise "the shrunk boundary failure must replay"
+  end
+end
+
+puts HypothesisQuickstartExample.find_and_replay_boundary if $PROGRAM_NAME == __FILE__

data/examples/keyed_draws.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Keyed draws: a reproduce blob that survives editing the property.
+#
+# Demonstrates:
+#   - naming a decision with `key: Zizek.key_hash(...)` so a replay finds it
+#     by name instead of by position;
+#   - a stored blob still reproducing its failure after a new draw is
+#     inserted into the property, with the new draw's miss counted and
+#     reported instead of raised; and
+#   - the positional version of the same edit, where inserting a draw shifts
+#     every choice after it and the old blob stops meaning what it recorded.
+#
+# The scenario is a client's retry policy. Version 1 draws a timeout and a
+# retry count; the bug fires when the policy retries more than three times.
+# Version 2 inserts a TLS flag between them — the kind of unrelated question
+# a growing simulator adds every week.
+
+require "zizek"
+
+module KeyedDrawsExample
+  module_function
+
+  def check_policy(test_case, timeout, retries)
+    test_case.note("timeout=#{timeout}s retries=#{retries}")
+    raise "#{retries} retries would stampede the backend" if retries > 3
+  end
+
+  # Version 1: every decision is drawn under a stable name.
+  def keyed_v1
+    lambda do |test_case|
+      timeout = test_case.integer(1, 30, key: Zizek.key_hash(:timeout))
+      retries = test_case.integer(0, 9, key: Zizek.key_hash(:retries))
+      check_policy(test_case, timeout, retries)
+    end
+  end
+
+  # Version 2 inserts an unrelated keyed draw between the original two.
+  def keyed_v2
+    lambda do |test_case|
+      timeout = test_case.integer(1, 30, key: Zizek.key_hash(:timeout))
+      tls = test_case.boolean(key: Zizek.key_hash(:tls))
+      retries = test_case.integer(0, 9, key: Zizek.key_hash(:retries))
+      test_case.note("tls=#{tls}")
+      check_policy(test_case, timeout, retries)
+    end
+  end
+
+  # The same two versions, addressed positionally.
+  def positional_v1
+    lambda do |test_case|
+      timeout = test_case.integer(1, 30)
+      retries = test_case.integer(0, 9)
+      check_policy(test_case, timeout, retries)
+    end
+  end
+
+  def positional_v2
+    lambda do |test_case|
+      timeout = test_case.integer(1, 30)
+      tls = test_case.boolean
+      retries = test_case.integer(0, 9)
+      test_case.note("tls=#{tls}")
+      check_policy(test_case, timeout, retries)
+    end
+  end
+
+  def find_failure(property)
+    Zizek.check(property, examples: 300, seed: 5)
+    raise "the retry stampede should be discovered"
+  rescue Zizek::Failure => failure
+    failure
+  end
+
+  def replay(property, blob)
+    Zizek.check(property, reproduce: blob)
+    raise "the recorded failure should still reproduce"
+  rescue Zizek::Failure => failure
+    failure
+  end
+
+  # Find the bug in version 1, then replay its blob against version 2.
+  #
+  # The keyed pair: `timeout` and `retries` resolve by name, so they read
+  # exactly the values the blob recorded, wherever they now sit. The new
+  # `tls` draw has no entry under its name — that is an edit to the property,
+  # not a malformed blob — so it uses its simplest value and the failure
+  # reports one key miss.
+  def keyed_blob_survives_the_edit
+    found = find_failure(keyed_v1)
+    replayed = replay(keyed_v2, found.blob)
+    raise "expected exactly one key miss" unless replayed.key_misses == 1
+    raise "the recorded draws must be preserved" unless
+      replayed.notes.include?(found.notes.first)
+
+    [found, replayed]
+  end
+
+  # The same edit under positional addressing. The inserted boolean consumes
+  # the entry recorded for `retries`, every draw after it is off by one, and
+  # the stream ends before the property stops drawing: ReplayOverrun.
+  def positional_blob_breaks_on_the_edit
+    found = find_failure(positional_v1)
+    begin
+      Zizek.check(positional_v2, reproduce: found.blob)
+      raise "the shifted replay should not run to completion"
+    rescue Zizek::ReplayOverrun => overrun
+      [found, overrun]
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  puts "== keyed: the blob outlives the edit =="
+  found, replayed = KeyedDrawsExample.keyed_blob_survives_the_edit
+  puts "version 1 failure:\n#{found.message}"
+  puts "\nversion 2 replay of the same blob:\n#{replayed.message}"
+
+  puts "\n== positional: the same edit shifts every later draw =="
+  found, overrun = KeyedDrawsExample.positional_blob_breaks_on_the_edit
+  puts "version 1 failure:\n#{found.message}"
+  puts "\nversion 2 replay of the same blob: #{overrun.class}: #{overrun.message}"
+end

data/examples/ledger.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "zizek"
+
+module LedgerExample
+  LIMIT = 1_000_000
+  PORTABLE_LEDGER_FAILURE =
+    "AXicVYyxCQAgEAMvYmXtILr/cipq+C/ChRykA4K2w4eohyMuWU0ryUWvXBSLdK4FQmgBCA=="
+
+  class Ledger
+    attr_reader :balances
+
+    def initialize
+      @balances = {}
+    end
+
+    def credit(account, amount)
+      balances[account] = balances.fetch(account, 0) + amount
+    end
+
+    def debit(account, amount)
+      balances[account] = balances.fetch(account, 0) - amount
+    end
+
+    def transfer(source, destination, amount)
+      source_balance = balances.fetch(source, 0)
+      return unless source != destination && amount - source_balance <= 1
+
+      debit(source, amount)
+      credit(destination, amount)
+    end
+  end
+
+  class LedgerTest
+    def initialize(accounts)
+      @ledger = Ledger.new
+      @accounts = accounts
+    end
+
+    def create_account(test_case)
+      account = test_case.draw(Zizek::Generators.text.min_size(1))
+      test_case.note("create account #{account.inspect}")
+      @accounts.add(test_case, account)
+    end
+
+    def credit(test_case)
+      account = test_case.draw(@accounts.values_reusable)
+      amount = test_case.draw(Zizek::Generators.integers.min_value(0).max_value(LIMIT))
+      test_case.note("credit #{account.inspect} with #{amount}")
+      @ledger.credit(account, amount)
+    end
+
+    def transfer(test_case)
+      source = test_case.draw(@accounts.values_reusable)
+      destination = test_case.draw(@accounts.values_reusable)
+      amount = test_case.draw(Zizek::Generators.integers.min_value(0).max_value(LIMIT))
+      test_case.note("transfer #{amount} from #{source.inspect} to #{destination.inspect}")
+      @ledger.transfer(source, destination, amount)
+    end
+
+    def nonnegative_balances(_test_case)
+      @ledger.balances.each do |account, balance|
+        raise "account #{account.inspect} has negative balance #{balance}" if balance.negative?
+      end
+    end
+
+    def rules
+      [
+        Zizek::Stateful::Rule.new("create_account", ->(machine, test_case) { machine.create_account(test_case) }),
+        Zizek::Stateful::Rule.new("credit", ->(machine, test_case) { machine.credit(test_case) }),
+        Zizek::Stateful::Rule.new("transfer", ->(machine, test_case) { machine.transfer(test_case) })
+      ]
+    end
+
+    def invariants
+      [
+        Zizek::Stateful::Rule.new(
+          "nonnegative_balances",
+          ->(machine, test_case) { machine.nonnegative_balances(test_case) }
+        )
+      ]
+    end
+  end
+
+  module_function
+
+  def property(test_case)
+    Zizek::Stateful.run(
+      LedgerTest.new(Zizek::Stateful.pool(test_case)),
+      test_case
+    )
+  end
+
+  def find_and_replay_bug
+    found =
+      begin
+        Zizek.check(method(:property), examples: 2_000, seed: 1)
+        raise "the ledger off-by-one bug should be discovered"
+      rescue Zizek::Failure => failure
+        raise unless failure.property_cause.message.include?("negative balance")
+
+        failure
+      end
+
+    begin
+      Zizek.check(method(:property), reproduce: found.blob)
+    rescue Zizek::Failure
+      return found
+    end
+    raise "the shrunk ledger failure must replay"
+  end
+end
+
+puts LedgerExample.find_and_replay_bug if $PROGRAM_NAME == __FILE__

data/examples/min_stack.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Port of Hegel's minimum-stack state machine. MinStack deliberately forgets
+# duplicate minima: after push(0), push(0), pop, its cached minimum is empty
+# while the reference stack still contains zero.
+
+require "zizek"
+
+module MinStackExample
+  SHRUNK_MIN_STACK_FAILURE =
+    "AXicdYixCQAACIB0jf6/tyJoy0UxASVkWHnhd9oFC6sAWQ=="
+
+  class MinStack
+    attr_reader :stack
+
+    def initialize
+      @stack = []
+      @minimums = []
+    end
+
+    def push(value)
+      stack << value
+      @minimums << value if minimum.nil? || value < minimum
+    end
+
+    def pop
+      value = stack.pop
+      @minimums.pop if !value.nil? && minimum == value
+      value
+    end
+
+    def minimum
+      @minimums.last
+    end
+
+    def reference_minimum
+      stack.min
+    end
+  end
+
+  class MinStackTest
+    def initialize
+      @stack = MinStack.new
+    end
+
+    def push(test_case)
+      value = test_case.draw(Zizek::Generators.integers)
+      test_case.note("push #{value}")
+      @stack.push(value)
+    end
+
+    def pop(test_case)
+      test_case.note("pop #{@stack.pop.inspect}")
+    end
+
+    def minimums_agree(_test_case)
+      return if @stack.minimum == @stack.reference_minimum
+
+      raise "cached minimum #{@stack.minimum.inspect}, expected #{@stack.reference_minimum.inspect}"
+    end
+
+    def rules
+      [
+        Zizek::Stateful::Rule.new("push", ->(machine, test_case) { machine.push(test_case) }),
+        Zizek::Stateful::Rule.new("pop", ->(machine, test_case) { machine.pop(test_case) })
+      ]
+    end
+
+    def invariants
+      [
+        Zizek::Stateful::Rule.new(
+          "minimums_agree",
+          ->(machine, test_case) { machine.minimums_agree(test_case) }
+        )
+      ]
+    end
+  end
+
+  module_function
+
+  def property(test_case)
+    Zizek::Stateful.run(MinStackTest.new, test_case)
+  end
+
+  def find_and_replay_bug
+    found =
+      begin
+        Zizek.check(method(:property), examples: 2_000, seed: 1)
+        raise "the duplicate-minimum bug should be discovered"
+      rescue Zizek::Failure => failure
+        raise unless failure.property_cause.message.include?("cached minimum")
+        raise unless failure.blob == SHRUNK_MIN_STACK_FAILURE
+
+        failure
+      end
+
+    begin
+      Zizek.check(method(:property), reproduce: found.blob)
+    rescue Zizek::Failure => replayed
+      raise unless replayed.property_cause.message == found.property_cause.message
+
+      return found
+    end
+    raise "the shrunk min-stack failure must replay"
+  end
+end
+
+puts MinStackExample.find_and_replay_bug if $PROGRAM_NAME == __FILE__

data/examples/minitest_suite.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Properties as ordinary Minitest tests.
+#
+# Demonstrates:
+#   - `property` defining real test methods, collected by any runner;
+#   - named draws, so the failure names the values instead of the property
+#     having to `note` them;
+#   - a failed assertion reported as a Minitest failure, carrying the
+#     reproduce blob; and
+#   - per-property settings.
+#
+# Run it directly:
+#
+#   ruby -Ilib examples/minitest_suite.rb
+#
+# One test is expected to fail: that is the point of the example. It prints
+# the falsifying example and a blob you can paste into `reproduce:`.
+
+require "minitest/autorun"
+require "zizek/minitest"
+
+G = Zizek::Generators
+
+module Bill
+  module_function
+
+  # Split `total` cents between `people`, giving the remainder to nobody.
+  # The remainder is the bug: the parts do not add back up to the total.
+  def split(total, people)
+    Array.new(people, total / people)
+  end
+end
+
+class BillTest < Minitest::Test
+  include Zizek::Minitest
+
+  # Passing: every share is non-negative and no larger than the total.
+  property "shares stay within the bill",
+           total: G.integers(0..10_000),
+           people: G.integers(1..50) do |total, people|
+    shares = Bill.split(total, people)
+    assert_equal people, shares.length
+    shares.each do |share|
+      assert_operator share, :>=, 0
+      assert_operator share, :<=, total
+    end
+  end
+
+  # Failing: shrinks to the smallest bill that cannot be divided evenly.
+  property "the split is exact",
+           total: G.integers(0..10_000),
+           people: G.integers(1..50) do |total, people|
+    assert_equal total, Bill.split(total, people).sum
+  end
+
+  # A property that wants the test case itself gets it when no generators are
+  # named, and settings ride along under the reserved `settings:` keyword.
+  property "shares are stable across calls", settings: { examples: 250, seed: 11 } do |test_case|
+    total = test_case.draw(G.integers(0..1_000), name: :total)
+    people = test_case.draw(G.integers(1..20), name: :people)
+    assert_equal Bill.split(total, people), Bill.split(total, people)
+  end
+end