rspec-core-parallel 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03f7e28ca852dcd4b84d72d272a6db18e6d8df1e9c090517613f548fbe374a5f
-  data.tar.gz: 7f3efdb57f46ed2164770dad99c66c08925a2258a0c3440f2e1fa0b9eee3209c
+  metadata.gz: 1b57c9af852c507ef4696411ab9de26231b9c04d9400fb8cdb48beb99edf4a89
+  data.tar.gz: ef94f289bf3f6128f124c7bf3c0300a11d435cf0e8a40c2405beaae4b3c274d3
 SHA512:
-  metadata.gz: 46abf9b5942f67930ec91ac9b5c3d926ddf82f721d22c2314f0cc7663f78c7c929996b206348b8a182fd3afb0c4be91a23c947acaedbcb01cbf5c1c23161446e
-  data.tar.gz: '0886bc56896897d0e33c9467934cbfd9e622955f3ea8606b4df7635196f8ec98dafe9a1a48c420026b15962636e48783324aa089da725a5a4f70c4b0a66657c1'
+  metadata.gz: c57a12dc5500fc4578a6ac51bfaa27b68b4f98da09e4297e2857993328ed2b6a9923851caffd14db0cc9a88fd9aecaa30dbdccb9fe44fcc721b48b4885329baa
+  data.tar.gz: d5b61024b3bc242e08c1c35a0b65feb8877083542f85f33d970a4250e30fcdc0a2f473f097cb0fad9c816e1e393ad54406637d39deef1ed55c1e8ed456273a3a

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0
+
+* SimpleCov collects the coverage of the workers without any configuration.
+* `--profile` shows the slowest examples as a share of the time taken by all
+  the examples, rather than of the run time, which could exceed 100%.
+* README: require the gem in `spec_helper.rb` in Rails apps too, to configure it
+  there, and create the test database on CI as usual.
+
 ## 0.1.0
 
 * Loading the gem makes `rspec` run the suite in forked worker processes, one

data/README.md

@@ -1,16 +1,11 @@
 # rspec-core-parallel
 
-Runs an RSpec suite on all the cores of your machine. Add the gem, and `rspec`
-runs in parallel, with one worker process per physical CPU core.
+Run your RSpec suite on all the cores of your machine. Add the gem and `rspec` runs in parallel, with one worker per
+physical CPU core.
 
-RSpec loads the suite once and forks worker processes, which share the loaded
-code. Groups are handed out to idle workers, longest first, and every result is
-sent back to the main process, which reports them like a sequential run: all
-formatters, `--only-failures`, `--profile`, `--fail-fast`, `--bisect` and exit
-codes work as usual.
-
-This gem brings `--parallel` to rspec-core 3.13 until it is part of rspec-core
-itself.
+The suite is loaded once, then forked into worker processes. Workers pick up the longest groups first and send their
+results back to the main process, which prints a single report. Formatters, `--only-failures`, `--profile`,
+`--fail-fast`, `--bisect` and the exit code work as in a normal run.
 
 ## Installation
 
@@ -20,19 +15,20 @@ group :test do
 end
 ```
 
-Rails apps load it with the other gems of the `test` group. Elsewhere, require
-it at the top of `spec_helper.rb`:
+And require it at the top of `spec_helper.rb`. Rails apps also load it with the rest of the `test` group, but only
+when the app boots, which is usually after `spec_helper.rb` is loaded: until then, settings like `parallel_workers`
+and `parallel_worker_setup` don't exist.
 
 ```ruby
 require "rspec/core/parallel"
 ```
 
-That's it: `bundle exec rspec` now runs in parallel.
+Then run `bundle exec rspec` as usual.
 
 ## Number of workers
 
-The default is one worker per physical CPU core. Set it in `spec_helper.rb`
-(`1` runs the suite sequentially):
+By default you get one worker per physical CPU core. To change it, set `parallel_workers` in `spec_helper.rb`.
+`1` turns parallel runs off.
 
 ```ruby
 RSpec.configure do |config|
@@ -40,51 +36,44 @@ RSpec.configure do |config|
 end
 ```
 
-To choose it on the command line, run `rspec-parallel`, which is `rspec` with
-the gem loaded before the options are read, so that it also takes
-`--parallel [COUNT]` (`-j`) and `--no-parallel`:
+To choose it on the command line, use `rspec-parallel`. It is `rspec` with the gem loaded before the options are
+parsed, so it also accepts `--parallel [COUNT]` (`-j`) and `--no-parallel`. Command line options win over
+`config.parallel_workers`.
 
 ```
 $ bundle exec rspec-parallel --parallel 4
 $ bundle exec rspec-parallel --no-parallel spec/models/user_spec.rb
 ```
 
-Options given on the command line win over `config.parallel_workers`.
-
-## How it compares
+## Compared to parallel_tests
 
-Unlike [parallel_tests](https://github.com/grosser/parallel_tests) and similar
-runners, which start one rspec process per CPU and split the spec files between
-them:
+[parallel_tests](https://github.com/grosser/parallel_tests) starts one rspec process per CPU and splits the spec files
+between them up front. With rspec-core-parallel:
 
-* the app boots once, then workers are forked from it;
-* groups are dispatched dynamically, longest first (using the run times of the
-  previous run), and long files are split, so all the workers finish together;
-* there is one combined report, and one exit code;
-* in Rails apps, the worker databases are created and loaded by the runner.
+- the app boots once and the workers are forked from it;
+- groups are handed out while the suite runs, longest first, based on the previous run, and long files are split, so
+  the workers finish at about the same time;
+- you get one report and one exit code;
+- in Rails apps, the test databases of the workers are created and loaded for you.
 
 ## Isolation
 
-Because every worker is a separate process, examples running at the same time
-never share global state (constants, stubs, `RSpec.configuration`...), so
-existing suites run unchanged, provided that they don't share external
-resources such as databases or files between processes.
-
-Rails apps need no setup: as with `rails test` in parallel, every worker gets
-its own test database (`app_test_0`, `app_test_1`...), created and loaded from
-the schema when needed. Set `ActiveSupport.parallelize_test_databases = false`
-to opt out.
-
-Each worker gets a `TEST_ENV_NUMBER` environment variable (`""`, `"2"`, `"3"`...,
-as with parallel_tests) and runs `parallel_worker_setup` hooks, which you can
-use to give every worker its own resources. Workers are forked once the suite
-is loaded, so values computed while loading it, such as a constant holding a
-directory or a Redis client, are the same in all of them. This includes
-configuration reading `TEST_ENV_NUMBER` while the app boots (as parallel_tests
-setups often do for Redis URLs): the variable is only set in the workers, so
-such resources must be pointed at a per-worker instance in
-`parallel_worker_setup`. For example, to give every worker its own directory
-for uploaded files:
+Each worker is a separate process, so examples running at the same time never share global state like constants,
+stubs or `RSpec.configuration`. Most suites run unchanged. What workers do share are external resources: databases,
+files, Redis, and so on.
+
+**Databases.** In Rails apps every worker gets its own test database (`app_test_0`, `app_test_1`, ...), created and
+loaded from the schema when needed, like `rails test` does in parallel. Set
+`ActiveSupport.parallelize_test_databases = false` to opt out. The main process still uses the test database itself
+(`maintain_test_schema!` runs before the workers are forked), so on CI create it as usual, e.g. with
+`bin/rails db:create db:schema:load`, rather than with `parallel:create`.
+
+**Other resources.** Each worker gets a `TEST_ENV_NUMBER` environment variable (`""`, `"2"`, `"3"`, ...) as with
+parallel_tests, and runs the `parallel_worker_setup` hooks. Workers are forked after the suite is loaded, so anything
+set up while loading, like a constant with a directory or a Redis client, is the same in all of them. This also applies
+to config that reads `TEST_ENV_NUMBER` while the app boots: the variable doesn't exist yet at that point. Point those
+resources to a per-worker instance in `parallel_worker_setup` instead. For example, a separate upload directory per
+worker:
 
 ```ruby
 RSpec.configure do |config|
@@ -94,54 +83,37 @@ RSpec.configure do |config|
 end
 ```
 
-`before(:suite)`, `after(:suite)` and `at_exit` hooks run in every worker.
+**Hooks.** `before(:suite)`, `after(:suite)` and `at_exit` hooks run in every worker.
 
 ## Code coverage
 
-To collect code coverage from all the workers with SimpleCov, enable its
-support for forked processes:
+SimpleCov collects the coverage of the workers without any configuration: the gem turns on SimpleCov's support for
+subprocesses and names the results of each worker after its number, so that they replace those of the previous run. If
+you already call `SimpleCov.enable_for_subprocesses true`, your `at_fork` configuration is kept.
 
-```ruby
-SimpleCov.enable_for_subprocesses true
-SimpleCov.start
-
-RSpec.configure do |config|
-  # A stable name per worker, so that each run replaces the results of the
-  # previous one instead of adding to them (SimpleCov names subprocesses after
-  # their pid by default).
-  config.parallel_worker_setup do |worker_number|
-    SimpleCov.command_name "RSpec (worker #{worker_number})"
-  end
-end
-```
-
-Workers only save their coverage: the main process, which exits last, merges
-it, writes the report and checks the minimum coverage.
+Workers only save their results. The main process exits last: it merges them, writes the report and checks the
+minimum coverage.
 
 ## Splitting long groups
 
-To spread long groups over several workers, a group expected to take longer
-than a worker's share of the suite is split into its child groups and parts of
-its examples, unless it has `before(:context)`/`after(:context)` hooks of its
-own (which can be allowed with
-`config.parallel_split_groups_with_context_hooks = true`) or is tagged with
-`:parallel_split => false`. Examples of the same file can therefore run at the
-same time in different workers: tag groups whose examples share a file or
-directory at a fixed path (such as a browser download directory) with
-`:parallel_split => false`, or use a path per worker.
+A group that would take longer than a worker's share of the suite is split into its child groups and chunks of
+examples, which run in different workers. Groups with their own `before(:context)` or `after(:context)` hooks are not
+split, because those hooks would run once per chunk. Set `config.parallel_split_groups_with_context_hooks = true` to
+split them anyway.
+
+Since examples of the same file can run at the same time, tag groups that use a fixed file or directory (a browser
+download folder, for example) with `parallel_split: false`, or give each worker its own path.
 
 ## Run times
 
-The run time of every example is saved in `tmp/rspec_parallel_run_times.txt`,
-or in `config.example_status_persistence_file_path` when it is set, so that the
-next runs hand out the longest groups first (see
-`config.parallel_run_times_file_path`). On CI, cache this file between builds.
+The run time of each example is saved to `tmp/rspec_parallel_run_times.txt`, or to
+`config.example_status_persistence_file_path` if you set one. The next run uses it to start the longest groups
+first. You can change the path with `config.parallel_run_times_file_path`. On CI, cache this file between builds.
 
 ## Requirements
 
-* rspec-core 3.13
-* Ruby 3.3 or later with `Process.fork`: on JRuby and Windows the suite runs
-  sequentially.
+- rspec-core 3.13
+- Ruby 3.3 or later. On JRuby and Windows, where `Process.fork` isn't available, the suite runs sequentially.
 
 ## License
 

data/lib/rspec/core/parallel/coordinator.rb

@@ -68,6 +68,7 @@ module RSpec
         def start_workers
           flush_output_streams
           RailsIntegration.before_fork
+          SimpleCovIntegration.before_fork
           Process.warmup if Process.respond_to?(:warmup)
 
           @workers = []

data/lib/rspec/core/parallel/core_ext.rb

@@ -195,6 +195,21 @@ module RSpec
           end
         end
 
+        # @private
+        module ProfileNotification
+          # Examples running in parallel take longer in total than the run:
+          # the slowest ones are then a share of the time taken by all the
+          # examples, rather than of the run time.
+          def percentage
+            @percentage ||=
+              begin
+                examples_time = examples.inject(0.0) { |total, example| total + example.execution_result.run_time.to_f }
+                time_taken = slow_duration / [duration, examples_time].max
+                '%.1f' % ((time_taken.nan? ? 0.0 : time_taken) * 100)
+              end
+          end
+        end
+
         # Order dependencies can only be reproduced in a single process.
         #
         # @private
@@ -247,6 +262,7 @@ module RSpec
     Example.__send__(:include, Parallel::CoreExt::Example)
     ExampleGroup.singleton_class.__send__(:prepend, Parallel::CoreExt::ExampleGroupClassMethods)
     Reporter.__send__(:include, Parallel::CoreExt::Reporter)
+    Notifications::ProfileNotification.__send__(:prepend, Parallel::CoreExt::ProfileNotification)
     Bisect::ShellCommand.__send__(:prepend, Parallel::CoreExt::BisectShellCommand)
     Bisect::ForkRunner::RunDispatcher.__send__(:prepend, Parallel::CoreExt::BisectRunDispatcher)
   end

data/lib/rspec/core/parallel/simplecov_integration.rb

@@ -1,14 +1,21 @@
 module RSpec
   module Core
     module Parallel
-      # Leaves SimpleCov's report to the main process. SimpleCov saves the
-      # coverage of every process at exit, and the process it considers the
-      # final one merges them, writes the report and checks the minimum
-      # coverage. It can't tell the workers from the main process (SimpleCov
-      # 1.x even takes the first worker for the final process, because of
-      # its `TEST_ENV_NUMBER`), so workers finishing early checked the
-      # coverage collected so far and printed false "below minimum coverage"
-      # warnings. The main process exits after all the workers.
+      # Collects the coverage of the workers with SimpleCov, without any
+      # configuration:
+      #
+      # * turns on SimpleCov's support for subprocesses, which starts SimpleCov
+      #   again in every forked worker, and names the results of each worker
+      #   after its number, so that they replace those of the previous run.
+      #   Suites already enabling it keep their own `at_fork` configuration.
+      # * leaves the report to the main process. SimpleCov saves the coverage
+      #   of every process at exit, and the process it considers the final one
+      #   merges them, writes the report and checks the minimum coverage. It
+      #   can't tell the workers from the main process (SimpleCov 1.x even
+      #   takes the first worker for the final process, because of its
+      #   `TEST_ENV_NUMBER`), so workers finishing early checked the coverage
+      #   collected so far and printed false "below minimum coverage"
+      #   warnings. The main process exits after all the workers.
       #
       # @private
       module SimpleCovIntegration
@@ -19,9 +26,20 @@ module RSpec
           end
         end
 
-        def self.after_fork
+        def self.before_fork
+          @command_name = nil
+          return unless defined?(::SimpleCov) && defined?(::Coverage.running?) && ::Coverage.running?
+          return if ::SimpleCov.enabled_for_subprocesses?
+
+          @command_name = ::SimpleCov.command_name
+          ::SimpleCov.enable_for_subprocesses true
+          require 'simplecov/process'
+        end
+
+        def self.after_fork(worker_number)
           return unless defined?(::SimpleCov) && ::SimpleCov.respond_to?(:final_result_process?)
 
+          ::SimpleCov.command_name "#{@command_name} (worker #{worker_number})" if @command_name
           ::SimpleCov.singleton_class.__send__(:prepend, NotFinalResultProcess)
         end
       end

data/lib/rspec/core/parallel/version.rb

@@ -1,7 +1,7 @@
 module RSpec
   module Core
     module Parallel
-      VERSION = '0.1.0'
+      VERSION = '0.2.0'
     end
   end
 end

data/lib/rspec/core/parallel/worker.rb

@@ -77,7 +77,7 @@ module RSpec
 
           begin
             RailsIntegration.after_fork(@number)
-            SimpleCovIntegration.after_fork
+            SimpleCovIntegration.after_fork(@number)
             configuration.parallel_worker_hooks(:setup).each { |hook| hook.call(@number) }
             configuration.with_suite_hooks { process_commands(registry, reporter, commands) }
             configuration.parallel_worker_hooks(:teardown).each { |hook| hook.call(@number) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-core-parallel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alessandro Rodi
@@ -79,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: 'Run an RSpec suite in forked worker processes: rspec --parallel'
 test_files: []