split-test-rb 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d64855f48e44c547898d3a178aeeac82ebf219871242899887492f3a0753677a
-  data.tar.gz: f0556f5c986e3914aca3b68b3fffc42b101643026d6a9dc9c7f32247668b7105
+  metadata.gz: 0ada8a8a7b86b617e21c1e4cb0aced70a07c7c558d133eeaf52009bb0e72c8b3
+  data.tar.gz: bfa1c1f339c5b8506e4ca4b29847b033cfa81ef0595177306281faa308651657
 SHA512:
-  metadata.gz: 6794cc3c793962f67e41ca9fe79236ddf2eeb1d3f218d1e1bd8213d8e22f917df999d391c3ac3288161c23f61fd96b455c62e39be426680b0b10cf0fa963f11d
-  data.tar.gz: 13b0f80b1ebcb0fc5f32a30dcf6b97e8c961cbca7575966446451507568d925fe637691f61d0222cfd53d7e9424a7362f7bded57f67a81c303ef5c23be2d8c77
+  metadata.gz: bc8cbf6a51dd57ec475591a53a1a0fcd11f92c133f22e74541374ec4039824360d2a8497d05895fcb0547791087755f230e5429f7d952d681c78e294e068f299
+  data.tar.gz: ece0a80dcf20141ac7ebafdd82a8a8decd73ea72c3d326f36ee4f58248795d5bf57211268d19f669db1db09fd5082b426af230a09159747bef97014e54f06246

data/README.md

@@ -10,12 +10,10 @@ split-test-rb reads RSpec JSON test reports containing execution times and distr
 
 ## Installation
 
-Since this gem is not yet published to RubyGems, you need to install it from GitHub.
-
 Add to your Gemfile:
 
 ```ruby
-gem 'split-test-rb', github: 'naofumi-fujii/split-test-rb'
+gem 'split-test-rb'
 ```
 
 Then run:
@@ -30,7 +28,7 @@ First, add split-test-rb to your Gemfile:
 
 ```ruby
 # Gemfile
-gem 'split-test-rb', github: 'naofumi-fujii/split-test-rb'
+gem 'split-test-rb'
 ```
 
 For a working example, see this project's own CI configuration:
@@ -51,6 +49,7 @@ Options:
   --test-pattern PATTERN      Test file pattern (default: **/*_spec.rb)
   --split-by-example-threshold SECONDS
                               Split files with execution time >= threshold into individual examples
+  --dry-run-json PATH         RSpec JSON from `rspec --dry-run --format json`, used to list current examples of heavy files
   --debug                     Show debug information
   -h, --help                  Show help message
 ```
@@ -105,6 +104,29 @@ This is useful when:
 
 **Note:** The JSON report must contain the `id` field for each example (RSpec's default JSON formatter includes this). The tool uses these IDs to generate the example-specific paths that RSpec can run.
 
+#### Keeping heavy files up to date with `--dry-run-json`
+
+By default, heavy files are assigned only by the example IDs found in the cached JSON reports. Examples that are not in the cache are not assigned to any node:
+
+- Examples newly added to a heavy file
+- Examples whose IDs shifted because other examples were inserted or moved (RSpec example IDs are position based, e.g. `[1:2:1]`)
+
+Pass the output of `rspec --dry-run --format json` to use the examples that currently exist:
+
+```bash
+bundle exec rspec --dry-run --format json --out tmp/dry-run.json
+split-test-rb --json-path tmp/test-results \
+  --node-index $CI_NODE_INDEX \
+  --node-total $CI_NODE_TOTAL \
+  --split-by-example-threshold 10.0 \
+  --dry-run-json tmp/dry-run.json
+```
+
+With this option, for each heavy file:
+- Examples in the dry-run JSON are assigned, using cached timings when available and the default timing (1.0s) otherwise
+- Cached example IDs that no longer exist are ignored
+- If the dry-run JSON has no examples for the file, the whole file is assigned
+
 ## How It Works
 
 1. **Parse RSpec JSON**: Extracts test file paths and execution times from the JSON report
@@ -160,6 +182,17 @@ To generate JSON reports with RSpec, use the built-in JSON formatter:
 bundle exec rspec --format json --out tmp/rspec-results/results.json
 ```
 
+## Release
+
+To release a new version, use the [Release workflow](.github/workflows/release.yml):
+
+1. Go to the [Actions](https://github.com/naofumi-fujii/split-test-rb/actions/workflows/release.yml) tab
+2. Click "Run workflow"
+3. Select the version bump type (patch/minor/major)
+4. Click "Run workflow"
+
+The workflow will automatically update `lib/split_test_rb/version.rb`, commit it to `main`, create a git tag (`v*`), publish the gem to RubyGems via trusted publishing, and create a GitHub Release.
+
 ## License
 
 MIT

data/lib/split_test_rb/version.rb

@@ -1,3 +1,3 @@
 module SplitTestRb
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.0.3'.freeze
 end

data/lib/split_test_rb.rb

@@ -139,6 +139,58 @@ module SplitTestRb
     end
   end
 
+  # Splits heavy test files into individual examples for finer-grained balancing
+  # Uses current_example_ids (from `rspec --dry-run --format json`) as the source of truth when given,
+  # so that examples missing from the cached JSON (new or shifted IDs) are still assigned
+  class ExampleSplitter
+    DEFAULT_TIMING = 1.0
+
+    def initialize(json_files, current_example_ids: nil, default_files: nil)
+      @example_timings = JsonParser.parse_files_with_examples(json_files)
+      @current_example_ids = current_example_ids
+      @default_files = default_files
+    end
+
+    # Returns timings where files >= threshold are replaced by their examples
+    def split(file_timings, threshold)
+      heavy_files = file_timings.select { |_file, time| time >= threshold }
+      return file_timings if heavy_files.empty?
+
+      # Start with light files (below threshold)
+      timings = file_timings.reject { |file, _| heavy_files.key?(file) }
+      heavy_files.each { |heavy_file, file_time| timings.merge!(examples_for(heavy_file, file_time)) }
+      timings
+    end
+
+    private
+
+    def examples_for(heavy_file, file_time)
+      return cached_examples_for(heavy_file) unless @current_example_ids
+
+      ids = @current_example_ids.select { |example_id| example_of?(example_id, heavy_file) }
+      # Assign the whole file when the dry-run JSON has no examples for it, so no tests are dropped
+      return { heavy_file => file_time } if ids.empty?
+
+      ids.to_h { |example_id| [example_id, timing_for(example_id)] }
+    end
+
+    def cached_examples_for(heavy_file)
+      @example_timings.select { |example_id, _| example_of?(example_id, heavy_file) }
+    end
+
+    def timing_for(example_id)
+      return @example_timings[example_id] if @example_timings.key?(example_id)
+
+      @default_files&.add(example_id)
+      DEFAULT_TIMING
+    end
+
+    # Returns true if example_id (e.g. "spec/a_spec.rb[1:1]") belongs to file_path
+    def example_of?(example_id, file_path)
+      example_id.start_with?("#{file_path}[")
+    end
+  end
+
   # Command-line interface
   class CLI
     def self.run(argv)
@@ -186,7 +238,9 @@ module SplitTestRb
       # Apply example-level splitting if threshold is set
       threshold = options[:split_by_example_threshold]
       timings = if threshold
-                  apply_example_splitting(file_timings, json_files, threshold)
+                  current_example_ids = load_current_example_ids(options[:dry_run_json])
+                  apply_example_splitting(file_timings, json_files, threshold,
+                                          current_example_ids: current_example_ids, default_files: default_files)
                 else
                   file_timings
                 end
@@ -194,24 +248,22 @@ module SplitTestRb
       [timings, default_files, json_files]
     end
 
-    # Splits heavy files (>= threshold) into individual examples
-    def self.apply_example_splitting(file_timings, json_files, threshold)
-      heavy_files = file_timings.select { |_file, time| time >= threshold }
-      return file_timings if heavy_files.empty?
+    # Splits heavy files (>= threshold) into individual examples (delegates to ExampleSplitter)
+    def self.apply_example_splitting(file_timings, json_files, threshold, current_example_ids: nil, default_files: nil)
+      ExampleSplitter.new(json_files, current_example_ids: current_example_ids, default_files: default_files)
+                     .split(file_timings, threshold)
+    end
 
-      example_timings = JsonParser.parse_files_with_examples(json_files)
+    # Loads example IDs from an RSpec dry-run JSON report, or returns nil when no path is given
+    def self.load_current_example_ids(dry_run_json)
+      return nil unless dry_run_json
 
-      # Start with light files (below threshold)
-      timings = file_timings.reject { |file, _| heavy_files.key?(file) }
-
-      # Add individual examples from heavy files
-      heavy_files.each_key do |heavy_file|
-        example_timings.each do |example_id, time|
-          timings[example_id] = time if example_id.start_with?(heavy_file)
-        end
+      unless File.exist?(dry_run_json)
+        warn "Error: dry-run JSON not found: #{dry_run_json}"
+        exit 1
       end
 
-      timings
+      JsonParser.parse_with_examples(dry_run_json).keys
     end
 
     # Adds test files missing from JSON results with default timing (1.0s)
@@ -221,7 +273,7 @@ module SplitTestRb
 
       return default_files if missing_files.empty?
 
-      warn "Warning: Found #{missing_files.size} test files not in JSON, adding with default execution time"
+      warn "Warning: #{missing_files.size} test files not found in JSON, adding with default execution time"
       missing_files.each do |file|
         timings[file] = 1.0
         default_files.add(file)
@@ -249,7 +301,8 @@ module SplitTestRb
       debug: false,
       test_dir: 'spec',
       test_pattern: '**/*_spec.rb',
-      split_by_example_threshold: nil
+      split_by_example_threshold: nil,
+      dry_run_json: nil
     }.freeze
 
     # Parses command-line arguments and returns options hash
