🚀 turbo_tests2 / TurboTests

if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know on Discord or RubyForum, as I may have missed the notification.

if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.

I've summarized my thoughts in this blog post.

turbo_tests2 is an RSpec parallel test runner. It uses runtime_groups for process counts, pid bookkeeping, file grouping, and runtime balancing, then replaces interleaved worker output with incremental summarized RSpec reporting. Source code of this gem is based on Discourse and RubyGems work in this area. As of v4.0.0 the parallel_tests dependency is gone; the CLI keeps compatibility with the parallel_tests grouping surface documented below. The project namespace remains TurboTests; the published gem and executable are turbo_tests2.

Incremental summarized output doesn't fit the vision of the parallel_tests author, and RSpec doesn't support built-in parallel testing yet. This gem targets RSpec, not every framework supported by parallel_tests, and may not be useful once one of the issues above is implemented.

Support tiers describe what this project's CI actually exercises, not what may work in an untested environment:

• Parallel support: CI runs the test suite with multiple workers available.
• Single-worker support: CI runs the suite with one worker; parallel runner behavior is not validated for that combination.
• Unsupported: the engine/platform combination is not covered by CI and is not a project compatibility claim.

The Windows current-Ruby job runs in parallel, but runtime-log recording is disabled there because the runtime logger needs file locking that Windows does not provide reliably (record_runtime = !Gem.win_platform?); see below.

TruffleRuby 22.3, 23.0 and TruffleRuby-head are not listed because no workflow covers them. heads.yml runs ruby-head and jruby-head only, and dep-heads.yml runs the released truffleruby engine against head-of-branch dependencies, which is not a head engine build.

parallel_tests is great, but parallel RSpec output is hard to read:

$ bundle exec rake parallel_tests:spec[^spec/search]
.................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................

Finished in 1 minute 6.92 seconds (files took 6.95 seconds to load)
2616 examples, 0 failures

.........................................................................................................................................F........................................................................................................................................F..............................................................................................................................................................................................................................................................................................

Finished in 1 minute 35.05 seconds (files took 6.26 seconds to load)
2158 examples, 2 failures

.................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................

Finished in 1 minute 35.05 seconds (files took 6.26 seconds to load)
2158 examples, 0 failures

turbo_tests2 output looks like regular rspec:

$ bundle exec turbo_tests2
..........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................F........................................................................................................................................F..............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................

Finished in 2 minute 25.15 seconds (files took 0 seconds to load)
6873 examples, 2 failures

Tokens to Remember
Works with JRuby
Works with Truffle Ruby
Works with MRI Ruby 4
Works with MRI Ruby 3
Works with MRI Ruby 2
Support & Community
Source
Documentation
Compliance
Style
Maintainer 🎖️
... 💖	🧊 🐙 🛖 🧪

Compatible with MRI Ruby 2.4.0+, JRuby, and TruffleRuby. CI workflows and Appraisals are generated for MRI Ruby 2.4+. This test floor is configured by ruby.test_minimum in .kettle-jem.yml and may be higher than the gem's runtime compatibility floor when legacy Rubies are not practical for the current toolchain.

The amazing test matrix is powered by the kettle-dev stack.

Gem	Source	Role	Total downloads
appraisal2	GitHub	multi-dependency Appraisal matrix generation
appraisal2-rubocop	GitHub	RuboCop Appraisal generator integration
kettle-dev	GitHub	development, release, and CI workflow tooling
kettle-jem	GitHub	Appraisals & CI workflow templates
kettle-soup-cover	GitHub	SimpleCov coverage policy and reporting
kettle-test	GitHub	standard test runner and coverage harness
rubocop-lts	GitHub	Ruby-version-aware linting

Support tiers describe what this project's CI actually exercises, not what may work in an untested environment:

• Parallel support: CI runs the test suite with multiple workers available.
• Unsupported: the engine/platform combination is not covered by CI and is not a project compatibility claim.

Available as part of the Tidelift Subscription.

The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.

• 💡Subscribe for support guarantees covering all your FLOSS dependencies
• 💡Tidelift is part of Sonar
• 💡Tidelift pays maintainers to maintain the software you depend on!
  📊@Pointy Haired Boss: An enterprise support subscription is "never gonna let you down", and supports open source maintainers

Alternatively:

Install the gem and add to the application's Gemfile by executing:

bundle add turbo_tests2

If bundler is not being used to manage dependencies, install the gem by executing:

gem install turbo_tests2

turbo_tests2 ships the turbo_tests2 executable by default.

If you want an opt-in compatibility command for a specific project, generate a local shim:

$ bundle exec turbo_tests2 shim install
Installed turbo_tests shim at bin/turbo_tests.

