parallel_matrix_formatter 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0b6ef7c5f8b705474c885a007295e1f1d7ffb20e4cae852f8daea1ffe2502ea
-  data.tar.gz: 65c7d8f0c19dc66dc2bee3c2961a3dd68379c2357903dc1214129deac3aac1bd
+  metadata.gz: 87461fe9450a052070b6692e41304d365cf182ff6c3ed24a54c763dac8921e60
+  data.tar.gz: 2249990d6263c6021be4b68916868371ad883eacbd56cfc8ceb79df4a86524fe
 SHA512:
-  metadata.gz: c087a648912b2cc60119dba2cc86d7f75a5139654777cc4b940c0a226805284ea0d4dc34366c81cd1f549bb0e92ed7626bd21f013f89fbd469022ee88320a78f
-  data.tar.gz: 0b81a551ef03313bffa728a0cc93f26280c4940c3ea3666819b6ee61ca21164e7fb138c04b19171a64b6876a498cf55457a061ad905d60002136a501abc3a2ad
+  metadata.gz: c2b8bc1f533a22055fae037c4ddae821852e7e3b27b5afc522cb98a1258a101a52c018eec59f6c43515fa1bb3694198662b75281f60d3ddfa87804b37e7b3eab
+  data.tar.gz: 05b0b6dae008cba2545a9b8dd0fd4eef58d65b538338ecb3c5596bf328746433b178f96d32478e853978ad9d7ee8bb4befcfa8183673eca2808dc1b378df8a0b

