minitest-parallel_fork

= minitest-parallel_fork

minitest-parallel_fork adds fork-based parallelization to Minitest. Each test/spec suite is run in one of the forks, allowing this to work correctly when using before_all/after_all/around_all hooks provided by minitest-hooks. Using separate processes via fork can significantly improve spec performance when using MRI, and can work in cases where Minitest's default thread-based parallelism do not work, such as when tests/specs modify the constant namespace.

= Installation

gem install minitest-parallel_fork

= Source Code

Source code is available on GitHub at https://github.com/jeremyevans/minitest-parallel_fork

= Usage

You can enable fork-based parallelism just by requiring +minitest/parallel_fork+. One easy to do so without modifying the spec code itself is to use the +RUBYOPT+ environment variable. So if you execute your specs using:

rake spec

You can switch to fork-based parallelism using:

RUBYOPT=-rminitest/parallel_fork rake spec

To control the number of forks, you can set the +NCPU+ environment variable:

NCPU=8 RUBYOPT=-rminitest/parallel_fork rake spec

If you don't set the +NCPU+ environment variable, minitest-parallel_fork will use 4 forks by default.

= Hooks

In some cases, especially when using external databases, you'll need to do some before fork or after fork setup. minitest/parallel_fork supports +before_parallel_fork+ and +after_parallel_fork+ hooks.

+before_parallel_fork+ is called before any child processes are forked:

Minitest.before_parallel_fork do DB.disconnect end

+after_parallel_fork+ is called after each child process is forked, with the number of the child process, starting at 0:

Minitest.after_parallel_fork do |i| DB.opts[:database] += (i+1).to_s end

The above examples show a fairly easy way to use minitest-parallel_fork with an external database when using Sequel. Before forking, all existing database connections are disconnected, and after forking, the database name is changed in each child to reference a child-specific database, so that the child processes do not share a database and are thus independent.

There is also a hook for debugging. +on_parallel_fork_marshal_failure+ is called if there is an error unmarshalling data sent from the child process to the parent process. This can happen if one of the child processes exits unexpected during the test, before it reports results.

Minitest.on_parallel_fork_marshal_failure do # Gather relevant logs for more debugging end

== Fail Fast Support

If you would like to run tests in parallel, but stop running tests at the first failure, you can use:

RUBYOPT=-rminitest/parallel_fork/fail_fast rake spec

Note that minitest-parallel_fork uses suite-based parallelism, so tests will not stop until one child has a failing test suite (test class that has a failing test method), and other children are signaled and also stop processing.

== Interrupt Support

If you would like to run tests in parallel, but allow for shutting down children when SIGINT is sent to the process, you can use:

RUBYOPT=-rminitest/parallel_fork/interrupt ruby spec_runner.rb

The first SIGINT to a process will ask the child processes to shut down gracefully with SIGUSR1. The second SIGINT to a process will kill the child processes with SIGKILL.

Note that if you use rake to run the specs, the second SIGINT may not be sent to to the parent process, as rake does it's own SIGINT handling.

== ActiveRecord

To use this with Rails/ActiveRecord, you probably want to use hooks similar to:

Minitest.before_parallel_fork do ActiveRecord::Base.connection.disconnect! end

Minitest.after_parallel_fork do |i| db_config = Rails.application.config.database_configuration[Rails.env].clone db_config['database'] += (i+1).to_s ActiveRecord::Base.establish_connection(db_config) end

= Speedup

The speedup you get greatly depends on your specs. Here's some examples using Sequel's specs:

                 2 forks         4 forks

spec_core: 1.25x - 1.36x 1.5x
spec_model: 1.29x - 1.62x 1.72x - 2.02x spec_plugin: 1.57x - 1.76x 2.29x - 2.37x
spec_sqlite: 1.75x - 1.86x 2.26x - 2.65x spec_postgres: 1.32x - 1.40x Untested

= License

MIT

= Author

Jeremy Evans [e-mail]