That creates bin/turbo_tests, which delegates to bundle exec turbo_tests2 "$@". Remove it with:

$ bundle exec turbo_tests2 shim remove
Removed turbo_tests shim at bin/turbo_tests.

Create test databases

$ bundle exec turbo_tests2 --create

Show help:

$ bundle exec turbo_tests2 -h
Usage: turbo_tests2 [options]

[optional] Only selected files & folders:
  turbo_tests2 spec/bar spec/baz/xxx_spec.rb

Options:
    -n, --count [PROCESSES]          How many processes to use, default: available CPUs
    -w, --workers [PROCESSES]        Alias for -n, --count
    -r, --require PATH               Require a file.
    -f, --format FORMATTER           Choose a formatter. Available formatters: progress (p), documentation (d). Default: progress
    -t, --tag TAG                    Run examples with the specified tag.
    -o, --out FILE                   Write output to a file instead of $stdout
        --runtime-log FILE           Location of previously recorded test runtimes
        --example-status-log FILE    Use RSpec example status persistence timings for grouping
        --pattern PATTERN            Run spec files matching this regex pattern
        --exclude-pattern PATTERN    Exclude spec files matching this regex pattern
        --only-group GROUP_INDEX[,GROUP_INDEX]
                                      Run only the selected 1-based parallel_tests group index(es)
        --group-by MODE              Group files by runtime, filesize, or found order
        --allowed-missing PERCENT    Allowed percentage of missing runtimes for runtime grouping
        --unknown-runtime SECONDS    Runtime in seconds to assign files missing runtime history
    -v, --verbose                    More output
        --worker-output MODE         Raw worker output mode: warnings, stream, buffered, or quiet; env: TURBO_TESTS2_WORKER_OUTPUT
        --fail-fast=[N]
        --seed SEED                  Seed for RSpec
        --order ORDER                RSpec example order: random (default) or defined
        --no-random                  Run examples in defined order without passing a seed
        --create                     Create databases
        --print_failed_group         Prints group that had failures in it
        --no-rake-hooks              Do not load a Rakefile or invoke setup and cleanup hooks
        --nice                       execute test commands with low priority

By default, turbo_tests2 generates one random RSpec seed, prints it, and passes that same seed to every worker process. Use --seed SEED to replay a run, or --order defined / --no-random when you want ordered examples without a seed.

turbo_tests2 supports selected parallel_tests options explicitly. It does not invoke the parallel_tests CLI directly, and it does not blindly pass unknown parallel_tests flags through after --. Options after -- are parsed only when listed as supported below.

To select or exclude files matching a regex:

bundle exec turbo_tests2 -n 4 --pattern spec/system
bundle exec turbo_tests2 -n 4 --exclude-pattern spec/system

The compatibility separator also accepts supported options:

bundle exec turbo_tests2 -n 4 -- --pattern spec/system
bundle exec turbo_tests2 -n 4 -- --exclude-pattern spec/system

To rerun one or more selected 1-based groups from a prior parallel split:

bundle exec turbo_tests2 -n 4 --only-group 2
bundle exec turbo_tests2 -n 4 -- --only-group 1,3

To choose a supported parallel_tests grouping mode explicitly:

bundle exec turbo_tests2 -n 4 --group-by runtime
bundle exec turbo_tests2 -n 4 --group-by filesize
bundle exec turbo_tests2 -n 4 --group-by found
bundle exec turbo_tests2 -n 4 -- --group-by runtime

runtime grouping uses the configured runtime log. On platforms other than Windows, turbo_tests2 records runtimes by default. filesize and found do not use runtime history for the initial split, but worker runtime recording still runs so future runtime-based runs can use the updated log.

On Windows, default file discovery uses filesize grouping and runtime recording is disabled because the runtime logger requires file locking that is not supported reliably there. An existing runtime log can still be selected explicitly with --group-by runtime, but Windows runs will not update it.

Runtime grouping also supports the explicit parallel_tests tuning flags --allowed-missing PERCENT and --unknown-runtime SECONDS:

bundle exec turbo_tests2 -n 4 --group-by runtime --allowed-missing 25
bundle exec turbo_tests2 -n 4 --group-by runtime --unknown-runtime 0.5
bundle exec turbo_tests2 -n 4 -- --allowed-missing 25 --unknown-runtime 0.5

Selected group runs default to filesize grouping unless --group-by is provided.

Raw worker stdout/stderr is separate from the parent process formatter output. The progress dot parade is reconstructed from JSON formatter events and already streams from the parent process as workers report examples. Use --worker-output MODE, or TURBO_TESTS2_WORKER_OUTPUT=MODE, to choose how raw worker stdout/stderr is handled. A CLI flag takes precedence over the environment variable.