@@ -284,10 +337,7 @@ module SplitTestRb
     def self.define_test_options(opts, options)
       opts.on('--test-dir DIR', 'Test directory (default: spec)') { |v| options[:test_dir] = v }
       opts.on('--test-pattern PATTERN', 'Test file pattern (default: **/*_spec.rb)') { |v| options[:test_pattern] = v }
-      opts.on('--split-by-example-threshold SECONDS', Float,
-              'Split files with execution time >= threshold into individual examples') do |v|
-        options[:split_by_example_threshold] = v
-      end
+      define_split_options(opts, options)
       opts.on('--debug', 'Show debug information') { options[:debug] = true }
       opts.on('-h', '--help', 'Show this help message') do
         puts opts
@@ -299,6 +349,18 @@ module SplitTestRb
       end
     end
 
+    # Defines example-level splitting related CLI options
+    def self.define_split_options(opts, options)
+      opts.on('--split-by-example-threshold SECONDS', Float,
+              'Split files with execution time >= threshold into individual examples') do |v|
+        options[:split_by_example_threshold] = v
+      end
+      opts.on('--dry-run-json PATH',
+              'RSpec JSON from `rspec --dry-run --format json`, used to list current examples of heavy files') do |v|
+        options[:dry_run_json] = v
+      end
+    end
+
     def self.find_all_spec_files(test_dir = 'spec', test_pattern = '**/*_spec.rb')
       # Find all test files in the specified directory with the given pattern
       glob_pattern = File.join(test_dir, test_pattern)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: split-test-rb
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Naofumi Fujii
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-16 00:00:00.000000000 Z
+date: 2026-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 description: A simple CLI tool to balance RSpec tests across parallel CI nodes using
   RSpec JSON reports
 email: