rails-quality-assurance 1.4.2 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c48fd8ab4bfffb99f79aed4c20a235d68a8743572688e16a30e92fb70c3653b
-  data.tar.gz: 316329537a41a4259bbc2ed9f69767dceb4d491af9d5314fa9e1f2241ff79f73
+  metadata.gz: 82e64c7980fb29c2994a22bf443e2215380a1dd16a9810d1790770624f47854a
+  data.tar.gz: 02dc1dd0d3537f7ededa2b4e2e7dca210b6142f2392f3383b150da0c6118697f
 SHA512:
-  metadata.gz: db9440d4c8d0524b9e1dbaec2d7ab1e5c8f506e86c0aedbeee6d9e1f194589076cc97d3842687789fb50087fb723e30aa40138b5e5c7870dec7964b7b038addb
-  data.tar.gz: f667a8d871426ae41141ad849368f71a69b26512a18376cf5a17c92d93fab62fbfee6f3c83adcc416e8bf9f69be0008cd2af155d2c7e713c6c50b69ee665c3f2
+  metadata.gz: 8be0b839b55b6c9af8aa85110e47fdd1d394c2d5e279a07e51817d32cac9622734c74d1e79e4e9e33243d3deb3ff6c0e4bf35440f771f1a50a641c74d8fabdfe
+  data.tar.gz: 0f609c8d4f8cba9ea6b93a60ba8121502efbcda7bdfa815319fa31196b527d84126d52c90ffc37ea49b2aaf49e5cd17735c3e08aa085f00693cf66734b16c7a5

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-09-25
+
+### Added
+
+- `spec:parallel` holds a cross-process `flock` lock
+  (`tmp/qa/spec_parallel.lock`). A second run aborts immediately with the
+  holder's command, PID, and elapsed time instead of piling workers onto the
+  machine. The kernel releases the lock when the holder exits, including on
+  SIGKILL, and the descriptor is inherited by spawned workers so the lock
+  outlives a killed coordinator for as long as any worker keeps running.
+
+## [1.5.0] - 2026-09-25
+
+### Changed
+
+- `spec:parallel` defaults `PARALLEL_TEST_PROCESSORS` to the number of available
+  CPUs instead of a hardcoded 3. On a 6-CPU machine the default run uses 6
+  workers: 5 for the regular suite plus 1 isolated worker for `spec/system/`.
+
+### Fixed
+
+- `ISOLATE_SPEC_TASKS=0` now disables system spec isolation. `--isolate-n 0`
+  was silently ignored by parallel_tests, which still reserved a dedicated
+  worker and kept system specs out of the regular grouping.
+
 ## [1.4.2] - 2026-09-16
 
 ### Fixed

data/README.md

@@ -27,7 +27,9 @@ Opinionated quality assurance kit for Ruby on Rails applications.
 
 - **RSpec**: Shared helpers and configuration.
 - **Playwright + Capybara**: Remote Chromium headless driver support with auto port assignment for parallel workers and HTML error state dumps on failure (`require 'rails_quality_assurance/playwright'`).
-- **Parallel Tests**: `rake spec:parallel` task with automated system test isolation.
+- **Parallel Tests**: `rake spec:parallel` task that matches the CPU count by
+  default, isolates system specs into a dedicated worker, and serializes runs
+  behind a cross-process lock.
 - **SimpleCov**: 100% line and branch coverage threshold enforcement, LCOV reporting, and parallel process reporting (`require 'rails_quality_assurance/simplecov'`).
 
 ### 4. Continuous Integration Harness
@@ -84,6 +86,35 @@ That single require sets up:
 
 *(If you prefer to load them individually, `require 'rails_quality_assurance/simplecov'` and `require 'rails_quality_assurance/playwright'` remain available.)*
 
