chaotic_job 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10db3cce1a0eedffe044477a348122d781e19cfbb6f561c9e389926d7de21153
-  data.tar.gz: a48f0d63526613593a25cc92d1c3eca794adb99466ef697a3c932e581a08434a
+  metadata.gz: eb8c72d5ca7192303c7c337d472c3eb6b02d3fc42eca6261dde846246b6526c6
+  data.tar.gz: 34726750b6c695d27f7d9b9260ad45a31710f7f870444d4ce5b2ca2f167cdd97
 SHA512:
-  metadata.gz: a1ea02d93adf652616f25478c8d7f628f30d56137485b10988bd2f08b9a62153327cd60c787555d7ba4286a7c26f94616ee45c92a58778e0689011461a39bb3b
-  data.tar.gz: 6d94662caef5559bca3de08c69674ad10dd4fa349fbd8434a42dc65c8baa8ba6da13f6cc8d13b9af815f4610148a874ba3f9fa0b9e5c8aa97e7b131afc5c3689
+  metadata.gz: 92a1d4958ab971e5850b0f60770fbf09c0c2556cdf25eb9cf23d494f8dabdce660ebd47718bb590b65d124c096d2bca391b4198bcbef6b241fe4b11c26468239
+  data.tar.gz: 319f7d9d1fa9f78c5490a5e48a58e464907432cdb018a298d365d84a8e514ac7791ea92f8fcc54e275da36da85b4ad411e21406ac46a8ad19c03d1054d478bbd

data/.standard.yml

@@ -5,3 +5,5 @@ ruby_version: 3.0
 ignore:
   - 'test/**/*':
     - Lint/ConstantDefinitionInBlock
+  - 'lib/**/*':
+    - Style/YodaCondition

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.8.0] - 2025-06-11
+
+- Add methods to allow checking if a Scenario matches a particular Glitch key + event pair [#10](https://github.com/fractaledmind/chaotic_job/pull/10)
+
+## [0.7.0] - 2025-06-09
+
+- Glitch only works with singular event + key definition [#6](https://github.com/fractaledmind/chaotic_job/pull/6)
+- Scenarios assert the glitch was executed [#7](https://github.com/fractaledmind/chaotic_job/pull/7)
+- Add helper methods to create a Glitch of the various kinds [#8](https://github.com/fractaledmind/chaotic_job/pull/8)
+- Improve test coverage [#9](https://github.com/fractaledmind/chaotic_job/pull/9)
+
 ## [0.6.0] - 2025-06-08
 
 - `run_scenario` requires a Glitch instance [#5](https://github.com/fractaledmind/chaotic_job/pull/5)

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/chaotic_job.svg)](https://rubygems.org/gems/chaotic_job)
 [![Gem Downloads](https://img.shields.io/gem/dt/chaotic_job)](https://rubygems.org/gems/chaotic_job)
 ![Tests](https://github.com/fractaledmind/chaotic_job/actions/workflows/main.yml/badge.svg)
-![Coverage](https://img.shields.io/badge/code%20coverage-92%25-success)
+![Coverage](https://img.shields.io/badge/code%20coverage-98%25-success)
 [![Sponsors](https://img.shields.io/github/sponsors/fractaledmind?color=eb4aaa&logo=GitHub%20Sponsors)](https://github.com/sponsors/fractaledmind)
 [![Twitter Follow](https://img.shields.io/twitter/url?label=%40fractaledmind&style=social&url=https%3A%2F%2Ftwitter.com%2Ffractaledmind)](https://twitter.com/fractaledmind)
 
@@ -167,17 +167,6 @@ Finally, if you need to inject a glitch right before a particular line of code i
 run_scenario(Job.new, glitch: ChaoticJob::Glitch.before_line("#{__FILE__}:6"))
 ```
 
-If you want to simulate multiple glitches affecting a job run, you simply define additional failure points using the fluid interface of the `ChaoticJob::Glitch` class:
-
-```ruby
-run_scenario(
-  Job.new,
-  glitch: ChaoticJob::Glitch
-    .before_call("Job#step_1")
-    .before_return("Job#step_3")
-)
-```
-
 Scenario testing is useful to test the behavior of a job under a specific set of conditions. But, if you want to test the behavior of a job under a variety of conditions, you can use the `run_simulation` method. Instead of running a single scenario, a simulation will run the full set of possible error scenarios for your job.
 
 ```ruby
@@ -203,23 +192,21 @@ end
 More specifically, it will create a scenario injecting a glitch before every line of code executed in your job. So, in this example, the simulation will run 12 scenarios:
 
 ```ruby
-[
-  [[:before_line, "test_chaotic_job.rb:69"]],
-  [[:before_line, "test_chaotic_job.rb:75"]],
-  [[:before_line, "test_chaotic_job.rb:74"]],
-  [[:before_line, "test_chaotic_job.rb:74"]],
-  [[:before_line, "test_chaotic_job.rb:68"]],
-  [[:before_line, "test_chaotic_job.rb:70"]],
-  [[:before_line, "test_chaotic_job.rb:68"]],
-  [[:before_line, "test_chaotic_job.rb:73"]],
-  [[:before_line, "test_chaotic_job.rb:75"]],
-  [[:before_line, "test_chaotic_job.rb:69"]],
-  [[:before_line, "test_chaotic_job.rb:70"]],
-  [[:before_line, "test_chaotic_job.rb:73"]]
-]
-```
-
-It generates all possible glitch scenarios by performing your job once with a [`TracePoint`](https://docs.ruby-lang.org/en/master/TracePoint.html) that captures each line executed in your job. It then computes all possible glitch locations to produce a set of scenarios that will be run. The block that you pass to `run_simulation` will be called for each scenario, allowing you to make assertions about the behavior of your job under all scenarios.
+#<Set:
+ {[:call, "Job#perform"],
+  [:line, "file.rb:3"],
+  [:call, "Job#step_1"],
+  [:return, "Job#step_1"],
+  [:line, "file.rb:4"],
+  [:call, "Job#step_2"],
+  [:return, "Job#step_2"],
+  [:line, "file.rb:5"],
+  [:call, "Job#step_3"],
+  [:return, "Job#step_3"],
+  [:return, "Job#perform"]}>
+```
+
+It generates all possible glitch scenarios by performing your job once with a [`TracePoint`](https://docs.ruby-lang.org/en/master/TracePoint.html) that captures every event executed as a part of your job running. The block that you pass to `run_simulation` will be called for each scenario, allowing you to make assertions about the behavior of your job under all scenarios.
 
 If you want to have the simulation run against a larger collection of scenarios, you can capture a custom callstack using the `ChaoticJob::Tracer` class and pass it to the `run_simulation` method as the `callstack` parameter. A `Tracer` is initialized with a block that determines which `TracePoint` events to collect. You then call `capture` with a block that defines the code to be traced. The default `Simulation` tracer collects all events for the passed job and then traces the job execution, essentially like this:
 

data/lib/chaotic_job/glitch.rb

@@ -8,81 +8,59 @@
 module ChaoticJob
   class Glitch
     def self.before_line(key, &block)
-      new.before_line(key, &block)
+      new(key, :line, &block)
     end
 
     def self.before_call(key, ...)
-      new.before_call(key, ...)
+      new(key, :call, ...)
     end
 
     def self.before_return(key, return_type = nil, &block)
-      new.before_return(key, return_type, &block)
+      new(key, :return, retval: return_type, &block)
     end
 
-    def initialize
-      @breakpoints = {}
-    end
-
-    def before_line(key, &block)
-      set_breakpoint(key, :line, &block)
-      self
-    end
+    attr_reader :key, :event
 
-    def before_call(key, ...)
-      set_breakpoint(key, :call, ...)
-      self
-    end
-
-    def before_return(key, return_type = nil, &block)
-      set_breakpoint(key, :return, retval: return_type, &block)
-      self
+    def initialize(key, event, *args, retval: nil, **kwargs, &block)
+      @event = event
+      @key = key
+      @args = args
+      @retval = retval
+      @kwargs = kwargs
+      @block = block
+      @executed = false
     end
 
     def set_action(force: false, &block)
-      @breakpoints.each do |_key, handlers|
-        handlers.each do |_event, handler|
-          handler[:block] = block if handler[:block].nil? || force
-        end
-      end
-      self
+      @block = block if @block.nil? || force
     end
 
     def inject!(&block)
-      breakpoints = @breakpoints
-
-      trace = TracePoint.new(:line, :call, :return) do |tp|
+      trace = TracePoint.new(@event) do |tp|
         # :nocov: SimpleCov cannot track code executed _within_ a TracePoint
         key = derive_key(tp)
-        matchers = derive_matchers(tp)
+        next unless @key == key
 
-        next unless (defn = breakpoints.dig(key, tp.event))
-        next unless matches?(defn, matchers)
+        matchers = derive_matchers(tp)
+        next unless matches?(matchers)
 
-        execute_block(defn)
+        execute_block
         # :nocov:
       end
 
       trace.enable(&block)
     end
 
-    def all_executed?
-      @breakpoints.all? do |_key, handlers|
-        handlers.all? { |_event, handler| handler[:executed] }
-      end
+    def executed?
+      @executed
     end
 
     private
 
-    def set_breakpoint(key, event, *args, retval: nil, **kwargs, &block)
-      @breakpoints[key] ||= {}
-      @breakpoints[key][event] = {args: args, kwargs: kwargs, retval: retval, block: block, executed: false}
-    end
-
     # :nocov: SimpleCov cannot track code executed _within_ a TracePoint
-    def matches?(defn, matchers)
-      return true if defn.nil?
+    def matches?(matchers)
       return true if matchers.nil?
-      return true if defn[:args].empty? && defn[:kwargs].empty? && defn[:retval].nil?
+      return true if @args.empty? && @kwargs.empty? && @retval.nil?
 
       args = []
       kwargs = {}
@@ -107,25 +85,24 @@ module ChaoticJob
         end
       end
 
-      defn[:args].each_with_index do |type, index|
+      @args.each_with_index do |type, index|
         return false unless type === args[index]
       end
 
-      defn[:kwargs].each do |key, type|
+      @kwargs.each do |key, type|
         return false unless type === kwargs[key]
       end
 
-      return false unless defn[:retval] === retval
+      return false unless @retval === retval
 
       true
     end
 
-    def execute_block(handler)
-      return unless handler
-      return if handler[:executed]
+    def execute_block
+      return if @executed
 
-      handler[:executed] = true
-      handler[:block].call
+      @executed = true
+      @block.call
     end
 
     def derive_key(trace)

data/lib/chaotic_job/performer.rb

@@ -76,8 +76,11 @@ module ChaoticJob
         cutoff.from_now
       in Time
         cutoff
+      else
+        raise Error.new("cutoff must be Time or ActiveSupport::Duration, but got #{cutoff.inspect}")
       end
       delta = (Time.now - time).abs.floor
+
       changeset = case delta
       when 0..59                    # seconds
         {usec: 0}
@@ -85,7 +88,7 @@ module ChaoticJob
         {sec: 0, usec: 0}
       when 3600..86_399             # hours
         {min: 0, sec: 0, usec: 0}
-      when 86_400..Float::INFINITY  # days+
+      else  # days+
         {hour: 0, min: 0, sec: 0, usec: 0}
       end
       time.change(**changeset)

data/lib/chaotic_job/scenario.rb

@@ -5,7 +5,7 @@
 
 module ChaoticJob
   class Scenario
-    attr_reader :events
+    attr_reader :events, :glitch, :job
 
     def initialize(job, glitch:, raise: RetryableError, capture: /active_job/)
       @job = job
@@ -30,11 +30,29 @@ module ChaoticJob
         end
       end
 
-      # TODO: assert that all glitch ran
+      self
     end
 
-    def all_glitched?
-      @glitch.all_executed?
+    def glitched?
+      @glitch.executed?
+    end
+
+    def before_line?(key)
+      return false unless :line == @glitch.event
+
+      key == @glitch.key
+    end
+
+    def before_call?(key)
+      return false unless :call == @glitch.event
+
+      key == @glitch.key
+    end
+
+    def before_return?(key)
+      return false unless :return == @glitch.event
+
+      key == @glitch.key
     end
   end
 end

data/lib/chaotic_job/simulation.rb

@@ -1,54 +1,47 @@
 # frozen_string_literal: true
 
 # Simulation.new(job).run { |scenario| ... }
-# Simulation.new(job).permutations
 # Simulation.new(job).variants
 # Simulation.new(job).scenarios
 module ChaoticJob
   class Simulation
-    def initialize(job, callstack: nil, depth: 1, variations: 100, test: nil, seed: nil)
+    def initialize(job, callstack: nil, variations: nil, test: nil, seed: nil)
       @template = job
       @callstack = callstack || capture_callstack
-      @depth = depth
       @variations = variations
       @test = test
       @seed = seed || Random.new_seed
       @random = Random.new(@seed)
 
-      raise Error.new("callstack must be a generated via the ChaoticJob::Tracer") unless @callstack.is_a?(Stack)
+      raise Error.new("callstack must be a generated via ChaoticJob::Tracer") unless @callstack.is_a?(Stack)
     end
 
-    def run(&callback)
-      @template.class.retry_on RetryableError, attempts: @depth + 2, wait: 1, jitter: 0
+    def run(&assertions)
+      @template.class.retry_on RetryableError, attempts: 3, wait: 1, jitter: 0
 
-      debug "👾 Running #{variants.size} simulations of the total #{permutations.size} possibilities..."
+      debug "👾 Running #{@variations || "all"} simulations of the total #{variants.size} possibilities..."
 
       scenarios.map do |scenario|
-        run_scenario(scenario, &callback)
+        run_scenario(scenario, &assertions)
         print "·"
       end
     end
 
-    def permutations
+    def variants
       error_locations = @callstack.map do |event, key|
         ["before_#{event}", key]
       end
-      error_locations.permutation(@depth)
-    end
 
-    def variants
-      return permutations if @variations.nil?
+      return error_locations if @variations.nil?
 
-      permutations.to_a.sample(@variations, random: @random)
+      error_locations.sample(@variations, random: @random)
     end
 
     def scenarios
-      variants.map do |glitches|
+      variants.map do |(event, key)|
         job = clone_job_template
-        glitch = Glitch.new.tap { |g| glitches.each { |event, key| g.public_send(event, key) } }
-        scenario = Scenario.new(job, glitch: glitch)
-        job.job_id = scenario.to_s
-        scenario
+        glitch = Glitch.public_send(event, key)
+        Scenario.new(job, glitch: glitch)
       end
     end
 
@@ -64,13 +57,14 @@ module ChaoticJob
       callstack
     end
 
-    def run_scenario(scenario, &callback)
+    def run_scenario(scenario, &assertions)
       debug "👾 Running simulation with scenario: #{scenario}"
       @test.before_setup
-      @test.simulation_scenario = scenario.to_s
+      @test.simulation_scenario = scenario
       scenario.run
       @test.after_teardown
-      callback.call(scenario)
+      @test.assert scenario.glitched?, "Scenario did not execute glitch: #{scenario.glitch}"
+      assertions.call(scenario)
     ensure
       @test.simulation_scenario = nil
     end

data/lib/chaotic_job/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChaoticJob
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/chaotic_job.rb

@@ -66,10 +66,9 @@ module ChaoticJob
       Performer.perform_all_after(time)
     end
 
-    def run_simulation(job, depth: nil, variations: nil, callstack: nil, &block)
+    def run_simulation(job, variations: nil, callstack: nil, &block)
       seed = defined?(RSpec) ? RSpec.configuration.seed : Minitest.seed
       kwargs = {test: self, seed: seed}
-      kwargs[:depth] = depth if depth
       kwargs[:variations] = variations if variations
       kwargs[:callstack] = callstack if callstack
       self.simulation_scenario = nil
@@ -90,7 +89,17 @@ module ChaoticJob
       end
     end
 
-    private
+    def glitch_before_line(key, &block)
+      Glitch.before_line(key, &block)
+    end
+
+    def glitch_before_call(key, ...)
+      Glitch.before_call(key, ...)
+    end
+
+    def glitch_before_return(key, return_type = nil, &block)
+      Glitch.before_return(key, return_type, &block)
+    end
 
     def assert(test, msg = nil)
       return super unless @simulation_scenario
@@ -100,7 +109,8 @@ module ChaoticJob
         default_msg = "Expected #{mu_pp test} to be truthy."
         custom_msg = msg.is_a?(Proc) ? msg.call : msg
         full_msg = custom_msg || default_msg
-        "  #{@simulation_scenario}\n#{full_msg}"
+        indented_scenario = @simulation_scenario.to_s.split("\n").join("\n  ")
+        "  #{indented_scenario}\n#{full_msg}"
       end
 
       super(test, contextual_msg)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: chaotic_job
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Stephen Margheim
 bindir: exe
 cert_chain: []
-date: 2025-06-08 00:00:00.000000000 Z
+date: 2025-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob