parallel_tests-ci 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 864c6fb5008d5737a937835d216eecd499c329ca7fb392c2348b692e89329f46
4
- data.tar.gz: 454b3b97fde4b123fc36f433e4f5879283af643e17b86adfb44ef0e47eac6111
3
+ metadata.gz: 39f278571d829d14a3b2cf88d84e36da5e6034ef795914065a707a2c63a8e685
4
+ data.tar.gz: 013fb20125cd950f5c9d1c45deb03490f0b4759982513eaa41c726ff1ebd69d2
5
5
  SHA512:
6
- metadata.gz: 38086198f85476845325ad56e9e842cd50ce1228941d83745eac4f7358c6c31518d5fa6fd2f1d3c8f1188d32f5a6610ce882bcfe093356eaf7f5dcdee8a9f0c3
7
- data.tar.gz: 034e3729db3f02d3d292df77c229b8e924e513afa88944275db27add15dc4b5604713cd485eb89031fd0d319dd8f11d20277bf32c716a5c5ecc017d60fbba7e3
6
+ metadata.gz: b7781e8c4269fb4bff0b020e841c30be60b0f6d640d43cf03deb92d07b6f6622ad4a894af453153584fd4cedffb19c8ee37d120cc4d5bce2ffd3dcb5706b6f0f
7
+ data.tar.gz: ff5b51d38a7856497f4d8af38c4fda3dd1e552b01c761fad5f92c4659ae9302ca2da9e30b31303567fec6624003b9f610362e719512dda04e4e2c37bb3d7f70e
data/CHANGELOG.md CHANGED
@@ -1,5 +1,31 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.0 (2026/11/20)
4
+
5
+ - [#17](https://github.com/dblock/parallel_tests-ci/pull/17): Remove the release environment approval gate while retaining the master-only restriction - [@dblock](https://github.com/dblock).
6
+ - [#18](https://github.com/dblock/parallel_tests-ci/pull/18): Add a RubyGems version badge to README - [@dblock](https://github.com/dblock).
7
+ - [#24](https://github.com/dblock/parallel_tests-ci/pull/24): Remove the second warm run from the Posebook demo - [@dblock](https://github.com/dblock).
8
+ - [#25](https://github.com/dblock/parallel_tests-ci/pull/25): Remove the second cold run from the Posebook demo - [@dblock](https://github.com/dblock).
9
+ - [#26](https://github.com/dblock/parallel_tests-ci/pull/26): Add a standalone GitHub Action that outputs RSpec shard assignments - [@dblock](https://github.com/dblock).
10
+ - [#27](https://github.com/dblock/parallel_tests-ci/pull/27): Shorten workflow input descriptions in the README - [@dblock](https://github.com/dblock).
11
+ - [#28](https://github.com/dblock/parallel_tests-ci/pull/28): Shorten the project guides and README demo - [@dblock](https://github.com/dblock).
12
+ - [#30](https://github.com/dblock/parallel_tests-ci/pull/30): Add automatic Minitest sharding and timing history. RSpec checks now include `Shard Tests` in their names; update any required checks when upgrading - [@dblock](https://github.com/dblock).
13
+ - [#31](https://github.com/dblock/parallel_tests-ci/pull/31): Separate framework runners from the shared sharding lifecycle - [@dblock](https://github.com/dblock).
14
+ - [#33](https://github.com/dblock/parallel_tests-ci/pull/33): Enable Minitest timing collection with a Gemfile require and detect the loaded framework by default - [@dblock](https://github.com/dblock).
15
+ - [#34](https://github.com/dblock/parallel_tests-ci/pull/34): Select automatic, file size, or runtime grouping in workflows and the standalone action - [@dblock](https://github.com/dblock).
16
+ - [#36](https://github.com/dblock/parallel_tests-ci/pull/36): Add a complete Minitest workflow example and keep release references current - [@dblock](https://github.com/dblock).
17
+ - [#38](https://github.com/dblock/parallel_tests-ci/pull/38): Replace `rspec-options` with framework-neutral `test-options` for RSpec and Minitest - [@dblock](https://github.com/dblock).
18
+ - [#40](https://github.com/dblock/parallel_tests-ci/pull/40): Separate installed-consumer checks by framework - [@dblock](https://github.com/dblock).
19
+ - [#41](https://github.com/dblock/parallel_tests-ci/pull/41): Name the synthetic RSpec fixture directory consistently with Minitest - [@dblock](https://github.com/dblock).
20
+ - [#42](https://github.com/dblock/parallel_tests-ci/pull/42): Separate RSpec runner integration checks from shared lifecycle specs - [@dblock](https://github.com/dblock).
21
+ - [#43](https://github.com/dblock/parallel_tests-ci/pull/43): Verify framework selection consistently for installed consumers - [@dblock](https://github.com/dblock).
22
+ - [#44](https://github.com/dblock/parallel_tests-ci/pull/44): Use the shared parallel_tests runner for framework-neutral file grouping - [@dblock](https://github.com/dblock).
23
+ - [#45](https://github.com/dblock/parallel_tests-ci/pull/45): Separate GitHub workflow specs and exercise both framework runners - [@dblock](https://github.com/dblock).
24
+ - [#46](https://github.com/dblock/parallel_tests-ci/pull/46): Organize framework-specific specs and fixtures around shared runner contracts - [@dblock](https://github.com/dblock).
25
+ - [#47](https://github.com/dblock/parallel_tests-ci/pull/47): Support Minitest in the standalone shard matrix action and align framework defaults and plans - [@dblock](https://github.com/dblock).
26
+ - [#48](https://github.com/dblock/parallel_tests-ci/pull/48): Pass standalone action inputs to Ruby as JSON and fix the upgrade heading - [@dblock](https://github.com/dblock).
27
+ - [#50](https://github.com/dblock/parallel_tests-ci/pull/50): Fix release validation against the prepared changelog and future README versions - [@dblock](https://github.com/dblock).
28
+
3
29
  ## 0.1.0 (2026/11/19)
4
30
 
5
31
  - [#2](https://github.com/dblock/parallel_tests-ci/pull/2): Add runtime-balanced RSpec shards and automatic trusted timing history - [@dblock](https://github.com/dblock).
data/README.md CHANGED
@@ -2,19 +2,51 @@
2
2
 
3
3
  # Parallel Tests CI
4
4
 
5
- [![Test](https://github.com/dblock/parallel_tests-ci/actions/workflows/test.yml/badge.svg)](https://github.com/dblock/parallel_tests-ci/actions/workflows/test.yml) [![Lint](https://github.com/dblock/parallel_tests-ci/actions/workflows/lint.yml/badge.svg)](https://github.com/dblock/parallel_tests-ci/actions/workflows/lint.yml) [![Package](https://github.com/dblock/parallel_tests-ci/actions/workflows/package.yml/badge.svg)](https://github.com/dblock/parallel_tests-ci/actions/workflows/package.yml) [![Coverage](https://coveralls.io/repos/github/dblock/parallel_tests-ci/badge.svg?branch=master)](https://coveralls.io/github/dblock/parallel_tests-ci?branch=master)
5
+ [![Gem Version](https://img.shields.io/gem/v/parallel_tests-ci.svg)](https://rubygems.org/gems/parallel_tests-ci) [![Test](https://github.com/dblock/parallel_tests-ci/actions/workflows/test.yml/badge.svg)](https://github.com/dblock/parallel_tests-ci/actions/workflows/test.yml) [![Lint](https://github.com/dblock/parallel_tests-ci/actions/workflows/lint.yml/badge.svg)](https://github.com/dblock/parallel_tests-ci/actions/workflows/lint.yml) [![Package](https://github.com/dblock/parallel_tests-ci/actions/workflows/package.yml/badge.svg)](https://github.com/dblock/parallel_tests-ci/actions/workflows/package.yml) [![Coverage](https://coveralls.io/repos/github/dblock/parallel_tests-ci/badge.svg?branch=master)](https://coveralls.io/github/dblock/parallel_tests-ci?branch=master)
6
6
 
7
- Runtime-balanced RSpec shards for GitHub Actions, powered by [parallel_tests](https://github.com/grosser/parallel_tests). Timing history is collected and reused automatically.
7
+ Runtime-balanced RSpec and Minitest shards for GitHub Actions, powered by [parallel_tests](https://github.com/grosser/parallel_tests). Timing history is collected and reused automatically.
8
8
 
9
- ## Installation
9
+ ## Usage
10
+
11
+ Requires Ruby 3.3+ and either RSpec or Minitest 5.
12
+
13
+ ### RSpec
10
14
 
11
- Requires Ruby 3.3+ and RSpec. Add to your Gemfile and run `bundle install`:
15
+ Add to your Gemfile and run `bundle install`:
12
16
 
13
17
  ```ruby
14
- gem 'parallel_tests-ci', '0.1.0', require: false
18
+ gem 'parallel_tests-ci', '0.2.0', require: 'parallel_tests/ci/rspec'
15
19
  ```
16
20
 
17
- ## Usage
21
+ RSpec matches `spec/**/*_spec.rb` by default and records timings automatically; no changes to `spec_helper.rb` are needed.
22
+
23
+ Add `.github/workflows/test.yml`:
24
+
25
+ ```yaml
26
+ name: Test
27
+ on: [push, pull_request]
28
+
29
+ permissions:
30
+ contents: read
31
+ actions: read
32
+
33
+ jobs:
34
+ test:
35
+ name: Test
36
+ uses: dblock/parallel_tests-ci/.github/workflows/rspec.yml@v0.2.0
37
+ with:
38
+ shards: 8
39
+ ```
40
+
41
+ ### Minitest
42
+
43
+ Add to your Gemfile and run `bundle install`:
44
+
45
+ ```ruby
46
+ gem 'parallel_tests-ci', '0.2.0', require: 'parallel_tests/ci/minitest'
47
+ ```
48
+
49
+ Minitest matches `test/**/*_test.rb` by default. If your test boot does not call `Bundler.require`, add `require 'parallel_tests/ci/minitest'` to `test_helper.rb`. The timing hook only activates in shard workers.
18
50
 
19
51
  Add `.github/workflows/test.yml`:
20
52
 
@@ -29,67 +61,83 @@ permissions:
29
61
  jobs:
30
62
  test:
31
63
  name: Test
32
- uses: dblock/parallel_tests-ci/.github/workflows/rspec.yml@v0.1.0
64
+ uses: dblock/parallel_tests-ci/.github/workflows/minitest.yml@v0.2.0
33
65
  with:
34
66
  shards: 8
35
67
  ```
36
68
 
37
- Ruby comes from your version file; workers use Ubuntu by default. The first run groups by file size. Successful default-branch pushes supply timings for later runs; PRs read them without updating history. Jobs appear as `Test / 1 of 8`, capped at matching file count. Keep gem and workflow versions matched.
69
+ ### Standalone Shard Matrix Action
70
+
71
+ If you manage your own CI jobs, use [the standalone action](DESIGN.md#standalone-shard-matrix-action) to plan RSpec or Minitest shards. It defaults to RSpec; set `framework: minitest` for Minitest. See the [RSpec](.github/workflows/test-standalone-rspec.yml) and [Minitest](.github/workflows/test-standalone-minitest.yml) examples, replacing `uses: ./` with `uses: dblock/parallel_tests-ci@v0.2.0`. Unlike the reusable workflows, the standalone action only assigns files to shards; your workflow runs the tests and manages timing history.
38
72
 
39
73
  ## Configuration
40
74
 
75
+ The workflow uses Ruby from your version file and defaults to Ubuntu. The first run groups tests by file size. Successful pushes on the default branch record timings for later runs, and PRs read them without updating history.
76
+
77
+ These inputs configure the reusable workflows.
78
+
41
79
  ### Runners and Execution
42
80
 
43
- | Input | Default | Purpose |
44
- | --- | --- | --- |
45
- | `runs-on` | `ubuntu-latest` | Runner label or JSON label array for all jobs; Linux and macOS supported. |
46
- | `timeout-minutes` | `360` | Minutes per job, including setup; positive integer, subject to runner limits. |
47
- | `max-parallel` | `256` | Concurrent workers (1-256), subject to runner availability. |
48
- | `fail-fast` | `false` | Cancel other workers when a worker fails. |
49
- | `fetch-depth` | `1` | Checkout history depth in all jobs; `0` fetches all history and tags. |
50
- | `ruby-version` | Empty | Override the caller's Ruby version file. |
51
- | `bundler-cache` | `true` | Cache gems in all jobs; `false` still installs gems. |
81
+ | Input | Default | Purpose |
82
+ | --- | --- | --- |
83
+ | `runs-on` | `ubuntu-latest` | Runner label or JSON label array for all jobs. |
84
+ | `timeout-minutes` | `360` | Minutes per job, including setup; positive integer. |
85
+ | `max-parallel` | `256` | Concurrent worker limit (1-256). |
86
+ | `fail-fast` | `false` | Cancel remaining workers on failure. |
87
+ | `fetch-depth` | `1` | Checkout depth; `0` gets all history and tags. |
88
+ | `ruby-version` | Empty | Override the caller's Ruby version. |
89
+ | `bundler-cache` | `true` | Cache gems; `false` still installs them. |
52
90
 
53
91
  ### Suite and Setup
54
92
 
55
- | Input | Default | Purpose |
56
- | --- | --- | --- |
57
- | `shards` | `4` | Workers (1-256), capped at matching file count. |
58
- | `worker-name` | `{shard.number} of {shard.count}` | Worker label template; empty uses the default. |
59
- | `pattern` | `spec/**/*_spec.rb` | Repository-relative spec glob. |
60
- | `rspec-options` | `[]` | JSON array of RSpec arguments. |
61
- | `environment` | `{}` | JSON object of non-secret environment variables. |
62
- | `before-bundle` | Empty | Shell setup before gems in every job. |
63
- | `setup` | Empty | Shell setup before specs in each worker. |
93
+ | Input | Default | Purpose |
94
+ | --- | --- | --- |
95
+ | `shards` | `4` | Workers (1-256), capped at test file count. |
96
+ | `worker-name` | `{shard.number} of {shard.count}` | Worker label template. |
97
+ | `pattern` | `spec/**/*_spec.rb` (RSpec), `test/**/*_test.rb` (Minitest) | Repository-relative test glob. |
98
+ | `test-options` | `[]` | Test framework arguments as a JSON array. |
99
+ | `environment` | `{}` | Non-secret env vars as a JSON object. |
100
+ | `before-bundle` | Empty | Shell setup before gem install in all jobs. |
101
+ | `setup` | Empty | Shell setup before tests in each worker. |
102
+
103
+ Use arguments supported by the selected framework, for example `test-options: '["--seed","123"]'`.
104
+
105
+ ### Shard Grouping
106
+
107
+ | Input | Default | Purpose |
108
+ | --- | --- | --- |
109
+ | `group-by` | `auto` | Choose `auto`, `filesize`, or `runtime`. |
110
+
111
+ - `auto`: Use runtime history when usable timings cover at least half the selected files. Otherwise, group by file size.
112
+ - `filesize`: Group by file size without reading timing history. Reusable workflows still collect fresh timings.
113
+ - `runtime`: Group by runtime. Planning fails if usable timings cover fewer than half the selected files.
64
114
 
65
115
  ### Artifacts
66
116
 
67
- | Input | Default | Purpose |
68
- | --- | --- | --- |
69
- | `artifacts` | Empty | Extra files to retain, including hidden files and failure diagnostics. |
70
- | `artifact-prefix` | `parallel-tests-ci` | Unique per call; letters, numbers, underscores, and hyphens only. |
71
- | `artifact-retention-days` | `30` | Days to retain plans, measurements, and test artifacts; `0` uses repository default. |
72
- | `baseline-retention-days` | `90` | Days to retain trusted history; `0` uses repository default. |
117
+ | Input | Default | Purpose |
118
+ | --- | --- | --- |
119
+ | `artifacts` | Empty | Extra files to keep, even on failure. |
120
+ | `artifact-prefix` | `parallel-tests-ci` | Artifact name prefix; unique per call. |
121
+ | `artifact-retention-days` | `30` | Days to keep run artifacts; `0` uses repo default. |
122
+ | `baseline-retention-days` | `90` | Days to keep timing history; `0` uses repo default. |
73
123
 
74
124
  See [Workflow Inputs](DESIGN.md#workflow-inputs) for templates, secret environments, and setup rules, and [Plans and Retries](DESIGN.md#plans-and-retries) for rerun behavior.
75
125
 
76
126
  ## Demo
77
127
 
78
- [Posebook](https://github.com/dblock/posebook), a custom Rails CMS, runs 1,142 examples across eight workers. Times below are reported by RSpec and exclude setup and spec loading.
128
+ [Posebook](https://github.com/dblock/posebook) runs 1,142 examples across eight workers. Times are for the slowest successful RSpec worker, excluding setup and spec loading.
79
129
 
80
- <img src="assets/demo.svg" alt="Slowest worker RSpec time: serial 395s, custom sharding 61.62s, parallel_tests alone 70.71s, parallel_tests-ci cold runs 79.11s and 79.03s, warm runs 57.59s and 62.90s" width="480">
130
+ <img src="assets/demo.svg" alt="Slowest worker RSpec time: serial 395s, custom sharding 61.62s, parallel_tests alone 70.71s, parallel_tests-ci cold run 79.11s, warm run 57.59s" width="480">
81
131
 
82
- - [Single-worker run](https://github.com/dblock/posebook/actions/runs/44218105420): No parallel tests; 395s.
83
- - [#178](https://github.com/dblock/posebook/pull/178): Introduce custom sharding, no `parallel_tests`; slowest worker 61.62s.
84
- - [#181](https://github.com/dblock/posebook/pull/181): `parallel_tests` alone, without `parallel_tests-ci`; slowest worker 70.71s.
85
- - [#185](https://github.com/dblock/posebook/pull/185): Initial cold run; slowest worker 79.11s.
86
- - [#186](https://github.com/dblock/posebook/pull/186): Repeat cold run, identical assignments; slowest worker 79.03s.
87
- - [#187](https://github.com/dblock/posebook/pull/187): Warm history redistributed 85/95 files; slowest successful worker 57.59s.
88
- - [#188](https://github.com/dblock/posebook/pull/188): Same warm assignments; slowest worker 62.90s.
132
+ - [Serial run](https://github.com/dblock/posebook/actions/runs/44218105420): 395s.
133
+ - [Custom sharding #178](https://github.com/dblock/posebook/pull/178): 61.62s.
134
+ - [`parallel_tests` alone #181](https://github.com/dblock/posebook/pull/181): 70.71s.
135
+ - [Cold run #185](https://github.com/dblock/posebook/pull/185): 79.11s.
136
+ - [Warm run #187](https://github.com/dblock/posebook/pull/187): 57.59s; timings for 85/95 files.
89
137
 
90
138
  ## Contributing
91
139
 
92
- See [Contributing](CONTRIBUTING.md), [Coding Guidance](AGENTS.md), [Design](DESIGN.md), [Changelog](CHANGELOG.md), and [Releasing](RELEASING.md).
140
+ See [Contributing](CONTRIBUTING.md), [Coding Guidance](AGENTS.md), [Design](DESIGN.md), [Changelog](CHANGELOG.md), [Releasing](RELEASING.md), and [Upgrading](UPGRADING.md).
93
141
 
94
142
  ## License
95
143
 
data/UPGRADING.md ADDED
@@ -0,0 +1,21 @@
1
+ # Upgrading
2
+
3
+ ## Upgrading to Version 0.2.0
4
+
5
+ Update the gem and reusable workflow to matching 0.2.0 versions. If you use `rspec-options`, rename it to `test-options`; the value remains a JSON array of RSpec arguments.
6
+
7
+ Before:
8
+
9
+ ```yaml
10
+ with:
11
+ rspec-options: '["--seed","123"]'
12
+ ```
13
+
14
+ After:
15
+
16
+ ```yaml
17
+ with:
18
+ test-options: '["--seed","123"]'
19
+ ```
20
+
21
+ RSpec worker checks now include `Shard Tests` in their names, for example `Test / Shard Tests / 1 of 8` instead of `Test / 1 of 8`. Update any required branch-protection checks accordingly.
@@ -45,7 +45,7 @@ module ParallelTests
45
45
  break
46
46
  end
47
47
  rescue Error, JSON::ParserError, SystemCallError => e
48
- warn "Timing history unavailable; using file sizes: #{e.message}"
48
+ warn "Timing history unavailable: #{e.message}"
49
49
  end
50
50
 
51
51
  def successful_runs(repository)
@@ -71,13 +71,18 @@ module ParallelTests
71
71
 
72
72
  def prepare(inputs:)
73
73
  run = Run.prepare(directory: "#{DIRECTORY}/plan", history: "#{DIRECTORY}/history/runtime.log",
74
- pattern: inputs.fetch('pattern'), shards: inputs.fetch('shards'),
75
- rspec_options: JSON.parse(inputs.fetch('rspec-options')))
74
+ **plan_settings(inputs))
76
75
  outputs(matrix: JSON.generate(worker_matrix(run, inputs: inputs)),
77
76
  artifact: "#{prefix(inputs.fetch('artifact-prefix'))}-plan-#{ENV.fetch('GITHUB_RUN_ATTEMPT')}")
78
77
  puts "Prepared #{run.plan.fetch('shards')} shards using #{run.plan.fetch('group_by')} grouping."
79
78
  end
80
79
 
80
+ def plan_settings(inputs)
81
+ { pattern: inputs.fetch('pattern'), shards: inputs.fetch('shards'),
82
+ test_options: JSON.parse(inputs.fetch('test-options', '[]')),
83
+ framework: inputs.fetch('framework'), group_by: inputs.fetch('group-by', 'auto') }
84
+ end
85
+
81
86
  def worker_matrix(run, inputs:)
82
87
  template = inputs.fetch('worker-name', '')
83
88
  template = '{shard.number} of {shard.count}' if template.empty?
@@ -0,0 +1,9 @@
1
+ # frozen_string_literal: true
2
+
3
+ path = ENV.fetch('PTCI_RUNTIME_LOG', '')
4
+ unless path.empty?
5
+ require 'minitest'
6
+ require 'parallel_tests/test/runtime_logger'
7
+
8
+ ParallelTests::Test::RuntimeLogger.logfile = path
9
+ end
@@ -0,0 +1,3 @@
1
+ # frozen_string_literal: true
2
+
3
+ # The shard runner installs the RSpec timing formatter via command-line options.
@@ -4,8 +4,8 @@ require 'digest'
4
4
  require 'fileutils'
5
5
  require 'json'
6
6
  require 'parallel_tests'
7
- require 'rbconfig'
8
- require 'shellwords'
7
+ require 'parallel_tests/test/runner'
8
+ require_relative 'runners'
9
9
 
10
10
  module ParallelTests
11
11
  module CI
@@ -13,31 +13,47 @@ module ParallelTests
13
13
  class Run
14
14
  attr_reader :directory, :plan
15
15
 
16
- def self.prepare(directory:, pattern: 'spec/**/*_spec.rb', shards: 4, history: nil, rspec_options: [])
17
- plan = configuration(pattern, shards, rspec_options)
18
- known = history_for(history, plan.fetch('sizes').keys)
19
- plan['group_by'] = grouping(known.size, plan.fetch('sizes').size)
16
+ def self.prepare(directory:, history: nil, group_by: 'auto', **settings)
17
+ plan = configuration(**settings)
18
+ files = plan.fetch('sizes').keys
19
+ known = group_by == 'filesize' ? {} : history_for(history, files)
20
+ plan['group_by'] = grouping(group_by, known.size, files.size)
20
21
  FileUtils.mkdir_p(directory)
21
22
  File.write(File.join(directory, 'plan.json'), JSON.generate(plan))
22
23
  RuntimeLog.write(File.join(directory, 'runtime.log'), known)
23
24
  new(directory)
24
25
  end
25
26
 
26
- def self.configuration(pattern, shards, options)
27
+ def self.configuration(pattern: nil, shards: 4, test_options: [], framework: 'rspec')
27
28
  count = positive_integer(shards)
28
29
  raise ArgumentError, 'GitHub Actions allows at most 256 shards' if count > 256
29
- unless options.is_a?(Array) && options.all?(String)
30
- raise ArgumentError, 'RSpec options must be an array of strings'
30
+ unless test_options.is_a?(Array) && test_options.all?(String)
31
+ raise ArgumentError, 'Test options must be an array of strings'
31
32
  end
32
33
 
34
+ plan = selection(pattern, framework)
35
+ plan.merge('shards' => [count, plan.fetch('sizes').size].min, 'test_options' => test_options)
36
+ end
37
+
38
+ def self.selection(pattern, framework)
39
+ runner = Runners.fetch(framework)
40
+ pattern ||= runner.default_pattern
33
41
  sizes = discover(pattern)
34
- raise ArgumentError, "No spec files match #{pattern.inspect}" if sizes.empty?
42
+ raise ArgumentError, "No #{runner.file_kind} files match #{pattern.inspect}" if sizes.empty?
35
43
 
36
- { 'pattern' => pattern, 'sizes' => sizes, 'shards' => [count, sizes.size].min, 'rspec_options' => options }
44
+ { 'pattern' => pattern, 'sizes' => sizes, 'framework' => framework }
37
45
  end
38
46
 
39
- def self.grouping(known, total)
40
- known.positive? && known * 2 >= total ? 'runtime' : 'filesize'
47
+ def self.grouping(requested, known, total)
48
+ sufficient = known * 2 >= total
49
+ return sufficient ? 'runtime' : 'filesize' if requested == 'auto'
50
+ return requested if requested == 'filesize' || (requested == 'runtime' && sufficient)
51
+
52
+ if requested == 'runtime'
53
+ raise ArgumentError, 'Runtime grouping requires usable timings for at least half the selected files'
54
+ end
55
+
56
+ raise ArgumentError, "Invalid group-by #{requested.inspect}; expected auto, filesize, or runtime"
41
57
  end
42
58
 
43
59
  def self.positive_integer(value)
@@ -72,6 +88,14 @@ module ParallelTests
72
88
  (1..plan.fetch('shards')).map { |shard| { shard: shard } }
73
89
  end
74
90
 
91
+ def file_matrix
92
+ groups = ParallelTests::Test::Runner.tests_in_groups(
93
+ plan.fetch('sizes').keys, plan.fetch('shards'),
94
+ { group_by: plan.fetch('group_by').to_sym, runtime_log: history_path }
95
+ )
96
+ groups.reject(&:empty?).map.with_index(1) { |files, shard| { shard: shard, files: files } }
97
+ end
98
+
75
99
  def fingerprint
76
100
  Digest::SHA256.hexdigest("#{File.read(File.join(directory, 'plan.json'))}\0#{File.read(history_path)}")
77
101
  end
@@ -81,7 +105,7 @@ module ParallelTests
81
105
  generation = self.class.positive_integer(attempt)
82
106
  directory = File.expand_path(directory)
83
107
  prepare_output(directory)
84
- code = execute(command(index, File.join(directory, 'runtime.log')), env)
108
+ code = execute_shard(index, File.join(directory, 'runtime.log'), env)
85
109
  if code.zero?
86
110
  File.write(File.join(directory, 'result.json'),
87
111
  JSON.generate('plan' => fingerprint, 'shard' => index, 'attempt' => generation))
@@ -92,7 +116,7 @@ module ParallelTests
92
116
  def collect(directory:, output:)
93
117
  paths = latest_results(directory)
94
118
  combined = RuntimeLog.merge(paths, files: plan.fetch('sizes').keys)
95
- raise ArgumentError, 'No test timings were recorded' if combined.empty?
119
+ raise ArgumentError, "No test timings were recorded#{runner.timing_hint}" if combined.empty?
96
120
 
97
121
  FileUtils.mkdir_p(File.dirname(output))
98
122
  RuntimeLog.write(output, combined)
@@ -105,7 +129,7 @@ module ParallelTests
105
129
  index = self.class.positive_integer(shard)
106
130
  raise ArgumentError, 'Shard is outside the prepared matrix' if index > plan.fetch('shards')
107
131
  unless self.class.discover(plan.fetch('pattern')) == plan.fetch('sizes')
108
- raise ArgumentError, 'Selected spec files or sizes changed after preparation'
132
+ raise ArgumentError, 'Selected test files or sizes changed after preparation'
109
133
  end
110
134
 
111
135
  index
@@ -117,24 +141,22 @@ module ParallelTests
117
141
  File.write(File.join(directory, 'runtime.log'), '')
118
142
  end
119
143
 
120
- def execute(command, env)
121
- pid = Process.spawn(env, *command)
122
- _pid, status = Process.wait2(pid)
123
- status.exitstatus || (128 + status.termsig)
124
- end
125
-
126
144
  def history_path
127
145
  File.join(directory, 'runtime.log')
128
146
  end
129
147
 
130
- def command(index, output)
131
- options = [*plan.fetch('rspec_options'), '--format', 'progress',
132
- '--format', 'ParallelTests::RSpec::RuntimeLogger', '--out', output]
133
- [RbConfig.ruby, Gem.bin_path('parallel_tests', 'parallel_rspec'),
134
- '-n', plan.fetch('shards').to_s, '--only-group', index.to_s,
135
- '--group-by', plan.fetch('group_by'), '--runtime-log', history_path,
136
- '--test-options', Shellwords.join(options), '--',
137
- *plan.fetch('sizes').keys.map { |file| "./#{file}" }]
148
+ def runner
149
+ Runners.fetch(plan.fetch('framework'))
150
+ end
151
+
152
+ def execute_shard(index, output, env)
153
+ files = plan.fetch('sizes').keys.map { |file| "./#{file}" }
154
+ runner.run(shard_flags(index), files: files, options: plan.fetch('test_options'), output: output, env: env)
155
+ end
156
+
157
+ def shard_flags(index)
158
+ ['-n', plan.fetch('shards').to_s, '--only-group', index.to_s,
159
+ '--group-by', plan.fetch('group_by'), '--runtime-log', history_path]
138
160
  end
139
161
 
140
162
  def latest_results(directory)
@@ -0,0 +1,93 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'rbconfig'
4
+ require 'shellwords'
5
+
6
+ module ParallelTests
7
+ module CI
8
+ # Internal framework selection.
9
+ module Runners
10
+ def self.fetch(framework)
11
+ case framework
12
+ when 'rspec' then RSpec.new
13
+ when 'minitest' then Minitest.new
14
+ else raise ArgumentError, "Unsupported test framework: #{framework}"
15
+ end
16
+ end
17
+
18
+ # Runs one group using the shared parallel_tests command and process handling.
19
+ class Base
20
+ def run(flags, files:, options:, output:, env:)
21
+ pid = Process.spawn(env.merge(timing_environment(output)), *command(flags, files, options, output))
22
+ _pid, status = Process.wait2(pid)
23
+ status.exitstatus || (128 + status.termsig)
24
+ end
25
+
26
+ def timing_hint
27
+ ''
28
+ end
29
+
30
+ private
31
+
32
+ def command(flags, files, options, output)
33
+ [RbConfig.ruby, Gem.bin_path('parallel_tests', executable), *flags,
34
+ '--test-options', Shellwords.join(test_options(options, output)), '--', *files]
35
+ end
36
+
37
+ def test_options(options, _output)
38
+ options
39
+ end
40
+
41
+ def timing_environment(_output)
42
+ {}
43
+ end
44
+ end
45
+
46
+ # Records RSpec timings through the upstream formatter.
47
+ class RSpec < Base
48
+ def default_pattern
49
+ 'spec/**/*_spec.rb'
50
+ end
51
+
52
+ def file_kind
53
+ 'spec'
54
+ end
55
+
56
+ private
57
+
58
+ def executable
59
+ 'parallel_rspec'
60
+ end
61
+
62
+ def test_options(options, output)
63
+ options + ['--format', 'progress', '--format', 'ParallelTests::RSpec::RuntimeLogger', '--out', output]
64
+ end
65
+ end
66
+
67
+ # Lets the caller's Minitest helper configure the upstream logger.
68
+ class Minitest < Base
69
+ def default_pattern
70
+ 'test/**/*_test.rb'
71
+ end
72
+
73
+ def file_kind
74
+ 'test'
75
+ end
76
+
77
+ def timing_hint
78
+ '; configure the Minitest runtime logger in your test helper'
79
+ end
80
+
81
+ private
82
+
83
+ def executable
84
+ 'parallel_test'
85
+ end
86
+
87
+ def timing_environment(output)
88
+ { 'PTCI_RUNTIME_LOG' => output }
89
+ end
90
+ end
91
+ end
92
+ end
93
+ end
@@ -3,6 +3,6 @@
3
3
  module ParallelTests
4
4
  # GitHub Actions integration for parallel_tests.
5
5
  module CI
6
- VERSION = '0.1.0'
6
+ VERSION = '0.2.0'
7
7
  end
8
8
  end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ rspec = defined?(RSpec)
4
+ minitest = defined?(Minitest)
5
+
6
+ if rspec && minitest
7
+ raise LoadError, "Both RSpec and Minitest are loaded. Use require: 'parallel_tests/ci/rspec' for RSpec " \
8
+ "or require: 'parallel_tests/ci/minitest' for Minitest."
9
+ elsif minitest
10
+ require_relative 'parallel_tests/ci/minitest'
11
+ elsif rspec
12
+ require_relative 'parallel_tests/ci/rspec'
13
+ else
14
+ raise LoadError, "Neither RSpec nor Minitest is loaded. Load one before requiring 'parallel_tests-ci'."
15
+ end
metadata CHANGED
@@ -1,13 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: parallel_tests-ci
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Daniel Doubrovkine
8
8
  bindir: bin
9
9
  cert_chain: []
10
- date: 2026-11-19 00:00:00.000000000 Z
10
+ date: 2026-11-20 00:00:00.000000000 Z
11
11
  dependencies:
12
12
  - !ruby/object:Gem::Dependency
13
13
  name: parallel_tests
@@ -34,9 +34,14 @@ files:
34
34
  - CHANGELOG.md
35
35
  - LICENSE.txt
36
36
  - README.md
37
+ - UPGRADING.md
38
+ - lib/parallel_tests-ci.rb
37
39
  - lib/parallel_tests/ci.rb
38
40
  - lib/parallel_tests/ci/github.rb
41
+ - lib/parallel_tests/ci/minitest.rb
42
+ - lib/parallel_tests/ci/rspec.rb
39
43
  - lib/parallel_tests/ci/run.rb
44
+ - lib/parallel_tests/ci/runners.rb
40
45
  - lib/parallel_tests/ci/runtime_log.rb
41
46
  - lib/parallel_tests/ci/version.rb
42
47
  homepage: https://github.com/dblock/parallel_tests-ci