Merge pull request #28 from joelhelbling/feat/policy-testing-harness

Handoff immutability policies, Phase 2: testing harness & mutation detector

Author: joelhelbling

lib/shifty/rspec.rb

@@ -0,0 +1,37 @@
+require "shifty/testing"
+
+# Opt-in RSpec sugar for testing Shifty workers under handoff policies.
+# `require "shifty/rspec"` from your spec_helper; assumes RSpec is loaded.
+
+RSpec::Matchers.define :mutate_input do |input|
+  match do |worker|
+    Shifty::Testing.mutates_input?(worker, input)
+  end
+
+  failure_message do |worker|
+    "expected the worker's task to mutate its input #{input.inspect}, but it did not"
+  end
+
+  failure_message_when_negated do |worker|
+    "expected the worker's task not to mutate its input, but it mutated " \
+      "#{input.inspect}. It is only correct under policy :isolated (mutation " \
+      "stays local) or :shared (mutation is intentional); it will raise under :frozen."
+  end
+end
+
+# Runs the worker through the framework against deeply frozen input —
+# the strictest policy — proving the task is non-destructive and therefore
+# correct under every policy (§9.4, "test at the ceiling").
+#
+# Expects `worker` and `safe_input` to be defined with `let`.
+RSpec.shared_examples "a policy-safe worker" do
+  it "processes a deeply frozen input without raising" do
+    expect {
+      Shifty::Testing.run(worker, inputs: [safe_input], policy: :frozen)
+    }.not_to raise_error
+  end
+
+  it "does not mutate its input" do
+    expect(worker).not_to mutate_input(safe_input)
+  end
+end

lib/shifty/testing.rb

@@ -0,0 +1,82 @@
+require "shifty"
+
+module Shifty
+  # Test harness: runs a worker through the framework so unit tests
+  # exercise the same handoff policy the production pipeline will.
+  # Deliberately not loaded by `require "shifty"` — opt in with
+  # `require "shifty/testing"`.
+  module Testing
+    class << self
+      # Feeds the inputs to the worker via a source and collects its
+      # outputs until the end-of-stream sentinel (nil). The worker's
+      # declared/effective policy governs each handoff, exactly as in
+      # production; pass policy: to override it for policy-matrix tests.
+      def run(worker, inputs:, policy: nil, max_shifts: 10_000)
+        harness(worker, policy) do |subject|
+          subject.supply = source_for(inputs)
+          outputs = []
+          shifts = 0
+          until (value = subject.shift).nil?
+            outputs << value
+            if (shifts += 1) > max_shifts
+              raise Error, "Shifty::Testing.run exceeded #{max_shifts} shifts " \
+                "without seeing the nil end-of-stream sentinel. The worker's " \
+                "task probably converts nil into a non-nil value; let nil " \
+                "pass through (e.g. `value && ...`), or raise max_shifts:."
+            end
+          end
+          outputs
+        end
+      end
+
+      # The mutation detector (§6.4): hands the task a private mutable
+      # deep copy and reports whether the task changed it — surfacing
+      # mutation even when the current policy permits or hides it.
+      def mutates_input?(worker, input)
+        copy = begin
+          Marshal.load(Marshal.dump(input))
+        rescue TypeError => e
+          raise Error, "Shifty::Testing.mutates_input? needs a deep-copyable " \
+            "(Marshal-dumpable) input, but got an instance of #{input.class} " \
+            "(#{e.message})."
+        end
+        baseline = Marshal.dump(copy)
+        harness(worker, :shared) do |subject|
+          subject.supply = source_for([copy])
+          subject.shift
+        end
+        Marshal.dump(copy) != baseline
+      end
+
+      private
+
+      # Temporarily rewires the caller's actual worker (a dup would defeat
+      # task closures that reference their own worker, e.g. side_worker's
+      # policy check) and restores its policy, supply, and Fiber afterward,
+      # so the harness never leaves a mark on the worker under test.
+      def harness(worker, policy)
+        saved = {
+          policy: worker.instance_variable_get(:@policy),
+          supply: worker.instance_variable_get(:@supply),
+          fiber: worker.instance_variable_get(:@my_little_machine)
+        }
+        worker.instance_variable_set(:@policy, Policy.validate!(policy)) if policy
+        worker.instance_variable_set(:@my_little_machine, nil)
+        worker.instance_variable_set(:@supply, nil)
+        yield worker
+      ensure
+        worker.instance_variable_set(:@policy, saved[:policy])
+        worker.instance_variable_set(:@supply, saved[:supply])
+        worker.instance_variable_set(:@my_little_machine, saved[:fiber])
+      end
+
+      def source_for(inputs)
+        series = inputs.dup
+        Worker.new(tags: [:source]) do
+          series.each { |input| Fiber.yield input }
+          loop { Fiber.yield nil }
+        end
+      end
+    end
+  end
+end

spec/shifty/rspec_sugar_spec.rb

@@ -0,0 +1,29 @@
+require "spec_helper"
+require "shifty/rspec"
+
+module Shifty
+  RSpec.describe "shifty/rspec sugar" do
+    include DSL
+
+    describe "the mutate_input matcher" do
+      context "detects a mutating worker" do
+        Given(:worker) { side_worker(policy: :shared) { |v| v << :boo } }
+        Then { expect(worker).to mutate_input([:a]) }
+      end
+
+      context "passes a non-destructive worker" do
+        Given(:worker) { relay_worker { |v| v + [:x] } }
+        Then { expect(worker).not_to mutate_input([:a]) }
+      end
+    end
+
+    describe %(the "a policy-safe worker" shared example) do
+      context "with a non-destructive worker" do
+        it_behaves_like "a policy-safe worker" do
+          let(:worker) { Shifty::Worker.new { |v| v&.to_s } }
+          let(:safe_input) { [:a] }
+        end
+      end
+    end
+  end
+end

spec/shifty/testing_spec.rb

@@ -0,0 +1,93 @@
+require "spec_helper"
+require "shifty/testing"
+
+module Shifty
+  RSpec.describe Testing do
+    include DSL
+
+    after { Shifty.reset_configuration! }
+
+    describe ".run" do
+      context "feeds inputs through the framework and collects outputs" do
+        Given(:worker) { relay_worker { |v| v.upcase } }
+        When(:outputs) { Testing.run(worker, inputs: ["a", "b", "c"]) }
+        Then { expect(outputs).to eq(["A", "B", "C"]) }
+      end
+
+      context "exercises the worker's effective policy (parity with production)" do
+        Given(:mutator) { Worker.new { |v| v && v << :x } }
+        Then do
+          expect { Testing.run(mutator, inputs: [[:a]]) }
+            .to raise_error(PolicyViolation)
+        end
+      end
+
+      context "a worker declaring :isolated runs under :isolated" do
+        Given(:mutator) { Worker.new(policy: :isolated) { |v| v && v << :x } }
+        When(:outputs) { Testing.run(mutator, inputs: [[:a]]) }
+        Then { expect(outputs).to eq([[:a, :x]]) }
+      end
+
+      context "an explicit policy: override beats the worker's own declaration" do
+        Given(:mutator) { Worker.new(policy: :shared) { |v| v && v << :x } }
+        Then do
+          expect { Testing.run(mutator, inputs: [[:a]], policy: :frozen) }
+            .to raise_error(PolicyViolation)
+        end
+        And { expect(mutator.effective_policy).to eq(:shared) }
+      end
+
+      context "false is a legitimate payload, not end-of-stream" do
+        # relay_worker's `value &&` guard passes false through untouched,
+        # so the negator applies only to the two true inputs.
+        Given(:flipper) { relay_worker { |v| !v } }
+        When(:outputs) { Testing.run(flipper, inputs: [true, false, true]) }
+        Then { expect(outputs).to eq([false, false, false]) }
+        And { expect(outputs.length).to eq(3) }
+      end
+
+      context "raises a diagnostic when a worker never passes the nil sentinel through" do
+        Given(:worker) { Worker.new { |v| v.to_s } }
+        Then do
+          expect { Testing.run(worker, inputs: [:a], max_shifts: 50) }
+            .to raise_error(Shifty::Error, /end-of-stream sentinel/)
+        end
+      end
+
+      context "collects a non-1:1 output stream (filter) until end of stream" do
+        Given(:evens) { filter_worker { |v| v.even? } }
+        When(:outputs) { Testing.run(evens, inputs: [1, 2, 3, 4]) }
+        Then { expect(outputs).to eq([2, 4]) }
+      end
+    end
+
+    describe ".mutates_input?" do
+      context "an undumpable input raises a descriptive error" do
+        Given(:worker) { relay_worker { |v| v } }
+        Then do
+          expect { Testing.mutates_input?(worker, proc {}) }
+            .to raise_error(Shifty::Error, /deep-copyable/)
+        end
+      end
+
+      context "a mutating task is detected" do
+        Given(:worker) { Worker.new(policy: :shared) { |v| v << :x } }
+        Then { expect(Testing.mutates_input?(worker, [:a])).to be true }
+      end
+
+      context "a non-destructive task is not" do
+        Given(:worker) { relay_worker { |v| v + [:x] } }
+        Then { expect(Testing.mutates_input?(worker, [:a])).to be false }
+      end
+
+      context "detects mutation even when the worker's own policy would hide it" do
+        Given(:worker) { side_worker(policy: :isolated) { |v| v << :boo } }
+        Then { expect(Testing.mutates_input?(worker, [:a])).to be true }
+      end
+    end
+
+    describe "opt-in loading" do
+      Then { expect(File.read(File.expand_path("../../lib/shifty.rb", __dir__))).not_to match(%r{shifty/(testing|rspec)}) }
+    end
+  end
+end