specbandit 0.12.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82b0e7cfc34d8564657fc313dc9f0e4432a8c7c88795690670da3f86a21acd64
-  data.tar.gz: 321f4437b8a265664b72f30cd38f03cdd5b03f5f7814d00f608096a6fa47b19c
+  metadata.gz: 14a1d9a07eb3ab1b19c59c9e054aec4fb32e5da1ac3f33841feb1fb068085648
+  data.tar.gz: 756a15f2a9c7f9cce3db7fa06e499235fd18ec332a51d6db1900ee1a9a2d1fb8
 SHA512:
-  metadata.gz: f3e05b5368da44a918d66432edd5985cfb461f9505f1a47ba56b4d7e599cdae48395a9e5b8da5bbd015c9d1540a567ea97d719ef40004fe36238c5afe013adc9
-  data.tar.gz: a5cc4f6d8844a31f9f98eb6caf5928424cccf2d4fa662d06f7a853a095ff6c8a1ef155169eaea659fb7c2e57a38d1e2c76f67dd9723260fca0bc6b410ea27eb3
+  metadata.gz: 6bc49db9d7bd80540b17d19b15fb759a2ab0c1c867026f3234610074323237cf4cd5ee8d7e590c472b324dbc152b0db83d35fa05bbf443175efad1f5fc658c1c
+  data.tar.gz: '09cdd5433154bc6a35d13006beccdcba288d8538fc79585e79b8939edf1a0c2e1149d98d21cbdc8ee4eb7f756640d00575b4ebb3791217f5359c511a8ddea6a0'

data/README.md

@@ -318,6 +318,8 @@ Specbandit detects the mode automatically based on the state of `--key-rerun`:
 | Yes | Empty | Yes | **Fail** | Exit 1 with error. Prevents silent false pass on stale re-runs. |
 | No | -- | Yes | **Error** | Validation error: `--rerun` requires `--key-rerun`. |
 
+> **Empty key names count as "not provided".** A `--key-rerun` whose value is an empty string -- e.g. `--key-rerun "$VAR"` where `$VAR` is unset in CI -- is treated exactly like `--key-rerun` being absent (the **No** rows above), not as a configured-but-empty key. Combined with `--rerun`, that means an empty/unset name fails hard (exit 1) rather than silently steal-and-pass. The same applies to `--key-failed`: an empty/unset name is treated as "not configured" and no failed files are recorded.
+
 #### The `--rerun` safety flag
 
 Without `--rerun`, specbandit cannot distinguish a first run from a re-run when the rerun key is empty (e.g., TTL expired or Redis was flushed). In that case it silently falls back to Record mode, which may find an empty shared queue and exit 0 with zero tests -- a **silent false pass**.

data/lib/specbandit/cli.rb

@@ -123,10 +123,22 @@ module Specbandit
           Specbandit.configuration.key_rerun_ttl = v
         end
 
+        opts.on('--key-failed KEY', 'Redis key to record failed test files for later review') do |v|
+          Specbandit.configuration.key_failed = v
+        end
+
+        opts.on('--key-failed-ttl SECONDS', Integer, 'TTL for failed key in seconds (default: 604800 / 1 week)') do |v|
+          Specbandit.configuration.key_failed_ttl = v
+        end
+
         opts.on('--rerun', 'Signal this is a re-run (fail hard if rerun key is empty)') do
           Specbandit.configuration.rerun = true
         end
 
+        opts.on('--report FILE', 'Write JSON report with run statistics to FILE') do |v|
+          Specbandit.configuration.report = v
+        end
+
         opts.on('--verbose', 'Show per-batch file list and full command output (default: quiet)') do
           Specbandit.configuration.verbose = true
         end