TURBO_TESTS2_MAX_PROCESSES=N supplies a positive inclusive process ceiling when neither --count nor --workers is present. This is intended for an outer orchestrator such as kettle-family; explicit CLI process counts always take precedence. As with --count, the runner also caps the actual process count at the number of discovered test groups.

Known coverage formatter chatter remains collapsed into the concise coverage summary.

Worker parallelism is spawn-based, not fork-based: each worker is started as a real subprocess (Process.spawn / Open3.popen3), never Kernel#fork. That makes parallel workers engine-portable — MRI, JRuby, and TruffleRuby all run the same spawn-based pool, and the default worker count is the machine's core count (Etc.nprocessors) on every engine. There is no serial-only mode for JVM engines unless you ask for one with TURBO_TESTS2_MAX_PROCESSES=1.

The cost of that portability on JVM engines is memory: each JRuby or TruffleRuby worker is a full JVM subprocess, and JRuby defaults its heap to one quarter of machine RAM. On a CI runner, Etc.nprocessors workers each grabbing a quarter of RAM is a recipe for the kernel's OOM killer, which kills workers silently — every worker stops messaging at once, and the stall watchdog then reports total silence. This is a resource problem, not a parallelism problem.

The fix is to run fewer, smaller workers. This is the canonical resource-constrained setup, and the kettle-jem CI templates bake it into every JRuby workflow they generate:

TURBO_TESTS2_MAX_PROCESSES=2 \
JRUBY_OPTS="-J-Xmx1280m" \
TURBO_TESTS2_WATCHDOG_SECONDS=1500 \
bundle exec turbo_tests2

Or in a GitHub Actions workflow:

env:
  # Fewer, smaller JVM workers on constrained runners.
  TURBO_TESTS2_MAX_PROCESSES: 2
  # Cap each worker JVM's heap (JRuby default: 1/4 of runner RAM).
  JRUBY_OPTS: "-J-Xmx1280m"
  # JVM lanes are slow; give the watchdog room without hitting the job timeout.
  TURBO_TESTS2_WATCHDOG_SECONDS: 1500

Guidance:

• Cap workers (TURBO_TESTS2_MAX_PROCESSES=2) when each worker is a heavy process: JVM engines, large test suites, or shared/undersized runners. Two JVM workers still roughly halve wall-clock time versus one.
• Cap the heap (JRUBY_OPTS="-J-Xmx1280m", or your engine's equivalent) so total memory is bounded regardless of runner size.
• Raise the watchdog (1500s) on slow engines: JIT warmup and heavy GC make silence windows longer, and you want the watchdog report, not the provider timeout, when something genuinely hangs.
• The same knobs apply to any engine where a worker process is expensive — the principle is: bound workers × per-worker memory under the runner's capacity.

If the worker message queue goes silent — every worker alive but none producing example/group messages — a run can otherwise hang until the CI provider kills the job (GitHub Actions: 6 hours).

TURBO_TESTS2_WATCHDOG_SECONDS=N (integer, 0 = disabled) bounds that silence. Default is 900 as of 4.0. (3.x defaulted to 0 — disabled — with a one-time deprecation notice; set 0 to keep the old wait-forever behavior.)

When the watchdog fires it kills the remaining worker processes, prints the unfinished groups and worker pids, and fails the run.

Setting it:

TURBO_TESTS2_WATCHDOG_SECONDS=900 bundle exec turbo_tests2

Notes:

• The clock measures silence across all workers, not per-test duration. In parallel lanes any other worker finishing an example keeps the run alive; only serial lanes (TURBO_TESTS2_MAX_PROCESSES=1) can trip on a single long test. Raise the value there if you have legitimately long, silent tests.
• CI jobs that hang despite the watchdog will still hit the provider limit; also set timeout-minutes on the CI job. Locally, an outer supervisor (process watcher, container timeout) plays the same role.
• When the watchdog is disabled (0), a 900s silence prints a one-time provider-neutral notice: with the watchdog off, whatever outer process watcher exists — a CI job timeout, a container orchestrator, or a local supervisor — is what will eventually end a hung run, usually without a useful stall report. The notice also names the most common cause of total silence in a parallel lane (silently OOM-killed workers) and the fix (cap workers x per-worker memory).

turbo_tests2 supports custom formatter such as Fuubar, but you might need to require it:

bundle exec turbo_tests2 -r fuubar -f Fuubar spec/whatever

If Rake and a Rakefile are present, the CLI will invoke the tasks turbo_tests2:setup and turbo_tests2:cleanup before and after running the test suite. If no Rakefile is discoverable, the test suite runs without hooks. These tasks can be used to do work that should only happen once, such as removing files or collating coverage:

# lib/tasks/turbo_tests2.rake
namespace :turbo_tests2 do
  task setup: :environment do
    # precompile assets once, to avoid doing it per each process
    Rake::Tasks["assets:precompile"]
  end

  task cleanup: :environment do
    # keep things nice and tidy
    Rake::Tasks["assets:clobber"]
  end
end

Projects with a discoverable Rakefile can disable this integration explicitly:

bundle exec turbo_tests2 --no-rake-hooks

This prevents the Rakefile from being loaded and skips both hooks.

You can get accurate coverage reporting by having SimpleCov write the results for each process into a different directory and then have the results collated as part of cleanup:

# spec/spec_helper.rb
require "simplecov"

# Configure minimum test coverage levels
#
# Details of default values for these configuration options can be seen at
# https://github.com/simplecov-ruby/simplecov/blob/master/lib/simplecov/profiles/rails.rb
SimpleCov.start("rails") do
  enable_coverage :branch

  coverage_dir "coverage/#{ENV["TEST_ENV_NUMBER"]}"

  formatter SimpleCov::Formatter::SimpleFormatter
end

# lib/tasks/turbo_tests2.rake
namespace :turbo_tests2 do
  task setup: :environment do
    # remove any existing coverage files to avoid false reporting
    FileUtils.rm_rf("coverage")
  end

  task cleanup: :environment do
    require "simplecov"

    # report coverage usage based on the results of all tests
    SimpleCov.collate(Dir["coverage/*/.resultset.json"]) do
      enable_coverage :branch

      minimum_coverage line: 100, branch: 100
    end
  end
end

While galtzo-floss tools are free software and will always be, the project would benefit immensely from some funding. Raising a monthly budget of... "dollars" would make the project more sustainable.

We welcome both individual and corporate sponsors! We also offer a wide array of funding channels to account for your preferences. Currently, Open Collective is our preferred funding platform.

If you're working in a company that's making significant use of galtzo-floss tools we'd appreciate it if you suggest to your company to become a galtzo-floss sponsor.

You can support the development of galtzo-floss tools via GitHub Sponsors, Liberapay, PayPal, Open Collective and Tidelift.

Support us with a monthly donation and help us continue our activities. [Become a backer]

NOTE: kettle-readme-backers updates this list every day, automatically.

No backers yet. Be the first!

Become a sponsor and get your logo on our README on GitHub with a link to your site. [Become a sponsor]

NOTE: kettle-readme-backers updates this list every day, automatically.

No sponsors yet. Be the first!

I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small. Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions. I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈‍ cats).

If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in bundle fund.

I’m developing a new library, floss_funding, designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.

Floss-Funding.dev: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags

See SECURITY.md.

If you need some ideas of where to help, you could work on adding more code coverage, check issues or PRs, or use the gem and think about how it could be better.

We so if you make changes, remember to update it.

See CONTRIBUTING.md for more detailed instructions.

See CONTRIBUTING.md.

Everyone interacting with this project's codebases, issue trackers, chat rooms and mailing lists agrees to follow the .

Made with contributors-img.

Also see GitLab Contributors: https://gitlab.com/galtzo-floss/turbo_tests2/-/graphs/main

This library follows for its public API where practical. For most applications, prefer the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("turbo_tests2", "~> 3.0")

Dropping support for a platform can be a breaking change for affected users. If a release changes supported platforms, it should be called out clearly in the changelog and versioned with that impact in mind.

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

• "Major Version Numbers are Not Sacred"

See CHANGELOG.md for a list of releases.

The gem is available as open source under the terms of the MIT .

See LICENSE.md for the official copyright notice.

• Copyright (c) 2020-2024 Illia
• Copyright (c) 2020 Ilya Zub
• Copyright (c) 2021 AMHOL
• Copyright (c) 2021 Serge Bedzhyk
• Copyright (c) 2023 Bo Anderson
• Copyright (c) 2023 Dmitiry Zub☀️
• Copyright (c) 2023 mrudzki
• Copyright (c) 2023-2024 Sebastien Savater
• Copyright (c) 2024 Hiroshi SHIBATA
• Copyright (c) 2025-2026 Gareth Jones
• Copyright (c) 2025-2026 Peter H. Boling
• Copyright (c) 2026 Jeff Widman

Maintainers have teeth and need to pay their dentists. After getting laid off in an RIF in March, and encountering difficulty finding a new one, I began spending most of my time building open source tools. I'm hoping to be able to pay for my kids' health insurance this month, so if you value the work I am doing, I need your support. Please consider sponsoring me or the project.

To join the community or get help, use the RubyForum or Discord.

To say "thanks!" ☝️ Join the community or 👇️ send money.

💌 💌 💌

Many parts of this project are actively managed by a kettle-jem smart template utilizing StructuredMerge.org merge contracts.

Thanks for RTFM. ☺️