README.md

TurboTests

turbo_tests2 is a drop-in replacement for grosser/parallel_tests with incremental summarized output. Source code of this gem is based on Discourse and RubyGems work in this area.

Incremental summarized output doesn't fit vision of parallel_tests author and RSpec doesn't support built-in parallel testing yet. This gem will not be useful once one of the issues above will be implemented.

Why incremental output?

parallel_tests is great, but it messes output:

$ 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

Installation

Add this line to your application's Gemfile:

gem 'turbo_tests2'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install turbo_tests2

Usage

Execute tests:

$ bundle exec turbo_tests2

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 [PROCESSES]                   How many processes to use, default: available CPUs
    -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
    -v, --verbose                    More output
        --fail-fast=[N]
        --seed SEED                  Seed for rspec

Rake Hooks

If Rake is present, the CLI will invoke the tasks turbo_tests:setup and turbo_tests:cleanup before and after running the test suite. These can be used to do work that should only happen once, such as removing files or collating coverage:

# lib/tasks/turbo_tests.rake
namespace :turbo_tests 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

SimpleCov

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/turbo_tests/#{ENV["TEST_ENV_NUMBER"]}"

  formatter SimpleCov::Formatter::SimpleFormatter
end

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

  task cleanup: :environment do
    require "simplecov"

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

      minimum_coverage line: 100, branch: 100
    end
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/galtzo-floss/turbo_tests2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the TurboTests project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.