parallel_matrix_formatter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e0b6ef7c5f8b705474c885a007295e1f1d7ffb20e4cae852f8daea1ffe2502ea
+  data.tar.gz: 65c7d8f0c19dc66dc2bee3c2961a3dd68379c2357903dc1214129deac3aac1bd
+SHA512:
+  metadata.gz: c087a648912b2cc60119dba2cc86d7f75a5139654777cc4b940c0a226805284ea0d4dc34366c81cd1f549bb0e92ed7626bd21f013f89fbd469022ee88320a78f
+  data.tar.gz: 0b81a551ef03313bffa728a0cc93f26280c4940c3ea3666819b6ee61ca21164e7fb138c04b19171a64b6876a498cf55457a061ad905d60002136a501abc3a2ad

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+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).
+
+## [0.1.0] - 2026-10-03
+
+### Added
+- `ParallelMatrixFormatter::Formatter`, an RSpec formatter for suites run with `parallel_split_test`;
+  it also works with a single `rspec` process.
+- One shared Matrix-style display: a progress line (time plus one percentage column per process, padded with
+  random katakana "rain") and one colored status symbol per finished example.
+- Orchestrator in process 1 that collects the results of all processes over a UNIX socket and, once every process
+  has reported or disconnected, prints a consolidated RSpec-style summary: all failures with messages and
+  backtraces, totals, wall-clock and summed process time, and `rspec ./path:line` rerun commands.
+- Yellow warning naming any process that disconnected without sending a summary (for example after a crash).
+- YAML configuration with defaults in `config/parallel_matrix_formatter.yml`: `suppress_output`, `digits`,
+  `progress_update` (`always`, `interval_seconds`, `percent_threshold`), `progress_line` and `example_status`
+  (formats, symbols, colors, column width and alignment).
+- Project overrides in `config/parallel_matrix_formatter.yml` or `parallel_matrix_formatter.yml`, or in the file
+  named by `PARALLEL_MATRIX_FORMATTER_CONFIG`; missing keys fall back to the defaults (deep merge).
+- Output suppression (`suppress_output: true` by default): STDOUT and STDERR of every process are reopened to
+  `/dev/null`, and the formatter keeps a private copy of the original stdout for the display.
+- `parallel_matrix_formatter/silence` file to silence application boot output
+  (`RUBYOPT="-rparallel_matrix_formatter/silence"`).
+- `NO_COLOR` environment variable support.
+- `demo/matrix_demo.rb` to preview the display without a test suite.
+- GitHub Actions workflow running specs and RuboCop on Ruby 3.2 to 4.0.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vovka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# 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.
+
+## What you are looking at
+
+![Four processes running a suite as Matrix digital rain](docs/images/rain.png)
+
+A suite of 480 examples split across four processes. Nothing on this screen is a log line: every glyph is a
+piece of the test run.
+
+- **The rain.** Each row starts with a progress line: the time, then one column per process. A column is ten
+  characters wide, with the percentage of that process in red and random green half-width katakana filling the
+  rest. The katakana are drawn afresh for every row, so as the rows stack up the columns flicker and fall like
+  the digital rain, while the red percentages climb from 1% to 100% inside it.
+- **Passed examples.** After the progress line, every finished example adds one more symbol to the row, in the
+  order the results arrive from all processes. A passed example is one random green katakana, so a healthy suite
+  simply keeps raining.
+- **Failed examples.** A failure is the same kind of glyph, but red. It is a glitch in the Matrix: easy to miss
+  if you are not looking, impossible to unsee once you are.
+- **Pending examples.** A pending or skipped example becomes a 🥄. Do not try to run the pending test, that is
+  impossible. Instead, only try to realize the truth: there is no spoon.
+- **Silence.** Every example of this suite prints to stdout. None of it reaches the screen, see
+  [Output suppression](#output-suppression).
+
+Every row has a column for every process; a process that has not reported yet shows 0%, as three of them do in
+the first row. By default a new progress line is printed once a minute, and once more when every process reaches
+100%; this run uses `interval_seconds: 2` so the short demo suite produces enough rows.
+
+When the last process finishes, the rain stops and one consolidated report follows, in the style of RSpec's own:
+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.
+
+![A complete run: rain followed by the consolidated summary](docs/images/full_run.png)
+
+The time and the percentages can go down the rabbit hole too. With `digits: "ﾛｲｸﾖﾑﾗﾚﾇﾒﾜ"` each digit 0-9 is
+replaced by the character at that position:
+
+![Katakana digits](docs/images/katakana_digits.png)
+
+All symbols, colors, widths and the update frequency are configurable, see [Configuration](#configuration).
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+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.
+
+## Usage
+
+```sh
+bundle exec parallel_split_test --format ParallelMatrixFormatter::Formatter spec
+```
+
+The formatter also works with a single process:
+
+```sh
+bundle exec rspec --format ParallelMatrixFormatter::Formatter
+```
+
+The output looks like this (colors omitted):
+
+```
+17:04:13 ｷｺｼ89%ﾚﾐｴ､ｷｦｻ92%ｸｪｨｹ ｱｲｳ
+...
+
+Failures:
+
+  1) Widget does the thing
+     Failure/Error: expect(actual).to eq(expected)
+     ...
+
+Finished in 12.3 seconds (22.8 seconds across processes)
+8 examples, 2 failures, 2 pending
+
+Failed examples:
+
+rspec ./spec/widget_spec.rb:10 # Widget does the thing
+```
+
+## Configuration
+
+The defaults live in [`config/parallel_matrix_formatter.yml`](config/parallel_matrix_formatter.yml). To change
+them, create `config/parallel_matrix_formatter.yml` or `parallel_matrix_formatter.yml` in your project root, or
+point the `PARALLEL_MATRIX_FORMATTER_CONFIG` environment variable at a file. You only need to list the keys you
+change; everything else falls back to the defaults.
+
+The full schema, with the default values:
+
+```yaml
+# Redirect STDOUT and STDERR of every test process to /dev/null.
+suppress_output: true
+
+# Ten characters that replace the digits 0-9 in the time and the percentages.
+# Leave empty to keep plain digits.
+digits: ""
+
+# When to print a fresh progress line. The first rule that applies wins.
+progress_update:
+  always: false            # after every example
+  interval_seconds: 60     # at most once per interval, plus once when every process is done; 0 disables
+  percent_threshold: 0     # whenever any process advances by this many percent; 0 disables
+
+# The line showing the progress of every process.
+progress_line:
+  format: "\n{time} {columns} "   # placeholders: {time}, {columns}
+  column:                         # one column per process
+    width: 10
+    align: center                 # left, center or right
+    color: red                    # color of the percentage
+    pad_symbols: "ｱｲｳｴｵ..."       # characters picked at random to pad the column ("rain")
+    pad_color: green
+
+# The symbol printed after every example.
+example_status:
+  format: "{symbol}"              # placeholders: {symbol}, {process_letter} (A for process 1, B for 2, ...)
+  symbols:                        # one random character of the string is picked each time
+    passed: "ｱｲｳｴｵ..."
+    failed: "ｱｲｳｴｵ..."
+    pending: "🥄"
+  colors:
+    passed: green
+    failed: red
+    pending: yellow
+```
+
+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
+`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
+(instead of once a minute):
+
+```yaml
+progress_update:
+  interval_seconds: 0
+  percent_threshold: 10
+example_status:
+  symbols:
+    passed: "🟢"
+    failed: "🔴"
+    pending: "🟡"
+```
+
+## Output suppression
+
+With `suppress_output: true` (the default) the formatter reopens the STDOUT and STDERR file descriptors of every
+test process to `/dev/null`, and keeps a private copy of the original stdout for the display. Application logs,
+deprecation warnings, output of C extensions and child processes therefore cannot corrupt the display.
+
+- RSpec creates formatters only after the files given with `--require` (for example `rails_helper`) are loaded, so
+  output printed while the application boots is not covered. To silence that too, load the gem's silence file
+  first:
+
+  ```sh
+  RUBYOPT="-rparallel_matrix_formatter/silence" bundle exec parallel_split_test --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`.
+- If you pass `--out FILE` to RSpec, the display is written to that file instead of the terminal.
+
+## How it works
+
+Every test process loads the formatter. Process 1 (`TEST_ENV_NUMBER` empty or `1`) additionally hosts the
+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.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake          # runs the specs and RuboCop
+bundle exec rspec         # runs the specs in one process with RSpec's own formatter
+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
+whenever a process advances by 10 percent; to see the same locally:
+`PARALLEL_MATRIX_FORMATTER_CONFIG=.github/parallel_matrix_formatter.yml bundle exec rake`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/vovka/parallel_matrix_formatter. Please add specs
+for your changes and make sure `bundle exec rake` passes.
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/config/parallel_matrix_formatter.yml

@@ -0,0 +1,47 @@
+# Default configuration of parallel_matrix_formatter.
+#
+# Copy this file to config/parallel_matrix_formatter.yml (or
+# parallel_matrix_formatter.yml) in your project and change what you like.
+# Keys you leave out fall back to the values below.
+
+# Redirect stdout and stderr of every test process to /dev/null so application
+# output cannot corrupt the display. This hides crashes too: set it to false
+# when something goes wrong and you need to see why.
+suppress_output: true
+
+# Ten characters that replace the digits 0-9 in the time and the percentages,
+# e.g. "ﾛｲｸﾖﾑﾗﾚﾇﾒﾜ". Leave empty to keep plain digits.
+digits: ""
+
+# When to print a fresh progress line. The first rule that applies wins.
+progress_update:
+  always: false            # after every example
+  interval_seconds: 60     # at most once per interval, plus once when every process is done; 0 disables
+  percent_threshold: 0     # whenever any process advances by this many percent; 0 disables
+
+# The line showing every process's progress, e.g. "17:04:13 ｷｺｼ89%ﾚﾐｴ､ｷｦｻ92%ｸｪｨｹ".
+# Placeholders: {time}, {columns}.
+progress_line:
+  format: "\n{time} {columns} "
+  # One column per process: its percentage surrounded by random "rain" symbols.
+  column:
+    width: 10
+    align: center          # left, center or right
+    color: red
+    pad_symbols: "ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝｦｧｨｩｪｫｬｭｮｯｰ｢｣､"
+    pad_color: green
+
+# The symbol printed after every example.
+# Placeholders: {symbol}, {process_letter} (A for process 1, B for process 2, ...).
+example_status:
+  format: "{symbol}"
+  # One random character of the string is picked each time.
+  symbols:
+    passed: "ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝｦｧｨｩｪｫｬｭｮｯｰ｢｣､"
+    failed: "ｱｲｳｴｵｶｷｸｹｺｻｼｽｾｿﾀﾁﾂﾃﾄﾅﾆﾇﾈﾉﾊﾋﾌﾍﾎﾏﾐﾑﾒﾓﾔﾕﾖﾗﾘﾙﾚﾛﾜﾝｦｧｨｩｪｫｬｭｮｯｰ｢｣､"
+    pending: "🥄"
+  # Any color RSpec knows: black, red, green, yellow, blue, magenta, cyan, white, bold_red, ...
+  colors:
+    passed: green
+    failed: red
+    pending: yellow

data/lib/parallel_matrix_formatter/config.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module ParallelMatrixFormatter
+  # Loads the configuration: the gem's defaults deep-merged with the project's
+  # own file, so a project only has to spell out the keys it changes.
+  module Config
+    DEFAULTS_PATH = File.expand_path('../../config/parallel_matrix_formatter.yml', __dir__)
+    PROJECT_PATHS = ['parallel_matrix_formatter.yml', 'config/parallel_matrix_formatter.yml'].freeze
+
+    module_function
+
+    def load(path = project_path)
+      defaults = read(DEFAULTS_PATH)
+      path ? deep_merge(defaults, read(path)) : defaults
+    end
+
+    def project_path
+      ENV['PARALLEL_MATRIX_FORMATTER_CONFIG'] || PROJECT_PATHS.find { |path| File.exist?(path) }
+    end
+
+    def read(path)
+      YAML.safe_load_file(path) || {}
+    end
+
+    def deep_merge(base, overrides)
+      base.merge(overrides) do |_key, old_value, new_value|
+        old_value.is_a?(Hash) && new_value.is_a?(Hash) ? deep_merge(old_value, new_value) : new_value
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/formatter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'rspec/core/formatters/base_formatter'
+
+module ParallelMatrixFormatter
+  # The RSpec formatter loaded into every test process. It silences the
+  # process, turns RSpec notifications into IPC messages for the orchestrator
+  # and, in process 1, hosts the orchestrator that renders the shared display.
+  class Formatter < RSpec::Core::Formatters::BaseFormatter
+    RSpec::Core::Formatters.register self, :start, :example_started, :example_passed,
+                                     :example_failed, :example_pending, :dump_summary, :close
+
+    def initialize(output)
+      config = Config.load
+      super(display_output(config, output))
+      @process_number = [ENV['TEST_ENV_NUMBER'].to_i, 1].max
+      @orchestrator = Orchestrator.for(@process_number, total_processes, self.output, config)
+      @examples_run = 0
+      @failures = []
+    end
+
+    def start(notification)
+      @total_examples = notification.count
+      @client = Ipc::Client.connect
+    end
+
+    def example_started(_notification)
+      @examples_run += 1
+    end
+
+    def example_passed(_notification)
+      report(:passed)
+    end
+
+    def example_pending(_notification)
+      report(:pending)
+    end
+
+    def example_failed(notification)
+      @failures << failure_details(notification)
+      report(:failed)
+    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)
+    end
+
+    def close(_notification)
+      @client&.close
+      @orchestrator.close
+    end
+
+    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)
+      return output unless config['suppress_output']
+
+      terminal = Output::Silencer.silence
+      output.is_a?(File) ? output : terminal
+    end
+
+    def report(status)
+      progress = @examples_run.fdiv(@total_examples)
+      @client.notify(type: 'example', process: @process_number, status: status, progress: progress)
+    end
+
+    def failure_details(notification)
+      {
+        description: notification.description,
+        location: notification.example.location_rerun_argument,
+        message_lines: notification.colorized_message_lines(Rendering::Colors),
+        backtrace: notification.colorized_formatted_backtrace(Rendering::Colors)
+      }
+    end
+  end
+end

data/lib/parallel_matrix_formatter/ipc/client.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'socket'
+
+module ParallelMatrixFormatter
+  module Ipc
+    # Sends messages to the orchestrator's server.
+    class Client
+      # 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)
+        deadline = Time.now + timeout
+        begin
+          new(UNIXSocket.new(path))
+        rescue Errno::ENOENT, Errno::ECONNREFUSED
+          raise Error, "no orchestrator listening at #{path} after #{timeout}s" if Time.now > deadline
+
+          sleep 0.1
+          retry
+        end
+      end
+
+      def initialize(socket)
+        @socket = socket
+      end
+
+      def notify(message)
+        @socket.puts(JSON.generate(message))
+      end
+
+      def close
+        @socket.close
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/ipc/server.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'socket'
+
+module ParallelMatrixFormatter
+  module Ipc
+    # Accepts connections from every test process and queues their messages.
+    # 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)
+        FileUtils.rm_f(path)
+        @path = path
+        @socket = UNIXServer.new(path)
+        @messages = Queue.new
+        @acceptor = Thread.new { accept_clients }
+      end
+
+      # Yields messages in arrival order until the server is closed.
+      def each_message
+        while (message = @messages.pop)
+          yield message
+        end
+      end
+
+      def close
+        @socket.close
+        @messages.close
+        FileUtils.rm_f(@path)
+      end
+
+      private
+
+      def accept_clients
+        loop { Thread.new(@socket.accept) { |client| read(client) } }
+      rescue IOError, Errno::EBADF
+        nil # the socket was closed
+      end
+
+      def read(client)
+        process = nil
+        while (line = client.gets)
+          message = JSON.parse(line)
+          process = message['process']
+          enqueue(message)
+        end
+        enqueue('type' => 'disconnected', 'process' => process) if process
+      ensure
+        client.close
+      end
+
+      def enqueue(message)
+        @messages << message
+      rescue ClosedQueueError
+        nil # nobody is listening any more
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/ipc.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+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")
+    end
+  end
+end

data/lib/parallel_matrix_formatter/null_orchestrator.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  # Stands in for the Orchestrator in every process but process 1, which only
+  # report to the orchestrator and never render anything themselves.
+  class NullOrchestrator
+    def close; end
+  end
+end

data/lib/parallel_matrix_formatter/orchestrator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+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.
+  class Orchestrator
+    def self.for(process_number, total_processes, output, config)
+      return NullOrchestrator.new unless process_number == 1
+
+      new(total_processes, output, Rendering::Display.new(config, total_processes))
+    end
+
+    def initialize(total_processes, output, display)
+      @total_processes = total_processes
+      @output = output
+      @display = display
+      @summaries = {}
+      @disconnected = []
+      @server = Ipc::Server.new
+      @collector = Thread.new { collect_messages }
+    end
+
+    # Blocks until every process is done, then prints the summary.
+    def close
+      @collector.join
+      @output.puts @display.summary(@summaries.values, missing_processes)
+      @output.flush
+      @server.close
+    end
+
+    private
+
+    def collect_messages
+      @server.each_message do |message|
+        handle(message)
+        break if all_finished?
+      end
+    end
+
+    def handle(message)
+      case message['type']
+      when 'example' then print_example(message)
+      when 'summary' then @summaries[message['process']] = message
+      when 'disconnected' then @disconnected << message['process']
+      end
+    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) }
+    end
+
+    def missing_processes
+      (1..@total_processes).reject { |process| @summaries.key?(process) }
+    end
+  end
+end

data/lib/parallel_matrix_formatter/output/silencer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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.
+    module Silencer
+      class << self
+        # @return [IO] the original stdout
+        def silence
+          @terminal = redirect_to_null unless silenced?
+          @terminal
+        end
+
+        def silenced?
+          !@terminal.nil?
+        end
+
+        private
+
+        def redirect_to_null
+          terminal = STDOUT.dup
+          terminal.sync = true
+          STDOUT.reopen(File::NULL, 'w')
+          STDERR.reopen(File::NULL, 'w')
+          terminal
+        end
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/colors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'rspec/core/formatters/console_codes'
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Wraps text in ANSI color codes. Accepts the color names RSpec knows
+    # (red, green, bold_blue, ...) as well as RSpec's semantic names (failure,
+    # detail, ...), so it doubles as the colorizer for RSpec's failure output.
+    # Colors are always on, since CI logs render them, unless NO_COLOR is set.
+    module Colors
+      module_function
+
+      def wrap(text, color)
+        return text.to_s if color.nil? || text.to_s.empty? || disabled?
+
+        code = RSpec::Core::Formatters::ConsoleCodes.console_code_for(color.to_sym)
+        "\e[#{code}m#{text}\e[0m"
+      end
+
+      def disabled?
+        !ENV['NO_COLOR'].to_s.empty?
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/digits.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Replaces the digits 0-9 of a string with custom characters, e.g. katakana.
+    module Digits
+      module_function
+
+      def replace(text, symbols)
+        return text if symbols.nil? || symbols.empty?
+
+        replacements = symbols.chars
+        text.gsub(/\d/) { |digit| replacements[digit.to_i] || digit }
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/display.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Turns the orchestrator's events into terminal text. Remembers the latest
+    # progress of every process, starting at 0% for processes that have not
+    # reported yet, so every progress line shows one column per process.
+    class Display
+      def initialize(config, total_processes)
+        @progress = (1..total_processes).to_h { |process| [process, 0.0] }
+        @policy = ProgressUpdatePolicy.new(config['progress_update'], total_processes)
+        @progress_line = ProgressLine.new(config['progress_line'], config['digits'])
+        @example_status = ExampleStatus.new(config['example_status'])
+        @summary = Summary.new
+      end
+
+      # @return [String] the example's status symbol, preceded by a progress line when one is due
+      def example(process, status, progress)
+        @progress[process] = progress
+        line = @policy.update?(@progress) ? @progress_line.render(@progress) : ''
+        line + @example_status.render(process, status)
+      end
+
+      def summary(summaries, missing_processes)
+        @summary.render(summaries, missing_processes)
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/example_status.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Renders the symbol printed for one finished example: a random character
+    # from the configured set for its status, in the status's color.
+    class ExampleStatus
+      def initialize(config)
+        @format = config['format']
+        @symbols = config['symbols']
+        @colors = config['colors']
+      end
+
+      # @param status [String] "passed", "failed" or "pending"
+      def render(process, status)
+        text = @format.gsub('{symbol}', symbol(status)).gsub('{process_letter}', process_letter(process))
+        Colors.wrap(text, @colors[status])
+      end
+
+      private
+
+      def symbol(status)
+        @symbols[status].to_s.chars.sample.to_s
+      end
+
+      def process_letter(process)
+        ('A'.ord + process - 1).chr
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/progress_column.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Renders the percentage of one process padded to a fixed width with random
+    # "rain" symbols, e.g. "ｷｺｼ89%ﾚﾐｴ".
+    class ProgressColumn
+      def initialize(config, digits)
+        @width = config['width'].to_i
+        @align = config['align']
+        @color = config['color']
+        @pad_symbols = config['pad_symbols'].to_s.chars
+        @pad_symbols = [' '] if @pad_symbols.empty?
+        @pad_color = config['pad_color']
+        @digits = digits
+      end
+
+      def render(progress)
+        value = Digits.replace("#{(progress * 100).round}%", @digits)
+        left, right = padding_sizes([@width - value.length, 0].max)
+        Colors.wrap(rain(left), @pad_color) + Colors.wrap(value, @color) + Colors.wrap(rain(right), @pad_color)
+      end
+
+      private
+
+      def padding_sizes(total)
+        case @align
+        when 'left' then [0, total]
+        when 'right' then [total, 0]
+        else [total / 2, total - (total / 2)]
+        end
+      end
+
+      def rain(size)
+        Array.new(size) { @pad_symbols.sample }.join
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/progress_line.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Renders the line showing the progress of every process, e.g.
+    # "\n17:04:13 ｷｺｼ89%ﾚﾐｴ､ｷｦｻ92%ｸｪｨｹ ".
+    class ProgressLine
+      def initialize(config, digits)
+        @format = config['format']
+        @digits = digits
+        @column = ProgressColumn.new(config['column'], digits)
+      end
+
+      # @param progress [Hash{Integer => Float}] latest progress of every process
+      def render(progress)
+        columns = progress.sort.map { |_process, value| @column.render(value) }.join
+        @format.gsub('{time}', time).gsub('{columns}', columns)
+      end
+
+      private
+
+      def time
+        Digits.replace(Time.now.strftime('%H:%M:%S'), @digits)
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/progress_update_policy.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Decides whether a fresh progress line is due. The first configured rule
+    # wins: always, then the time interval, then the percentage threshold.
+    class ProgressUpdatePolicy
+      def initialize(config, total_processes)
+        @total_processes = total_processes
+        @always = config['always']
+        @interval = config['interval_seconds'].to_f
+        @threshold = config['percent_threshold'].to_f
+        @last_update_at = nil
+        @last_progress = {}
+      end
+
+      # @param progress [Hash{Integer => Float}] latest progress of every process
+      def update?(progress)
+        return true if @always
+        return interval_elapsed?(progress) if @interval.positive?
+        return threshold_crossed?(progress) if @threshold.positive?
+
+        false
+      end
+
+      private
+
+      def interval_elapsed?(progress)
+        due = @last_update_at.nil? || Time.now - @last_update_at >= @interval || all_complete?(progress)
+        @last_update_at = Time.now if due
+        due
+      end
+
+      def threshold_crossed?(progress)
+        crossed = progress.select { |process, value| crossed?(@last_progress[process], value) }
+        @last_progress.merge!(crossed)
+        crossed.any?
+      end
+
+      def crossed?(previous, current)
+        return true if previous.nil?
+        return true if current >= 1.0 && previous < 1.0
+
+        (current - previous) * 100 >= @threshold
+      end
+
+      def all_complete?(progress)
+        progress.size == @total_processes && progress.values.all? { |value| value >= 1.0 }
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/rendering/summary.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'rspec/core/formatters/helpers'
+
+module ParallelMatrixFormatter
+  module Rendering
+    # Renders the end-of-run report in the style of RSpec's own: every failure
+    # of every process, the totals and the commands to rerun the failures.
+    class Summary
+      Helpers = RSpec::Core::Formatters::Helpers
+
+      def initialize
+        @started_at = Time.now
+      end
+
+      # @param summaries [Array<Hash>] the summary message of every process that sent one
+      # @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)]
+        "\n#{sections.compact.join("\n")}"
+      end
+
+      private
+
+      def failures_section(failures)
+        return if failures.empty?
+
+        blocks = failures.each_with_index.map { |failure, index| failure_block(failure, index + 1) }
+        "\nFailures:\n\n#{blocks.join("\n")}"
+      end
+
+      def failure_block(failure, number)
+        indent = ' ' * (number.to_s.length + 4)
+        details = failure['message_lines'] + failure['backtrace']
+        ["  #{number}) #{failure['description']}", *details.map { |line| indent + line }, ''].join("\n")
+      end
+
+      def warnings(missing_processes)
+        return if missing_processes.empty?
+
+        processes = missing_processes.join(', ')
+        "\n#{Colors.wrap("WARNING: no summary received from process #{processes}, it probably crashed. " \
+                         'Set suppress_output: false to see its output.', :yellow)}"
+      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'] })
+        "\nFinished in #{Helpers.format_duration(Time.now - @started_at)} (#{process_time} across processes)\n" +
+          Colors.wrap(totals_line(examples, failures, pending), totals_color(failures, pending))
+      end
+
+      def totals_line(examples, failures, pending)
+        line = "#{Helpers.pluralize(examples, 'example')}, #{Helpers.pluralize(failures, 'failure')}"
+        pending.positive? ? "#{line}, #{pending} pending" : line
+      end
+
+      def totals_color(failures, pending)
+        return :failure if failures.positive?
+
+        pending.positive? ? :pending : :success
+      end
+
+      def rerun_section(failures)
+        return if failures.empty?
+
+        "\nFailed examples:\n\n#{failures.map { |failure| rerun_command(failure) }.join("\n")}"
+      end
+
+      def rerun_command(failure)
+        command = Colors.wrap("rspec #{failure['location']}", :failure)
+        "#{command} #{Colors.wrap("# #{failure['description']}", :detail)}"
+      end
+    end
+  end
+end

data/lib/parallel_matrix_formatter/silence.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Silences the process as early as possible. RSpec only instantiates the
+# formatter after the --require'd files have loaded, so output printed while
+# the application boots would otherwise reach the terminal. Load this file
+# before anything else to silence it:
+#
+#   RUBYOPT="-rparallel_matrix_formatter/silence" bundle exec parallel_split_test ...
+require_relative 'config'
+require_relative 'output/silencer'
+
+ParallelMatrixFormatter::Output::Silencer.silence if ParallelMatrixFormatter::Config.load['suppress_output']

data/lib/parallel_matrix_formatter/version.rb

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

data/lib/parallel_matrix_formatter.rb

@@ -0,0 +1,32 @@
+# 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.
+#
+# 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

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: parallel_matrix_formatter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Volodymyr Shcherbyna
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
+email:
+- scherbina.v@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/parallel_matrix_formatter.yml
+- lib/parallel_matrix_formatter.rb
+- lib/parallel_matrix_formatter/config.rb
+- lib/parallel_matrix_formatter/formatter.rb
+- lib/parallel_matrix_formatter/ipc.rb
+- lib/parallel_matrix_formatter/ipc/client.rb
+- lib/parallel_matrix_formatter/ipc/server.rb
+- lib/parallel_matrix_formatter/null_orchestrator.rb
+- lib/parallel_matrix_formatter/orchestrator.rb
+- lib/parallel_matrix_formatter/output/silencer.rb
+- lib/parallel_matrix_formatter/rendering/colors.rb
+- lib/parallel_matrix_formatter/rendering/digits.rb
+- lib/parallel_matrix_formatter/rendering/display.rb
+- lib/parallel_matrix_formatter/rendering/example_status.rb
+- lib/parallel_matrix_formatter/rendering/progress_column.rb
+- 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/silence.rb
+- lib/parallel_matrix_formatter/version.rb
+homepage: https://github.com/vovka/parallel_matrix_formatter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/vovka/parallel_matrix_formatter
+  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'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Matrix digital rain RSpec formatter for parallel_split_test
+test_files: []