chaotic_job 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8241f1235f37ed46c1da18d53e18c6fce43fb5758273bb51dba8db332dddb5b6
-  data.tar.gz: fc86ee73cf18b16d6142f7111e5d1cfa446b46bfea2e1959eb7aa222a5bf42dd
+  metadata.gz: c84ddd59307328e8986c00f5c03da961e4d3910c4e42eb81f847e2703f2fe128
+  data.tar.gz: 9d65a1efddcb025569d5f97c8f87d3e5a920fee0c40f3b6d2bedf3f8c907b857
 SHA512:
-  metadata.gz: 7d32f1ab9748ea544d13c15692934634a6c3bcc01d602903e5e554abd229b7623a6a9aff111357031f474ec701fcd96131994604a121f9e55672eaed2616107b
-  data.tar.gz: c8ef73d8d07a091f59ebd1347ecc3f11fbd6ba6abc3eee218e251600ff156f748ec2a911d8108834cad96f9ce7ef59d1b3989606a27a827f1bb7bd93bfd9b062
+  metadata.gz: e1fe18d93d38e9e15ecb011fc578b94543b2fd8c83c017d7df3f69d0ad243d7f676e8892562c346b07e0b86631891d16465f358c5c5999b639191cad34796543
+  data.tar.gz: 6837ab188e03fc32cb66feb689f561bc3a7e37dd98bbdff412504876f713d6d1ac4721b4cd4d0bd217a0423cfe938064b441203cd70b60f8c2bf1fe66b687502

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.3.0] - 2024-12-17
+
+- Ensure that assertion failure messages raised within a simulation contain the scenario description
+- Add a `ChaoticJob.journal_entries` top-level method
+
 ## [0.2.0] - 2024-11-06
 
 - Update the `perform_all` helper method to `perform_all_jobs`

data/README.md

@@ -42,6 +42,10 @@ end
 
 The `ChaoticJob::Helpers` module provides 6 methods, 4 of which simply allow you to perform a job with retries in the proper way while the other 2 allow you to simulate failures and glitches.
 
+### Glitches
+
+A central concept in `ChaoticJob` is the _glitch_. A glitch is an error injected into the job execution flow via a [`TracePoint`](https://docs.ruby-lang.org/en/master/TracePoint.html). Glitches are transient errors, which means they occur once and only once, making them perfect for testing a job's resilience to unpredictable failures that can occur while running jobs, like network issues, upstream API outages, rate limits, or  infrastructure failure. By default, `ChaoticJob` raises a custom error defined by the gem (`ChaoticJob::RetryableError`), which the internals of the gem ensure that the job under test is configured to retry on; you can, however, raise specific errors as needed when setting up your [scenarios](#simulating-failures). By forcing a retry via the error handling mechanisms of Active Job, glitches are a simple but effective way to test that your job is resilient to any kind of transient error that the job is configured to retry on.
+
 ### Performing Jobs
 
 When testing job resilience, you will necessarily be testing how a job behaves when it retries. Unfortunately, the helpers provided by `ActiveJob::TestHelper` are tailored to testing the job's behavior on the first attempt.
@@ -120,7 +124,7 @@ end
 > | `Journal.entries` | get all of the logged values under the default scope |
 > | `Journal.entries(scope: :special)` | get all of the logged values under a particular scope |
 
-In this example, the job being tested is defined within the test case. You can, of course, also test jobs defined in your application. The key detail is the `glitch` keyword argument. A "glitch" is simply a tuple that describes precisely where you would like the failure to occur. The first element of the tuple is the location of the glitch, which can be either *before* or *after*. The second element is the location of the code that will be affected by the glitch, defined by its file path and line number. What this example scenario does is inject a glitch before the `step_3` method is called, here:
+In this example, the job being tested is defined within the test case. You can, of course, also test jobs defined in your application. The key detail is the `glitch` keyword argument. A "glitch" is simply a tuple that describes precisely where you would like the failure to occur. The first element of the tuple is the location of the glitch, which can be either *before* or *after* a line of code. The second element is the location of the code that will be affected by the glitch, defined by its file path and line number. What this example scenario does is inject a glitch before the `step_3` method is called, here:
 
 ```ruby
 def perform
@@ -131,8 +135,6 @@ def perform
 end
 ```
 
-This glitch is a transient error, which are the only kind of errors that matter when testing resilience, as permanent errors mean your job will simply end up in the dead set. So, the glitch failure will occur once and only once, this forces a retry but does not prevent the job from completing.
-
 If you want to simulate multiple glitches affecting a job run, you can use the plural `glitches` keyword argument instead and pass an array of tuples:
 
 ```ruby

data/lib/chaotic_job/simulation.rb

@@ -84,9 +84,12 @@ module ChaoticJob
     def run_scenario(scenario, &callback)
       debug "👾 Running simulation with scenario: #{scenario}"
       @test.before_setup
+      @test.simulation_scenario = scenario.to_s
       scenario.run
       @test.after_teardown
       callback.call(scenario)
+    ensure
+      @test.simulation_scenario = nil
     end
 
     def clone_job_template

data/lib/chaotic_job/version.rb

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

data/lib/chaotic_job.rb

@@ -23,6 +23,14 @@ module ChaoticJob
     end
   end
 
+  def self.journal_entries(scope: nil)
+    if scope
+      Journal.entries(scope: scope)
+    else
+      Journal.entries
+    end
+  end
+
   def self.journal_size(scope: nil)
     if scope
       Journal.size(scope: scope)
@@ -40,6 +48,8 @@ module ChaoticJob
   end
 
   module Helpers
+    attr_accessor :simulation_scenario
+
     def perform_all_jobs
       Performer.perform_all
     end
@@ -58,6 +68,7 @@ module ChaoticJob
       kwargs = {test: self, seed: seed}
       kwargs[:depth] = depth if depth
       kwargs[:variations] = variations if variations
+      self.simulation_scenario = nil
       Simulation.new(job, **kwargs).run(&block)
     end
 
@@ -71,5 +82,19 @@ module ChaoticJob
         Scenario.new(job, **kwargs).run
       end
     end
+
+    def assert(test, msg = nil)
+      return super unless @simulation_scenario
+
+      contextual_msg = lambda do
+        # copied from the original `assert` method in Minitest::Assertions
+        default_msg = "Expected #{mu_pp test} to be truthy."
+        custom_msg = original_msg.is_a?(Proc) ? original_msg.call : original_msg
+        full_msg = custom_msg || default_msg
+        "  #{@simulation_scenario}\n#{full_msg}"
+      end
+
+      super(test, contextual_msg)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chaotic_job
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
+original_platform: ''
 authors:
 - Stephen Margheim
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-07 00:00:00.000000000 Z
+date: 2024-12-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -24,7 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-description:
 email:
 - stephen.margheim@gmail.com
 executables: []
@@ -52,7 +51,6 @@ metadata:
   homepage_uri: https://github.com/fractaledmind/chaotic_job
   source_code_uri: https://github.com/fractaledmind/chaotic_job
   changelog_uri: https://github.com/fractaledmind/chaotic_job/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -67,8 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.21
-signing_key:
+rubygems_version: 3.6.0
 specification_version: 4
 summary: Test ActiveJobs for reliability and resilience.
 test_files: []