+#### Configuring SimpleCov (`.simplecov`)
+
+`rails_quality_assurance` requires SimpleCov and then calls
+`SimpleCov.start 'rails'`. SimpleCov automatically loads a `.simplecov` file
+from the project root while `require 'simplecov'` runs, so anything configured
+there is applied **before** coverage starts:
+
+```ruby
+# .simplecov
+SimpleCov.configure do
+  cover_views            # measure ActionView templates (SimpleCov 1.2+)
+  track_tests            # record which test covered each line
+  group 'Components', 'app/components'
+  skip 'app/views/pwa'
+end
+```
+
+Use SimpleCov's native DSL for any option the gem does not wrap — `cover`,
+`track_tests`, `group`, `minimum_coverage`, `maximum_coverage_drop`,
+`baseline_file`, and so on. Because SimpleCov reads the file itself, a new
+SimpleCov option is available to a project without a new
+`rails-quality-assurance` release.
+
+`.simplecov` is loaded with plain `load`, so bare method calls resolve against
+`main`. Wrap them in `SimpleCov.configure` (which evaluates the block in
+SimpleCov's context, as above) or prefix each call with `SimpleCov.`. Keep it
+to configuration only: `SimpleCov.start` belongs in `spec/spec_helper.rb`, and
+SimpleCov 1.3 deprecates calling it from `.simplecov`.
+
 ### 3. Rails Test Setup (spec/rails_helper.rb)
 
 After the Rails environment boots, one require applies the shared Rails test configuration:
@@ -138,6 +169,27 @@ bin/rails qa:frontend            # Runs Biome and Stylelint
 bin/rails spec:parallel          # Runs RSpec in parallel with system specs isolated
 ```
 
+`spec:parallel` reads these environment variables:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `PARALLEL_TEST_PROCESSORS` | Number of CPUs | Total worker count |
+| `ISOLATE_SPEC_TASKS` | `1` (or `0` on a single CPU) | Workers reserved for `spec/system/` |
+| `PARALLEL_SPEC_OPTIONS` | - | Extra options passed to RSpec |
+
+Isolation workers are carved out of the total. On a 6-CPU machine the default
+run uses 6 workers: 5 for the regular suite and 1 isolated worker for
+`spec/system/`. Set `ISOLATE_SPEC_TASKS=0` to skip isolation entirely; system
+specs then run as ordinary specs.
+
+`spec:parallel` takes an exclusive `flock` on `tmp/qa/spec_parallel.lock` for
+the whole run. Starting a second run while one is in progress aborts
+immediately with the holder's command, PID, and elapsed time instead of
+doubling the worker count. The kernel releases the lock when the holder exits,
+including on SIGKILL, so a killed run never leaves a stale lock behind; spawned
+workers inherit the descriptor, so the lock stays held while any of them is
+still alive.
+
 ---
 
 ## Development

data/lib/rails_quality_assurance/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RailsQualityAssurance
+  # Base class for all errors raised by the gem.
+  class Error < StandardError; end
+end

data/lib/rails_quality_assurance/parallel_spec_config.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'parallel'
+
+module RailsQualityAssurance
+  # Resolves the parallel spec worker layout from the environment.
+  #
+  # `PARALLEL_TEST_PROCESSORS` is the total worker count and defaults to the
+  # number of available CPUs. `ISOLATE_SPEC_TASKS` carves that many workers out
+  # of the total for `spec/system/`; `0` disables isolation and system specs run
+  # as ordinary specs.
+  class ParallelSpecConfig
+    ISOLATE_PATTERN = 'spec/system/'
+    DEFAULT_ISOLATE_PROCESSORS = 1
+
+    attr_reader :processors, :isolate_processors
+
+    def self.from_env(env = ENV)
+      processors = env.fetch('PARALLEL_TEST_PROCESSORS', Parallel.processor_count).to_i
+      isolate = env.fetch('ISOLATE_SPEC_TASKS', default_isolate_processors(processors))
+
+      new(processors:, isolate_processors: isolate)
+    end
+
+    # A single CPU cannot spare a worker for isolation.
+    def self.default_isolate_processors(processors)
+      processors > 1 ? DEFAULT_ISOLATE_PROCESSORS : 0
+    end
+
+    def initialize(processors:, isolate_processors:)
+      @processors = Integer(processors)
+      @isolate_processors = Integer(isolate_processors)
+
+      validate
+    end
+
+    def isolate?
+      isolate_processors.positive?
+    end
+
+    def parallel_options
+      return '' unless isolate?
+
+      "--isolate --single #{ISOLATE_PATTERN} --isolate-n #{isolate_processors}"
+    end
+
+    private
+
+    def validate
+      raise ArgumentError, 'PARALLEL_TEST_PROCESSORS must be a positive integer' if processors <= 0
+      raise ArgumentError, 'ISOLATE_SPEC_TASKS must be zero or greater' if isolate_processors.negative?
+
+      return if isolate_processors < processors
+
+      raise ArgumentError, 'ISOLATE_SPEC_TASKS must be less than PARALLEL_TEST_PROCESSORS'
+    end
+  end
+end

data/lib/rails_quality_assurance/run_lock.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'time'
+require 'rails_quality_assurance/error'
+
+module RailsQualityAssurance
+  # Cross-process exclusive lock that serializes heavy runs such as the
+  # parallel spec suite.
+  #
+  # The lock is held through `flock`, so the kernel releases it when the last
+  # holder exits, even on SIGKILL. The holder descriptor is made inheritable so
+  # workers spawned by the guarded run keep the lock alive if the coordinating
+  # process dies mid-run.
+  class RunLock
+    # Raised when another run already holds the lock.
+    class Busy < Error; end
+
+    def self.guard(path, command: nil)
+      lock = new(path)
+      lock.acquire(command)
+
+      begin
+        yield
+      ensure
+        lock.release
+      end
+    end
+
+    def initialize(path)
+      @path = path
+      @file = nil
+    end
+
+    # Takes the lock and records the holder, or raises Busy with the current
+    # holder's details so the caller can tell what is already running.
+    def acquire(command = nil)
+      @file = open_file
+
+      return record_holder(command) if try_lock
+
+      message = busy_message
+      release
+      raise Busy, message
+    end
+
+    def release
+      return unless @file
+
+      @file.flock(File::LOCK_UN)
+      @file.close
+      @file = nil
+    end
+
+    private
+
+    def try_lock
+      @file.flock(File::LOCK_EX | File::LOCK_NB)
+    rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+      false
+    end
+
+    def record_holder(command)
+      # Spawned workers must inherit the descriptor, otherwise the lock is
+      # released the moment the coordinating process dies while they still run.
+      @file.close_on_exec = false
+      write_metadata(command)
+
+      self
+    end
+
+    def open_file
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.open(@path, File::RDWR | File::CREAT, 0o644)
+    end
+
+    def write_metadata(command)
+      @file.rewind
+      @file.truncate(0)
+      @file.write(JSON.generate('pid' => Process.pid, 'started_at' => Time.now.utc.iso8601, 'command' => command))
+      @file.flush
+    end
+
+    def busy_message
+      holder = metadata
+      return 'Another quality assurance run is already in progress; wait for it to finish.' if holder.empty?
+
+      "Another quality assurance run is already in progress: #{holder['command']} " \
+        "(pid #{holder['pid']}, started #{elapsed(holder['started_at'])} ago). " \
+        'Wait for it to finish before starting another run.'
+    end
+
+    def metadata
+      @file.rewind
+      JSON.parse(@file.read)
+    rescue JSON::ParserError, TypeError
+      {}
+    end
+
+    def elapsed(started_at)
+      seconds = (Time.now.utc - Time.iso8601(started_at.to_s)).round
+      return "#{seconds}s" if seconds < 60
+
+      minutes = seconds / 60
+      return "#{minutes}m#{seconds % 60}s" if minutes < 60
+
+      "#{minutes / 60}h#{minutes % 60}m"
+    rescue ArgumentError, TypeError
+      'an unknown time'
+    end
+  end
+end

data/lib/rails_quality_assurance/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsQualityAssurance
-  VERSION = '1.4.2'
+  VERSION = '1.6.0'
 end

data/lib/rails_quality_assurance.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
+require 'rails_quality_assurance/error'
 require 'rails_quality_assurance/version'
 require 'rails_quality_assurance/ci'
+require 'rails_quality_assurance/parallel_spec_config'
+require 'rails_quality_assurance/run_lock'
 
 module RailsQualityAssurance
-  class Error < StandardError; end
-
   def self.root
     File.expand_path('..', __dir__)
   end
@@ -33,6 +34,11 @@ module RailsQualityAssurance
     'bundle exec ruby -e \'require "importmap-rails"; require "importmap/map"; ' \
       'ARGV.replace(["audit"]); require "importmap/commands"\''
   end
+
+  # Shared lock file that serializes parallel spec runs for the current app.
+  def self.spec_lock_path
+    File.join('tmp', 'qa', 'spec_parallel.lock')
+  end
 end
 
 require 'rails_quality_assurance/railtie'

data/lib/tasks/quality_assurance.rake

@@ -89,18 +89,18 @@ namespace :spec do
   desc 'Run specs in parallel with system specs isolated'
   task parallel: :environment do
     ENV['PARALLEL_TEST_FIRST_IS_1'] ||= 'true'
-    parallel_tasks = ENV.fetch('PARALLEL_TEST_PROCESSORS', 3).to_s
-    isolate_tasks = ENV.fetch('ISOLATE_SPEC_TASKS', 1).to_s
+    config = RailsQualityAssurance::ParallelSpecConfig.from_env
     test_options = ENV.fetch('PARALLEL_SPEC_OPTIONS', nil)
-    raise ArgumentError, 'PARALLEL_TEST_PROCESSORS must be a positive integer' if parallel_tasks.to_i <= 0
 
-    options = "--isolate --single spec/system/ --isolate-n #{isolate_tasks}"
-    options << " --test-options=\"#{test_options}\"" if test_options
+    options = config.parallel_options
+    options = "#{options} --test-options=\"#{test_options}\"" if test_options
 
-    # Each phase runs in its own rake process: parallel_tests shells out to `$0`
-    # to load a schema per worker, which only works when `$0` is a rake runner.
-    sh "bundle exec rake parallel:create[#{parallel_tasks}]"
-    sh "bundle exec rake parallel:load_schema[#{parallel_tasks}]"
-    sh "bundle exec parallel_rspec spec/ -n #{parallel_tasks} #{options}"
+    RailsQualityAssurance::RunLock.guard(RailsQualityAssurance.spec_lock_path, command: 'spec:parallel') do
+      # Each phase runs in its own rake process: parallel_tests shells out to `$0`
+      # to load a schema per worker, which only works when `$0` is a rake runner.
+      sh "bundle exec rake parallel:create[#{config.processors}]"
+      sh "bundle exec rake parallel:load_schema[#{config.processors}]"
+      sh "bundle exec parallel_rspec spec/ -n #{config.processors} #{options}"
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-quality-assurance
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.6.0
 platform: ruby
 authors:
 - Mauricio Zaffari
@@ -395,6 +395,8 @@ files:
 - lib/rails_quality_assurance/all.rb
 - lib/rails_quality_assurance/ci.rb
 - lib/rails_quality_assurance/ci_runner.rb
+- lib/rails_quality_assurance/error.rb
+- lib/rails_quality_assurance/parallel_spec_config.rb
 - lib/rails_quality_assurance/playwright.rb
 - lib/rails_quality_assurance/playwright/helper.rb
 - lib/rails_quality_assurance/rails/helper.rb
@@ -403,6 +405,7 @@ files:
 - lib/rails_quality_assurance/railtie.rb
 - lib/rails_quality_assurance/rspec.rb
 - lib/rails_quality_assurance/rspec/helper.rb
+- lib/rails_quality_assurance/run_lock.rb
 - lib/rails_quality_assurance/simplecov.rb
 - lib/rails_quality_assurance/simplecov/helper.rb
 - lib/rails_quality_assurance/test_helper.rb