data/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.2.0] - 2026-10-03
+
+### Added
+- Support for [`parallel_tests`](https://github.com/grosser/parallel_tests) (`parallel_rspec`) next to
+  `parallel_split_test`. The formatter detects the runner and takes the number of processes and the identity of
+  the run from it; the README lists the `parallel_rspec` options that are not supported.
+
+### Fixed
+- The stderr of every process is written to a log file in the temporary directory instead of `/dev/null`; the
+  summary lists the logs when a process is missing, an error happened outside of the examples or a log is not
+  empty.
+- The closing `Summary:` of `parallel_split_test` is no longer empty: every process writes its totals line to the
+  stream RSpec gave its formatter, which `parallel_split_test` records.
+- Process 1 no longer waits forever for a process that died before its first example: every process announces
+  itself as soon as it connects. Without a pid file (`parallel_split_test`) process 1 stops waiting for a process
+  that has not connected within the new `connect_timeout_seconds` setting (default 120, the timeout the processes
+  already used to connect) and reports it as missing.
+- Under `parallel_tests` the summary could leave out a fast process: it had already left the pid file while its
+  messages were still unread. The orchestrator now also waits until every connection has been read to the end.
+- Without a runner (plain `rspec`) the socket is named after the process's own pid instead of its parent's, so
+  two `rspec` runs started from the same shell no longer remove each other's socket.
+- `--format ParallelMatrixFormatter::Formatter` works without requiring the gem first; the formatter file now
+  loads everything it needs.
+
+### Changed
+- README: documents other formatters writing to stdout, the `--out` handling of `parallel_split_test` and the
+  default colors.
+- The orchestrator waits for the processes that actually connected instead of trusting the announced number of
+  processes. Under `parallel_tests` it also waits for every process listed in the run's pid file, so it neither
+  hangs when `parallel_tests` starts fewer processes than announced nor finishes before a slow process reports.
+- The socket is named after the run (the pid file under `parallel_tests`, the parent pid under `parallel_split_test`);
+  `Ipc.socket_path`, `Ipc::Server.new` and `Ipc::Client.connect` take the path explicitly.
+
 ## [0.1.0] - 2026-10-03
 
 ### Added

data/README.md

@@ -1,9 +1,29 @@
 # ParallelMatrixFormatter
 
-An RSpec formatter for suites run with [`parallel_split_test`](https://github.com/grosser/parallel_split_test).
-Instead of interleaved output from every process, it prints one shared Matrix-style display: a progress line with
-the percentage of each process surrounded by falling katakana "rain", a colored symbol for every finished example,
-and, at the end, a single consolidated RSpec-style summary with all failures from all processes.
+[![Gem Version](https://badge.fury.io/rb/parallel_matrix_formatter.svg)](https://rubygems.org/gems/parallel_matrix_formatter)
+[![CI](https://github.com/vovka/parallel_matrix_formatter/actions/workflows/ci.yml/badge.svg)](https://github.com/vovka/parallel_matrix_formatter/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.txt)
+
+Parallel RSpec output turns into unreadable interleaved noise. This formatter merges every process into one live
+progress display and one consolidated failure report, rendered as Matrix digital rain.
+
+![Demo: four parallel processes as Matrix rain, then one consolidated failure report](docs/images/demo.gif)
+
+An RSpec formatter for suites run with [`parallel_split_test`](https://github.com/grosser/parallel_split_test)
+or [`parallel_tests`](https://github.com/grosser/parallel_tests). It prints a progress line with the percentage of
+each process surrounded by falling katakana "rain", a colored symbol for every finished example, and, at the end, a
+single RSpec-style summary with all failures from all processes.
+
+## Quick start
+
+```sh
+bundle add parallel_matrix_formatter --group test
+bundle exec parallel_split_test --format ParallelMatrixFormatter::Formatter spec
+# or
+bundle exec parallel_rspec -o "--format ParallelMatrixFormatter::Formatter" spec
+```
+
+See [Installation](#installation) and [Usage](#usage) for details.
 
 ## What you are looking at
 
@@ -34,7 +54,7 @@ When the last process finishes, the rain stops and one consolidated report follo
 the failures of all processes with their messages in red and backtraces in cyan, the wall-clock time next to the
 time summed across processes, the totals (red when something failed, yellow when examples are only pending, green
 otherwise) and the commands to rerun the failures. The first line and the closing `Summary:` block are printed by
-`parallel_split_test` itself.
+`parallel_split_test` itself (`parallel_tests` prints its own first line and totals in the same places).
 
 ![A complete run: rain followed by the consolidated summary](docs/images/full_run.png)
 
@@ -55,15 +75,30 @@ gem 'parallel_matrix_formatter', group: :test
 
 and run `bundle install`.
 
-Requirements: Ruby 3.2 or newer, `rspec-core` 3.x. The processes talk over UNIX sockets, so Linux and macOS are
-supported; Windows is not.
+Requirements: Ruby 3.2 or newer, `rspec-core` 3.x, and either `parallel_split_test` or `parallel_tests` (or
+neither, for a single process). The processes talk over UNIX sockets, so Linux and macOS are supported; Windows is
+not.
 
 ## Usage
 
+With `parallel_split_test`:
+
 ```sh
 bundle exec parallel_split_test --format ParallelMatrixFormatter::Formatter spec
 ```
 
+With `parallel_tests`:
+
+```sh
+bundle exec parallel_rspec -o "--format ParallelMatrixFormatter::Formatter" spec
+```
+
+or, to make it the default, put the option in a `.rspec_parallel` file, which `parallel_rspec` reads:
+
+```
+--format ParallelMatrixFormatter::Formatter
+```
+
 The formatter also works with a single process:
 
 ```sh
@@ -103,6 +138,10 @@ The full schema, with the default values:
 # Redirect STDOUT and STDERR of every test process to /dev/null.
 suppress_output: true
 
+# How long the processes wait to connect to process 1, and process 1 waits for them. A process that has not
+# connected by then is reported as missing.
+connect_timeout_seconds: 120
+
 # Ten characters that replace the digits 0-9 in the time and the percentages.
 # Leave empty to keep plain digits.
 digits: ""
@@ -137,7 +176,8 @@ example_status:
 ```
 
 Colors can be any name known to RSpec's console codes: `black`, `red`, `green`, `yellow`, `blue`, `magenta`,
-`cyan`, `white` and their `bold_*` variants. Colors are always emitted, because CI logs render ANSI codes; set the
+`cyan`, `white` and their `bold_*` variants. Colors are always emitted, even when stdout is not a terminal, because
+CI logs render ANSI codes; set the
 `NO_COLOR` environment variable to turn them off.
 
 Example override: emoji for the examples, and a progress line whenever a process advances by 10 percent
@@ -166,10 +206,21 @@ deprecation warnings, output of C extensions and child processes therefore canno
 
   ```sh
   RUBYOPT="-rparallel_matrix_formatter/silence" bundle exec parallel_split_test --format ParallelMatrixFormatter::Formatter spec
+  RUBYOPT="-rparallel_matrix_formatter/silence" bundle exec parallel_rspec -o "--format ParallelMatrixFormatter::Formatter" spec
   ```
 
-- Suppression also hides crashes. When a process dies without reporting, the summary shows a yellow warning
-  naming it. To see why, set `suppress_output: false`.
+- STDOUT goes to `/dev/null`, but STDERR of every process goes to a log file in the temporary directory
+  (`parallel_matrix_formatter-<run>-<process>.stderr.log`), so crashes, load errors and warnings are not lost.
+  When a process is missing, an error happened outside of the examples or a log is not empty, the summary lists
+  the logs. A process that dies without reporting is also named in a yellow warning.
+- The closing `Summary:` of `parallel_split_test` is built from what each process writes to the stream RSpec
+  hands to its formatter, so every process writes its own totals line (`3 examples, 0 failures`) to that stream,
+  which is recorded but not displayed. `parallel_tests` totals the `N examples, M failures` lines it reads from
+  stdout; the consolidated totals the display prints in process 1 are the only such line, so its total is right.
+- Another formatter writing to stdout (for example `--format progress`) is silenced too. Send it to a file:
+  `--format progress --out progress.txt`. `parallel_split_test` only rewrites the first `-o`/`--out` per process
+  (to `name.<process>.ext`, merged afterwards), so a second formatter with `--out` may be written by every
+  process to the same file.
 - If you pass `--out FILE` to RSpec, the display is written to that file instead of the terminal.
 
 ## How it works
@@ -178,7 +229,37 @@ Every test process loads the formatter. Process 1 (`TEST_ENV_NUMBER` empty or `1
 orchestrator, which listens on a UNIX socket in the temporary directory (one per run). The other processes
 connect to it and send the result of every example and, at the end, a summary of their run. The orchestrator
 renders the progress lines and status symbols as messages arrive. When every process has sent its summary or has
-disconnected, it prints the consolidated summary.
+disconnected (or, without a pid file to consult, has not connected within `connect_timeout_seconds`), it prints
+the consolidated summary.
+
+The formatter detects the runner it is started by:
+
+| Runner | Number of processes | Identifies the run (socket name) |
+| --- | --- | --- |
+| `parallel_split_test` | `ParallelSplitTest.processes` | pid of the parent process |
+| `parallel_tests` | `PARALLEL_TEST_GROUPS` | name of the `PARALLEL_PID_FILE` |
+| none | 1 | pid of the process |
+
+`parallel_tests` can start fewer processes than it announces: it drops empty groups (more processes than spec
+files) without correcting `PARALLEL_TEST_GROUPS`. So under `parallel_tests` the orchestrator does not wait for
+the announced number. It waits for the processes that connected, and for every process still listed in the
+pid file that `parallel_tests` keeps for the run, so it neither hangs for a process that never existed nor
+finishes before a slow one reports.
+
+## Using it with parallel_tests
+
+These `parallel_rspec` options are not supported, because they change how the output of the processes reaches
+the terminal or how many times a process runs:
+
+- `--serialize-stdout` holds back the output of process 1 until it has finished, so the display is not live.
+- `--prefix-output-with-test-env-number` prefixes every chunk of output, which garbles the display.
+- `--test-file-limit` runs several RSpec processes one after another under the same process number.
+- `--only-group-continuous-test-env` numbers the processes after their group, so there may be no process 1 to
+  host the display.
+
+A process that dies before RSpec has loaded the formatter (for example because of a syntax error in a required
+file) never connects, so the yellow warning about missing processes cannot name it. `parallel_rspec` still
+exits with a failure status.
 
 ## Development
 
@@ -189,10 +270,14 @@ bundle exec rspec         # runs the specs in one process with RSpec's own forma
 ruby demo/matrix_demo.rb  # previews the display without a test suite
 ```
 
-The specs eat their own dog food: `rake` (and CI) runs them with `parallel_split_test` and this formatter. CI
-adds [`.github/parallel_matrix_formatter.yml`](.github/parallel_matrix_formatter.yml), which prints a progress line
+The specs eat their own dog food: `rake` (and CI) runs them with `parallel_split_test` and this formatter, as
+released on RubyGems. The release is installed into `tmp/` on the first run and renders the report, so a bug in
+the code under test cannot garble the report of its own specs; its version is pinned in
+[`spec/support/released_formatter.rb`](spec/support/released_formatter.rb). CI also sets
+[`.github/parallel_matrix_formatter.yml`](.github/parallel_matrix_formatter.yml), which prints a progress line
 whenever a process advances by 10 percent; to see the same locally:
-`PARALLEL_MATRIX_FORMATTER_CONFIG=.github/parallel_matrix_formatter.yml bundle exec rake`.
+`PARALLEL_MATRIX_FORMATTER_CONFIG=.github/parallel_matrix_formatter.yml bundle exec rake`. The integration specs
+run the formatter for real under both `parallel_split_test` (faked by a stub) and `parallel_rspec`.
 
 ## Contributing
 

data/config/parallel_matrix_formatter.yml

@@ -9,6 +9,11 @@
 # when something goes wrong and you need to see why.
 suppress_output: true
 
+# How long a process waits for process 1 to start listening, and process 1
+# waits for the others to connect. A process that never connects (for example
+# because spec_helper failed to load) is reported as missing once it passes.
+connect_timeout_seconds: 120
+
 # Ten characters that replace the digits 0-9 in the time and the percentages,
 # e.g. "ﾛｲｸﾖﾑﾗﾚﾇﾒﾜ". Leave empty to keep plain digits.
 digits: ""

data/lib/parallel_matrix_formatter/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  class Error < StandardError; end
+end

data/lib/parallel_matrix_formatter/formatter.rb

@@ -2,6 +2,26 @@
 
 require 'rspec/core/formatters/base_formatter'
 
+# RSpec requires only this file for --format ParallelMatrixFormatter::Formatter,
+# so it loads everything the formatter needs.
+require_relative 'error'
+require_relative 'config'
+require_relative 'output/silencer'
+require_relative 'runner'
+require_relative 'ipc'
+require_relative 'ipc/client'
+require_relative 'ipc/server'
+require_relative 'rendering/colors'
+require_relative 'rendering/digits'
+require_relative 'rendering/progress_update_policy'
+require_relative 'rendering/progress_column'
+require_relative 'rendering/progress_line'
+require_relative 'rendering/example_status'
+require_relative 'rendering/summary'
+require_relative 'rendering/display'
+require_relative 'null_orchestrator'
+require_relative 'orchestrator'
+
 module ParallelMatrixFormatter
   # The RSpec formatter loaded into every test process. It silences the
   # process, turns RSpec notifications into IPC messages for the orchestrator
@@ -13,15 +33,21 @@ module ParallelMatrixFormatter
     def initialize(output)
       config = Config.load
       super(display_output(config, output))
+      @connect_timeout = config['connect_timeout_seconds']
+      @stream = output
       @process_number = [ENV['TEST_ENV_NUMBER'].to_i, 1].max
-      @orchestrator = Orchestrator.for(@process_number, total_processes, self.output, config)
+      @runner = Runner.detect
+      @orchestrator = Orchestrator.for(@process_number, @runner, self.output, config)
       @examples_run = 0
       @failures = []
     end
 
     def start(notification)
       @total_examples = notification.count
-      @client = Ipc::Client.connect
+      @client = Ipc::Client.connect(Ipc.socket_path(@runner.run_id), timeout: @connect_timeout)
+      # Announces the process at once, so the orchestrator notices it dying
+      # even before its first example.
+      @client.notify(**sender, type: 'hello')
     end
 
     def example_started(_notification)
@@ -42,9 +68,11 @@ module ParallelMatrixFormatter
     end
 
     def dump_summary(summary)
-      @client.notify(type: 'summary', process: @process_number, duration: summary.duration,
-                     examples: summary.example_count, failures: summary.failure_count,
-                     pending: summary.pending_count, failed_examples: @failures)
+      record_totals(summary)
+      @client.notify(**sender, type: 'summary', duration: summary.duration,
+                               examples: summary.example_count, failures: summary.failure_count,
+                               pending: summary.pending_count, errors: summary.errors_outside_of_examples_count,
+                               failed_examples: @failures)
     end
 
     def close(_notification)
@@ -54,12 +82,6 @@ module ParallelMatrixFormatter
 
     private
 
-    # Under parallel_split_test every process is forked by the same runner,
-    # which records the process count before forking.
-    def total_processes
-      (ParallelSplitTest.processes if defined?(ParallelSplitTest)) || 1
-    end
-
     # The silenced terminal is where the display goes, unless RSpec was asked
     # to write to a file with --out.
     def display_output(config, output)
@@ -69,9 +91,23 @@ module ParallelMatrixFormatter
       output.is_a?(File) ? output : terminal
     end
 
+    # parallel_split_test builds its closing "Summary:" from what every process
+    # wrote to the stream RSpec handed to the formatter. The display goes to the
+    # silenced terminal instead, so the totals line goes to the stream, which
+    # parallel_split_test records while its own stdout is silenced.
+    def record_totals(summary)
+      @stream.puts summary.totals_line unless @stream.equal?(output)
+    end
+
+    # Identifies this process to the orchestrator: its number and the pids it
+    # can be told apart by in the runner's pid file.
+    def sender
+      { process: @process_number, pid: Process.pid, ppid: Process.ppid }
+    end
+
     def report(status)
       progress = @examples_run.fdiv(@total_examples)
-      @client.notify(type: 'example', process: @process_number, status: status, progress: progress)
+      @client.notify(**sender, type: 'example', status: status, progress: progress)
     end
 
     def failure_details(notification)

data/lib/parallel_matrix_formatter/ipc/client.rb

@@ -10,7 +10,7 @@ module ParallelMatrixFormatter
       # Process 1 may still be loading spec files when the others start.
       CONNECT_TIMEOUT = 120
 
-      def self.connect(path = Ipc.socket_path, timeout: CONNECT_TIMEOUT)
+      def self.connect(path, timeout: CONNECT_TIMEOUT)
         deadline = Time.now + timeout
         begin
           new(UNIXSocket.new(path))

data/lib/parallel_matrix_formatter/ipc/server.rb

@@ -10,21 +10,36 @@ module ParallelMatrixFormatter
     # When a client disconnects, a synthetic `disconnected` message carrying its
     # process number is queued, so a crashed process is noticed too.
     class Server
-      def initialize(path = Ipc.socket_path)
+      def initialize(path)
         FileUtils.rm_f(path)
         @path = path
         @socket = UNIXServer.new(path)
         @messages = Queue.new
+        @lock = Mutex.new
+        @open_clients = 0
         @acceptor = Thread.new { accept_clients }
       end
 
-      # Yields messages in arrival order until the server is closed.
-      def each_message
-        while (message = @messages.pop)
+      # Yields messages in arrival order until the server is closed. With a
+      # poll interval it also yields nil whenever that long passes without a
+      # message, so the caller can check on the processes it is waiting for.
+      def each_message(poll_interval: nil)
+        loop do
+          message = @messages.pop(timeout: poll_interval)
+          break if message.nil? && @messages.closed?
+
           yield message
         end
       end
 
+      # Whether every client that connected, or is waiting to be accepted, has
+      # disconnected and every message has been yielded. A process can exit
+      # before its messages are read, so its absence from a runner's pid file
+      # alone does not mean it has been heard from.
+      def idle?
+        @lock.synchronize { @open_clients.zero? && !@socket.wait_readable(0) } && @messages.empty?
+      end
+
       def close
         @socket.close
         @messages.close
@@ -34,7 +49,14 @@ module ParallelMatrixFormatter
       private
 
       def accept_clients
-        loop { Thread.new(@socket.accept) { |client| read(client) } }
+        loop do
+          @socket.wait_readable
+          client = @lock.synchronize do
+            @open_clients += 1
+            @socket.accept
+          end
+          Thread.new(client) { |connection| read(connection) }
+        end
       rescue IOError, Errno::EBADF
         nil # the socket was closed
       end
@@ -49,6 +71,7 @@ module ParallelMatrixFormatter
         enqueue('type' => 'disconnected', 'process' => process) if process
       ensure
         client.close
+        @lock.synchronize { @open_clients -= 1 }
       end
 
       def enqueue(message)

data/lib/parallel_matrix_formatter/ipc.rb

@@ -6,10 +6,9 @@ module ParallelMatrixFormatter
   # Communication between the test processes and the orchestrator: newline
   # separated JSON messages over a UNIX socket.
   module Ipc
-    # Every process started by parallel_split_test is forked by the same
-    # runner, so its pid identifies the run.
-    def self.socket_path
-      File.join(Dir.tmpdir, "parallel_matrix_formatter-#{Process.ppid}.sock")
+    # @param run_id [String, Integer] identifies the run, see Runner#run_id
+    def self.socket_path(run_id)
+      File.join(Dir.tmpdir, "parallel_matrix_formatter-#{run_id}.sock")
     end
   end
 end

data/lib/parallel_matrix_formatter/orchestrator.rb

@@ -4,20 +4,36 @@ module ParallelMatrixFormatter
   # Runs in process 1 only. Receives the messages of every test process over
   # IPC, renders them as they arrive and prints the consolidated summary once
   # every process has reported its summary or disconnected.
+  #
+  # The runner's process count is only a lower bound: parallel_tests drops
+  # empty groups and numbers processes by group under --only-group. So the
+  # processes to wait for are the ones that actually connected, plus, without
+  # a pid file, the ones the count promises. With a pid file the orchestrator
+  # also waits for every live test process it has not heard from yet. A process
+  # counts as heard from when its pid, or its parent's (a wrapper such as spring
+  # that parallel_tests started instead of rspec), arrived in a message.
+  # Without a pid file, a process that has not connected within the connect
+  # timeout counts as gone: it died before loading the formatter, or gave up.
+  # Either way it only finishes once the server has read every connection.
   class Orchestrator
-    def self.for(process_number, total_processes, output, config)
+    POLL_INTERVAL = 1
+
+    def self.for(process_number, runner, output, config)
       return NullOrchestrator.new unless process_number == 1
 
-      new(total_processes, output, Rendering::Display.new(config, total_processes))
+      new(runner, output, Rendering::Display.new(config, runner.process_count), config['connect_timeout_seconds'])
     end
 
-    def initialize(total_processes, output, display)
-      @total_processes = total_processes
+    def initialize(runner, output, display, connect_timeout = Ipc::Client::CONNECT_TIMEOUT)
+      @runner = runner
       @output = output
       @display = display
       @summaries = {}
       @disconnected = []
-      @server = Ipc::Server.new
+      @processes = []
+      @known_pids = []
+      @connect_deadline = Time.now + connect_timeout
+      @server = Ipc::Server.new(Ipc.socket_path(runner.run_id))
       @collector = Thread.new { collect_messages }
     end
 
@@ -32,13 +48,14 @@ module ParallelMatrixFormatter
     private
 
     def collect_messages
-      @server.each_message do |message|
-        handle(message)
+      @server.each_message(poll_interval: POLL_INTERVAL) do |message|
+        handle(message) if message
         break if all_finished?
       end
     end
 
     def handle(message)
+      remember(message)
       case message['type']
       when 'example' then print_example(message)
       when 'summary' then @summaries[message['process']] = message
@@ -46,17 +63,37 @@ module ParallelMatrixFormatter
       end
     end
 
+    def remember(message)
+      @processes |= [message['process']]
+      @known_pids |= message.values_at('pid', 'ppid').compact
+    end
+
     def print_example(message)
       @output.print @display.example(message['process'], message['status'], message['progress'])
       @output.flush
     end
 
     def all_finished?
-      missing_processes.all? { |process| @disconnected.include?(process) }
+      missing_processes.all? { |process| gone?(process) } && no_unknown_live_process? && @server.idle?
+    end
+
+    def gone?(process)
+      @disconnected.include?(process) || (!@processes.include?(process) && Time.now > @connect_deadline)
     end
 
     def missing_processes
-      (1..@total_processes).reject { |process| @summaries.key?(process) }
+      awaited_processes.reject { |process| @summaries.key?(process) }
+    end
+
+    def awaited_processes
+      @runner.pid_file ? @processes : @processes | (1..@runner.process_count).to_a
+    end
+
+    def no_unknown_live_process?
+      return true unless @runner.pid_file
+
+      live = @runner.live_pids
+      !live.nil? && (live - @known_pids).empty?
     end
   end
 end

data/lib/parallel_matrix_formatter/output/silencer.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require 'tmpdir'
+
 module ParallelMatrixFormatter
   module Output
-    # Redirects the process's stdout and stderr to /dev/null and keeps a private
-    # copy of the original stdout for the display. The redirection happens at
-    # the file descriptor level, so output written through loggers holding
-    # STDOUT, C extensions or child processes is silenced as well.
+    # Redirects the process's stdout to /dev/null and its stderr to a log file,
+    # and keeps a private copy of the original stdout for the display. The
+    # redirection happens at the file descriptor level, so output written
+    # through loggers holding STDOUT, C extensions or child processes is
+    # silenced as well. There is one log per process, named after the run (the
+    # parent pid) and the process number.
     module Silencer
       class << self
         # @return [IO] the original stdout
@@ -18,15 +22,26 @@ module ParallelMatrixFormatter
           !@terminal.nil?
         end
 
+        # @return [Array<String>] the stderr logs of every process of the run
+        def stderr_logs
+          @log_prefix ? Dir["#{@log_prefix}-*.stderr.log"] : []
+        end
+
         private
 
         def redirect_to_null
           terminal = STDOUT.dup
           terminal.sync = true
           STDOUT.reopen(File::NULL, 'w')
-          STDERR.reopen(File::NULL, 'w')
+          STDERR.reopen(stderr_log_path, 'w')
+          STDERR.sync = true
           terminal
         end
+
+        def stderr_log_path
+          @log_prefix = File.join(Dir.tmpdir, "parallel_matrix_formatter-#{Process.ppid}")
+          "#{@log_prefix}-#{[ENV['TEST_ENV_NUMBER'].to_i, 1].max}.stderr.log"
+        end
       end
     end
   end

data/lib/parallel_matrix_formatter/rendering/progress_update_policy.rb

@@ -45,7 +45,7 @@ module ParallelMatrixFormatter
       end
 
       def all_complete?(progress)
-        progress.size == @total_processes && progress.values.all? { |value| value >= 1.0 }
+        progress.size >= @total_processes && progress.values.all? { |value| value >= 1.0 }
       end
     end
   end

data/lib/parallel_matrix_formatter/rendering/summary.rb

@@ -17,7 +17,8 @@ module ParallelMatrixFormatter
       # @param missing_processes [Array<Integer>] processes that never sent a summary
       def render(summaries, missing_processes)
         failures = summaries.flat_map { |summary| summary['failed_examples'] }
-        sections = [failures_section(failures), warnings(missing_processes), totals(summaries), rerun_section(failures)]
+        sections = [failures_section(failures), warnings(missing_processes),
+                    logs_section(summaries, missing_processes), totals(summaries), rerun_section(failures)]
         "\n#{sections.compact.join("\n")}"
       end
 
@@ -44,6 +45,18 @@ module ParallelMatrixFormatter
                          'Set suppress_output: false to see its output.', :yellow)}"
       end
 
+      # The stderr of the processes is silenced into logs, so point at them
+      # when something went wrong: a missing process, an error outside of the
+      # examples (a load error) or anything a process wrote to stderr.
+      def logs_section(summaries, missing_processes)
+        logs = Output::Silencer.stderr_logs
+        errors = summaries.sum { |summary| summary['errors'].to_i }
+        return unless errors.positive? || missing_processes.any? || logs.any? { |log| File.size?(log) }
+
+        title = Colors.wrap("stderr of the processes (#{errors} errors outside of examples):", :yellow)
+        "\n#{title}\n#{logs.join("\n")}"
+      end
+
       def totals(summaries)
         examples, failures, pending = %w[examples failures pending].map { |key| summaries.sum { |s| s[key] } }
         process_time = Helpers.format_duration(summaries.sum { |summary| summary['duration'] })

data/lib/parallel_matrix_formatter/runner.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ParallelMatrixFormatter
+  # Describes the parallel runner that started this process: how many processes
+  # it runs, which run they belong to and, where the runner keeps one, the file
+  # listing the processes that are still alive.
+  #
+  # parallel_split_test forks every process from one runner, so the constant
+  # ParallelSplitTest knows the count and the parent pid identifies the run.
+  # parallel_tests spawns every process from one parallel_rspec, which exports
+  # the requested number of groups and a pid file that is unique per run.
+  # Without a runner the only process is process 1 itself, so its own pid
+  # identifies the run; the parent pid would be shared by every rspec started
+  # from the same shell.
+  Runner = Struct.new(:process_count, :run_id, :pid_file, keyword_init: true) do
+    def self.detect
+      if defined?(::ParallelSplitTest)
+        new(process_count: ::ParallelSplitTest.processes, run_id: Process.ppid)
+      elsif ENV['PARALLEL_TEST_GROUPS']
+        parallel_tests
+      else
+        new(process_count: 1, run_id: Process.pid)
+      end
+    end
+
+    def self.parallel_tests
+      pid_file = ENV.fetch('PARALLEL_PID_FILE', nil)
+      new(process_count: [ENV['PARALLEL_TEST_GROUPS'].to_i, 1].max,
+          run_id: pid_file ? File.basename(pid_file) : Process.ppid, pid_file: pid_file)
+    end
+
+    # @return [Array<Integer>, nil] pids of the test processes still running, or
+    #   nil when unknown: no pid file, or one that is empty or half written
+    def live_pids
+      return unless pid_file
+
+      pids = JSON.parse(File.read(pid_file))
+      pids if pids.is_a?(Array)
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+  end
+end

data/lib/parallel_matrix_formatter/silence.rb

@@ -6,6 +6,7 @@
 # before anything else to silence it:
 #
 #   RUBYOPT="-rparallel_matrix_formatter/silence" bundle exec parallel_split_test ...
+#   RUBYOPT="-rparallel_matrix_formatter/silence" bundle exec parallel_rspec ...
 require_relative 'config'
 require_relative 'output/silencer'
 

data/lib/parallel_matrix_formatter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ParallelMatrixFormatter
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/parallel_matrix_formatter.rb

@@ -1,32 +1,15 @@
 # frozen_string_literal: true
 
-require 'rspec/core'
-
-require_relative 'parallel_matrix_formatter/version'
-require_relative 'parallel_matrix_formatter/config'
-require_relative 'parallel_matrix_formatter/output/silencer'
-require_relative 'parallel_matrix_formatter/ipc'
-require_relative 'parallel_matrix_formatter/ipc/client'
-require_relative 'parallel_matrix_formatter/ipc/server'
-require_relative 'parallel_matrix_formatter/rendering/colors'
-require_relative 'parallel_matrix_formatter/rendering/digits'
-require_relative 'parallel_matrix_formatter/rendering/progress_update_policy'
-require_relative 'parallel_matrix_formatter/rendering/progress_column'
-require_relative 'parallel_matrix_formatter/rendering/progress_line'
-require_relative 'parallel_matrix_formatter/rendering/example_status'
-require_relative 'parallel_matrix_formatter/rendering/summary'
-require_relative 'parallel_matrix_formatter/rendering/display'
-require_relative 'parallel_matrix_formatter/null_orchestrator'
-require_relative 'parallel_matrix_formatter/orchestrator'
-require_relative 'parallel_matrix_formatter/formatter'
-
 # Matrix digital rain RSpec formatter for test suites split across processes
-# with parallel_split_test.
+# with parallel_split_test or parallel_tests.
 #
 # Every test process loads the Formatter, which silences the process and sends
 # each example's result to process 1 over a UNIX socket. Process 1 also hosts
 # the Orchestrator, which renders the shared display and, once every process has
 # reported, the consolidated summary.
-module ParallelMatrixFormatter
-  class Error < StandardError; end
-end
+
+require 'rspec/core'
+
+require_relative 'parallel_matrix_formatter/version'
+require_relative 'parallel_matrix_formatter/error'
+require_relative 'parallel_matrix_formatter/formatter'

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parallel_matrix_formatter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Volodymyr Shcherbyna
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-core
@@ -24,7 +25,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 description: An RSpec formatter that renders the progress of every parallel_split_test
-  process as one Matrix-style digital rain and prints a single consolidated summary.
+  or parallel_tests process as one Matrix-style digital rain and prints a single consolidated
+  summary.
 email:
 - scherbina.v@gmail.com
 executables: []
@@ -37,6 +39,7 @@ files:
 - config/parallel_matrix_formatter.yml
 - lib/parallel_matrix_formatter.rb
 - lib/parallel_matrix_formatter/config.rb
+- lib/parallel_matrix_formatter/error.rb
 - lib/parallel_matrix_formatter/formatter.rb
 - lib/parallel_matrix_formatter/ipc.rb
 - lib/parallel_matrix_formatter/ipc/client.rb
@@ -52,6 +55,7 @@ files:
 - lib/parallel_matrix_formatter/rendering/progress_line.rb
 - lib/parallel_matrix_formatter/rendering/progress_update_policy.rb
 - lib/parallel_matrix_formatter/rendering/summary.rb
+- lib/parallel_matrix_formatter/runner.rb
 - lib/parallel_matrix_formatter/silence.rb
 - lib/parallel_matrix_formatter/version.rb
 homepage: https://github.com/vovka/parallel_matrix_formatter
@@ -62,6 +66,7 @@ metadata:
   source_code_uri: https://github.com/vovka/parallel_matrix_formatter
   changelog_uri: https://github.com/vovka/parallel_matrix_formatter/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -76,7 +81,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: Matrix digital rain RSpec formatter for parallel_split_test
+summary: Matrix digital rain RSpec formatter for parallel_split_test and parallel_tests
 test_files: []