@@ -207,9 +219,12 @@ module Specbandit
           --rspec-opts OPTS      Extra options forwarded to RSpec (for rspec adapter)
           --batch-size N         Files per batch (default: 5, or set SPECBANDIT_BATCH_SIZE)
           --redis-url URL        Redis URL (default: redis://localhost:6379)
-          --key-rerun KEY        Per-runner rerun key for re-run support
-          --key-rerun-ttl N      TTL for rerun key (default: 604800 / 1 week)
-          --rerun                Signal this is a re-run (fail hard if rerun key is empty)
+           --key-rerun KEY        Per-runner rerun key for re-run support
+           --key-rerun-ttl N      TTL for rerun key (default: 604800 / 1 week)
+           --key-failed KEY       Redis key to record failed test files
+           --key-failed-ttl N     TTL for failed key (default: 604800 / 1 week)
+           --rerun                Signal this is a re-run (fail hard if rerun key is empty)
+          --report FILE          Write JSON report to FILE after run
           --verbose              Show per-batch file list and full command output
 
           Arguments after -- are forwarded to the adapter (rspec opts, command opts, etc.).
@@ -226,8 +241,11 @@ module Specbandit
           SPECBANDIT_RSPEC_OPTS       RSpec options (rspec adapter)
           SPECBANDIT_KEY_RERUN        Per-runner rerun key
           SPECBANDIT_KEY_RERUN_TTL    Rerun key TTL in seconds (default: 604800)
+          SPECBANDIT_KEY_FAILED       Redis key for failed test files
+          SPECBANDIT_KEY_FAILED_TTL   Failed key TTL in seconds (default: 604800)
           SPECBANDIT_RERUN            Signal re-run mode (1/true/yes)
           SPECBANDIT_VERBOSE          Enable verbose output (1/true/yes)
+          SPECBANDIT_REPORT           Path to write JSON report file
 
         File input priority for push:
           1. stdin (piped)     echo "spec/a_spec.rb" | specbandit push --key KEY

data/lib/specbandit/configuration.rb

@@ -4,12 +4,14 @@ module Specbandit
   class Configuration
     attr_accessor :redis_url, :batch_size, :key, :rspec_opts, :key_ttl,
                   :key_rerun, :key_rerun_ttl, :rerun, :verbose,
-                  :adapter, :command, :command_opts
+                  :adapter, :command, :command_opts,
+                  :key_failed, :key_failed_ttl, :report
 
     DEFAULT_REDIS_URL = 'redis://localhost:6379'
     DEFAULT_BATCH_SIZE = 5
     DEFAULT_KEY_TTL = 21_600 # 6 hours in seconds
     DEFAULT_KEY_RERUN_TTL = 604_800 # 1 week in seconds
+    DEFAULT_KEY_FAILED_TTL = 604_800 # 1 week in seconds
     DEFAULT_ADAPTER = 'cli'
 
     def initialize
@@ -25,6 +27,9 @@ module Specbandit
       @adapter = ENV.fetch('SPECBANDIT_ADAPTER', DEFAULT_ADAPTER)
       @command = ENV.fetch('SPECBANDIT_COMMAND', nil)
       @command_opts = parse_space_separated(ENV.fetch('SPECBANDIT_COMMAND_OPTS', nil))
+      @key_failed = ENV.fetch('SPECBANDIT_KEY_FAILED', nil)
+      @key_failed_ttl = Integer(ENV.fetch('SPECBANDIT_KEY_FAILED_TTL', DEFAULT_KEY_FAILED_TTL))
+      @report = ENV.fetch('SPECBANDIT_REPORT', nil)
     end
 
     def validate!
@@ -32,6 +37,7 @@ module Specbandit
       raise Error, 'batch_size must be a positive integer' unless batch_size.positive?
       raise Error, 'key_ttl must be a positive integer' unless key_ttl.positive?
       raise Error, 'key_rerun_ttl must be a positive integer' unless key_rerun_ttl.positive?
+      raise Error, 'key_failed_ttl must be a positive integer' unless key_failed_ttl.positive?
       raise Error, '--rerun requires --key-rerun to be set' if rerun && (key_rerun.nil? || key_rerun.empty?)
     end
 

data/lib/specbandit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Specbandit
-  VERSION = '0.12.0'
+  VERSION = '0.13.1'
 end

data/lib/specbandit/worker.rb

@@ -4,7 +4,8 @@ require 'json'
 
 module Specbandit
   class Worker
-    attr_reader :queue, :key, :batch_size, :adapter, :key_rerun, :key_rerun_ttl, :rerun, :output, :verbose
+    attr_reader :queue, :key, :batch_size, :adapter, :key_rerun, :key_rerun_ttl, :key_failed, :key_failed_ttl, :rerun,
+                :output, :verbose, :report
 
     def initialize(
       key: Specbandit.configuration.key,
@@ -12,8 +13,11 @@ module Specbandit
       adapter: nil,
       key_rerun: Specbandit.configuration.key_rerun,
       key_rerun_ttl: Specbandit.configuration.key_rerun_ttl,
+      key_failed: Specbandit.configuration.key_failed,
+      key_failed_ttl: Specbandit.configuration.key_failed_ttl,
       rerun: Specbandit.configuration.rerun,
       verbose: Specbandit.configuration.verbose,
+      report: Specbandit.configuration.report,
       queue: nil,
       output: $stdout,
       # Legacy parameter for backward compatibility.
@@ -24,12 +28,16 @@ module Specbandit
       @batch_size = batch_size
       @key_rerun = key_rerun
       @key_rerun_ttl = key_rerun_ttl
+      @key_failed = key_failed
+      @key_failed_ttl = key_failed_ttl
       @rerun = rerun
       @verbose = verbose
+      @report = report
       @queue = queue || RedisQueue.new
       @output = output
       @batch_results = []
       @accumulated_examples = []
+      @accumulated_failed_files = []
       @accumulated_summary = { duration: 0.0, example_count: 0, failure_count: 0, pending_count: 0,
                                errors_outside_of_examples_count: 0 }
 
@@ -46,26 +54,14 @@ module Specbandit
     #
     # Returns 0 if all batches passed (or nothing to do), 1 if any batch failed.
     def run
+      @run_start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       adapter.setup
 
-      exit_code = if key_rerun
-                    rerun_files = queue.read_all(key_rerun)
-                    if rerun_files.any?
-                      run_replay(rerun_files)
-                    elsif rerun
-                      output.puts "[specbandit] ERROR: --rerun flag is set but rerun key '#{key_rerun}' is empty."
-                      output.puts '[specbandit] The rerun key may have expired (TTL) or Redis was flushed.'
-                      output.puts '[specbandit] Cannot replay — failing to prevent silent false pass.'
-                      1
-                    else
-                      run_steal(record: true)
-                    end
-                  else
-                    run_steal(record: false)
-                  end
+      exit_code = determine_exit_code
 
       print_summary if @batch_results.any?
       merge_json_results
+      write_report
       exit_code
     ensure
       adapter.teardown
@@ -73,6 +69,43 @@ module Specbandit
 
     private
 
+    # Decide the operating mode and execute it, returning the exit code.
+    # - no usable rerun key → steal mode (or crash if --rerun was requested)
+    # - rerun key has data  → replay mode
+    # - rerun key but empty → record mode (or crash if --rerun was requested)
+    def determine_exit_code
+      unless key_present?(key_rerun)
+        return fail_stale_rerun if rerun
+
+        return run_steal(record: false)
+      end
+
+      rerun_files = queue.read_all(key_rerun)
+      return run_replay(rerun_files) if rerun_files.any?
+      return fail_stale_rerun if rerun
+
+      run_steal(record: true)
+    end
+
+    # A Redis key name is usable only when it is a non-nil, non-empty string.
+    # Guards the Ruby gotcha where "" is truthy (e.g. --key-rerun "$UNSET_VAR"),
+    # which would otherwise read/write against an empty key name.
+    def key_present?(value)
+      !value.nil? && !value.empty?
+    end
+
+    # Emit the stale/missing-rerun error and return exit code 1.
+    def fail_stale_rerun
+      if key_present?(key_rerun)
+        output.puts "[specbandit] ERROR: --rerun flag is set but rerun key '#{key_rerun}' is empty."
+      else
+        output.puts '[specbandit] ERROR: --rerun flag is set but no rerun key is configured.'
+      end
+      output.puts '[specbandit] The rerun key may have expired (TTL) or Redis was flushed.'
+      output.puts '[specbandit] Cannot replay — failing to prevent silent false pass.'
+      1
+    end
+
     # Replay mode: run a known list of files in local batches.
     # Used when re-running a failed CI job -- the rerun key already
     # contains the exact files this runner executed previously.
@@ -89,6 +122,7 @@ module Specbandit
         batch.each { |f| output.puts "  #{f}" } if verbose
 
         result = adapter.run_batch(batch, batch_num)
+        record_failed_files(batch, result)
         process_batch_result(result)
 
         if result.exit_code != 0
@@ -132,6 +166,7 @@ module Specbandit
         files.each { |f| output.puts "  #{f}" } if verbose
 
         result = adapter.run_batch(files, batch_num)
+        record_failed_files(files, result)
         process_batch_result(result)
 
         if result.exit_code != 0
@@ -151,11 +186,50 @@ module Specbandit
       failed ? 1 : 0
     end
 
+    # Record failed files to the failed key in Redis for later review.
+    # Called after each batch; only pushes when key_failed is configured
+    # and the batch had a non-zero exit code.
+    #
+    # For RSpec batches with JSON output, only the individual failed file
+    # paths are recorded (not the entire batch). For CLI adapter batches
+    # (no per-file granularity), the whole batch is recorded as fallback.
+    def record_failed_files(files, result)
+      return unless key_present?(key_failed)
+      return if result.exit_code.zero?
+
+      failed_files = extract_failed_files(result) || files
+      return if failed_files.empty?
+
+      queue.push(key_failed, failed_files, ttl: key_failed_ttl)
+    end
+
+    # Extract individual failed file paths from an RspecBatchResult's JSON output.
+    # Returns nil when per-file data is not available (CLI adapter).
+    def extract_failed_files(result)
+      return nil unless result.is_a?(RspecBatchResult) && result.json_path && File.exist?(result.json_path)
+
+      data = JSON.parse(File.read(result.json_path))
+      failed = data.fetch('examples', [])
+                   .select { |e| e['status'] == 'failed' }
+                   .filter_map { |e| e['file_path'] }
+                   .uniq
+
+      failed.empty? ? nil : failed
+    rescue JSON::ParserError
+      nil
+    end
+
     # Process a BatchResult: store it, and for RSpec batches,
     # read the JSON output for rich reporting.
     def process_batch_result(result)
       @batch_results << result
 
+      # Accumulate failed files for the report while JSON data is still available.
+      if result.exit_code != 0
+        per_file = extract_failed_files(result)
+        @accumulated_failed_files.concat(per_file || result.files)
+      end
+
       # If the adapter returned an RspecBatchResult with a json_path,
       # accumulate the structured results for rich reporting.
       return unless result.is_a?(RspecBatchResult) && result.json_path
@@ -242,6 +316,48 @@ module Specbandit
       File.write(path, JSON.pretty_generate(merged))
     end
 
+    # Write a JSON report file with run statistics when --report is set.
+    def write_report
+      return unless report
+      return if @batch_results.empty?
+
+      wall_time = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @run_start_time).round(2)
+      durations = batch_durations
+      failed_batches_count = @batch_results.count { |r| r.exit_code != 0 }
+      passed_batches_count = @batch_results.count { |r| r.exit_code == 0 }
+
+      data = {
+        specbandit_version: Specbandit::VERSION,
+        summary: {
+          total_files: @batch_results.sum { |r| r.files.size },
+          total_batches: @batch_results.size,
+          passed_batches: passed_batches_count,
+          failed_batches: failed_batches_count,
+          passed: failed_batches_count == 0
+        },
+        failed_files: @accumulated_failed_files.uniq,
+        total_wall_time: wall_time,
+        batch_timings: {
+          count: durations.size,
+          min: format('%.2f', durations.min || 0),
+          avg: format('%.2f', durations.empty? ? 0 : durations.sum / durations.size),
+          max: format('%.2f', durations.max || 0),
+          all: durations.map { |d| d.round(2) }
+        },
+        batches: @batch_results.map do |r|
+          {
+            batch_num: r.batch_num,
+            files: r.files,
+            exit_code: r.exit_code,
+            duration: r.duration.round(2),
+            passed: r.exit_code == 0
+          }
+        end
+      }
+
+      File.write(report, JSON.pretty_generate(data))
+    end
+
     # Print a unified summary to the output stream after all batches.
     def print_summary
       output.puts ''

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: specbandit
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.1
 platform: ruby
 authors:
 - Ferran Basora
@@ -109,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Distributed test runner using Redis as a work queue
 test_files: []