= 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

= Known Issues

When using with minitest 6 and minitest-hooks, reported assertion counts may be
inaccurate, though run, failure, and error counts should still be accurate.

= License

MIT

= Author

Jeremy Evans <code@jeremyevans.net>
