parallel_specs 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31a954499f658d2d18df5d6126b522cf299985b33f68e5016d8a19de4e1369bd
-  data.tar.gz: 80789703549b936ae3b97309b0979a72d6799f10cd3ab604f11b7f3ed316509c
+  metadata.gz: 7220b40d98f5c203c37cc69d12e9145e909dd4877d35e77fb0ae011f23ab3d3e
+  data.tar.gz: 40eadee9e0eb4748c3c17ad8c4b0bf016328c4564d655e014c8a0e22fbc5ae81
 SHA512:
-  metadata.gz: f994089098548075cccb2591e4e56dee64aee54fd861b92a30573a62e1358323b1bbf300af645f8aab23e6a5334c0f0b27cd834f61ffc118575f8c3e4737c83f
-  data.tar.gz: b6cf4496f6703d1d11d9375408bf718b7adf5c74327c8a9f12212b2956e17aabbb234f752092dbe44f4a97f5f9510351b32b5733f4f4646d8cd80ca6388bdbcb
+  metadata.gz: 83ae2b21bd87c2445be0a1af045df3a2e0563a84eded7c62d08cb47792f7bc73d55f6416dea0aaa37b3ae49ebac3876804eb391c5219ff4c521e88074188aed5
+  data.tar.gz: 12bef5dbb566c689b5721f5a88339a69c3936eae64f1251977b4e1c847de2ab41c5e518d911ea31a4405321bbf9a2fabc6dd35d5942cc44ce35c7ec0e0015d76

data/README.md

@@ -9,16 +9,47 @@ A focused extraction of the RSpec pieces from `parallel_tests` with only the par
 - runtime-log generation for balanced spec splitting
 - modern Ruby only
 
+## Setup
+
+Add the gem to your app's Gemfile:
+
+```ruby
+group :test do
+  gem 'parallel_specs'
+end
+```
+
+Then install it:
+
+```bash
+bundle install
+```
+
+For Rails apps, configure the test database name to include `TEST_ENV_NUMBER`. The first worker uses a blank value, then workers 2, 3, and so on use their worker number:
+
+```yaml
+# config/database.yml
+test:
+  database: my_app_test<%= ENV['TEST_ENV_NUMBER'] %>
+```
+
+If you previously used `parallel_tests`, this is the same database naming convention. Once the `parallel_specs` Rake tasks are available, you can remove `parallel_tests` if you were only keeping it for database setup.
+
 ## Commands
 
 ```bash
 bundle exec parallel_specs
 bundle exec parallel_specs -n 6
+bundle exec parallel_specs --dashboard-mode plain
+bundle exec parallel_specs --plain
+bundle exec parallel_specs --plain-dashboard
 bundle exec parallel_specs --test-options='--tag ~type:system'
 bundle exec parallel_specs --record-runtime
 ```
 
-Local TTY runs render the interactive dashboard. CI and other non-TTY runs automatically fall back to the plain text summary.
+Local TTY runs render the interactive dashboard. CI and other non-TTY runs automatically fall back to the plain text summary. Use `--plain`, `--dashboard-mode plain`, or `--plain-dashboard` to force plain dashboard output without setting an environment variable.
+
+Plain dashboard output is intentionally minimal: it prints the examples counter and elapsed time, then relies on the process exit status and the final RSpec summary for success or failure. It does not print per-worker rows or current example names.
 
 ## Runtime balancing
 
@@ -40,15 +71,70 @@ bundle exec parallel_specs --record-runtime --runtime-log tmp/my_runtime.log
 
 `--runtime-log PATH` is used as the input path for balancing and, with `--record-runtime`, as the output destination for the completed run.
 
+## Rails database tasks
+
+Rails apps that use `TEST_ENV_NUMBER` in `config/database.yml` can prepare per-worker test databases without depending on `parallel_tests`.
+
+The most common workflow is:
+
+```bash
+# Create all worker databases once
+bundle exec rake parallel:create
+
+# Load the current schema into each worker database
+bundle exec rake parallel:load_schema
+
+# Run the specs
+bundle exec parallel_specs
+```
+
+After changing migrations, refresh the worker databases with:
+
+```bash
+bundle exec rake parallel:prepare
+```
+
+`parallel:prepare` checks for pending migrations, dumps the schema or structure once, and then loads it into each worker database.
+
+To reset everything from scratch:
+
+```bash
+bundle exec rake parallel:drop
+bundle exec rake parallel:create
+bundle exec rake parallel:load_schema
+```
+
+Each task accepts an optional worker count:
+
+```bash
+bundle exec rake 'parallel:create[4]'
+bundle exec rake 'parallel:prepare[4]'
+bundle exec parallel_specs -n 4
+```
+
+If no count is provided, the tasks use `PARALLEL_SPECS_PROCESSORS` or the detected processor count. Use the same count for database prep and spec runs.
+
+The gem also exposes compatible `parallel:setup`, `parallel:migrate`, `parallel:rollback`, `parallel:load_structure`, `parallel:seed`, and `parallel:rake` tasks.
+
+Set `PARALLEL_SPECS_RAILS_ENV` to prepare an environment other than `test`.
+
 ## Environment variables
 
 The supported environment variables are:
 
-- `PARALLEL_SPECS_PROCESSORS` sets the default worker count when `-n` is not provided.
-- `PARALLEL_SPECS_DASHBOARD_MODE` can be `interactive` or `plain` to override automatic dashboard selection.
+- `PARALLEL_SPECS_PROCESSORS` sets the default worker count when `-n` is not provided and when Rails database tasks are run without a count.
+- `PARALLEL_SPECS_DASHBOARD_MODE` can be `interactive` or `plain` to override automatic dashboard selection. You can also use `--plain`, `--dashboard-mode plain`, or `--plain-dashboard` for a single run.
 - `PARALLEL_SPECS_HEARTBEAT_INTERVAL` sets the plain-dashboard heartbeat interval in seconds.
+- `PARALLEL_SPECS_FULL_RERUN_COMMANDS=1` prints full failed-worker rerun commands even when they are long.
+- `PARALLEL_SPECS_RERUN_COMMAND_SPEC_FILE_LIMIT` sets how many spec files a failed-worker rerun command may include before it is summarized instead of printed. The default is 25.
+- `PARALLEL_SPECS_RERUN_COMMAND_CHAR_LIMIT` sets the maximum failed-worker rerun command length before it is summarized instead of printed. The default is 2000.
+- `PARALLEL_SPECS_RAILS_ENV` sets the Rails environment used by the `parallel:*` database tasks. The default is `test`.
 - `CI` makes dashboard output default to plain mode.
 
 Worker processes continue to receive `TEST_ENV_NUMBER` for compatibility with existing test-environment isolation setup.
 
 This gem does not intentionally preserve the old `parallel_tests` executable names, formatter paths, or environment variable aliases.
+
+## Acknowledgements
+
+This gem is largely based on the excellent work from [`parallel_tests`](https://github.com/grosser/parallel_tests), especially its approach to grouping test files, assigning `TEST_ENV_NUMBER`, and preparing per-worker Rails test databases.

data/lib/parallel_specs/cli/dashboard.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'io/console'
-require 'uri'
+require "json"
+require "io/console"
+require "strscan"
 
 module ParallelSpecs
   class CLI
@@ -20,7 +20,7 @@ module ParallelSpecs
         :exit_status
       )
 
-      SPINNER = ['-', '\\', '|', '/'].freeze
+      SPINNER = ["-", "\\", "|", "/"].freeze
       PROGRESS_BAR_WIDTH = 24
       REFRESH_INTERVAL = 0.1
 
@@ -45,7 +45,8 @@ module ParallelSpecs
         @event_offsets = Hash.new(0)
         @event_remainders = Hash.new { |hash, key| hash[key] = +"" }
         @spinner_index = 0
-        @rendered_lines = 0
+        @rendered_rows = 0
+        @last_frame = nil
         @dirty = true
       end
 
@@ -70,7 +71,7 @@ module ParallelSpecs
                 render if @dirty
               end
             end
-          rescue StandardError => e
+          rescue => e
             @running = false
             warn "parallel_specs: dashboard refresh failed while polling #{event_file_context}: #{e.class}: #{e.message}"
           end
@@ -84,7 +85,7 @@ module ParallelSpecs
         @mutex.synchronize do
           begin
             poll_once
-          rescue StandardError => e
+          rescue => e
             warn "parallel_specs: dashboard final poll failed while polling #{event_file_context}: #{e.class}: #{e.message}"
           end
           render
@@ -115,20 +116,20 @@ module ParallelSpecs
         worker = @workers.fetch(process_number)
         worker.started_at ||= @now.call
 
-        case event.fetch('event')
-        when 'start'
-          worker.example_total = event['total']
-        when 'example_started'
-          worker.current_example = event['example']
-        when 'example_passed'
+        case event.fetch("event")
+        when "start"
+          worker.example_total = event["total"]
+        when "example_started"
+          worker.current_example = event["example"]
+        when "example_passed"
           worker.passed += 1
-          worker.current_example = event['example']
-        when 'example_pending'
+          worker.current_example = event["example"]
+        when "example_pending"
           worker.pending += 1
-          worker.current_example = event['example']
-        when 'example_failed'
+          worker.current_example = event["example"]
+        when "example_failed"
           worker.failed += 1
-          worker.current_example = event['example']
+          worker.current_example = event["example"]
         end
 
         @dirty = true
@@ -138,7 +139,7 @@ module ParallelSpecs
         @event_files.each do |process_number, path|
           next unless File.exist?(path)
 
-          File.open(path, 'r') do |file|
+          File.open(path, "r") do |file|
             file.seek(@event_offsets[process_number])
             chunk = file.read.to_s
             @event_offsets[process_number] = file.pos
@@ -151,7 +152,11 @@ module ParallelSpecs
             lines.each do |line|
               next if line.empty?
 
-              process_event(process_number, JSON.parse(line))
+              begin
+                process_event(process_number, JSON.parse(line))
+              rescue JSON::ParserError, KeyError => e
+                warn "parallel_specs: dashboard event ignored while polling worker #{process_number + 1}=#{path}: #{e.class}: #{e.message}"
+              end
             end
           end
         end
@@ -161,7 +166,7 @@ module ParallelSpecs
         lines = if interactive?
           [header_line, *workers.map { |worker| worker_line(worker) }]
         else
-          [plain_header_line, *workers.map { |worker| plain_worker_line(worker) }]
+          [plain_header_line]
         end
         "#{lines.join("\n")}\n"
       end
@@ -173,7 +178,7 @@ module ParallelSpecs
       end
 
       def event_file_context
-        @event_files.map { |process_number, path| "worker #{process_number + 1}=#{path}" }.join(', ')
+        @event_files.map { |process_number, path| "worker #{process_number + 1}=#{path}" }.join(", ")
       end
 
       def render
@@ -186,14 +191,20 @@ module ParallelSpecs
       end
 
       def render_interactive
+        @render_width = terminal_width
         output = frame
-        if @rendered_lines > 0
-          @output.print("\e[#{@rendered_lines}A")
+        rows_to_clear = [@rendered_rows, rendered_rows_for(@last_frame, @render_width)].max
+
+        if rows_to_clear.positive?
+          @output.print("\e[#{rows_to_clear}A")
           @output.print("\r\e[J")
         end
         @output.print(output)
         @output.flush if @output.respond_to?(:flush)
-        @rendered_lines = output.lines.count
+        @rendered_rows = rendered_rows_for(output, @render_width)
+        @last_frame = output
+      ensure
+        @render_width = nil
       end
 
       def render_plain
@@ -202,29 +213,18 @@ module ParallelSpecs
       end
 
       def header_line
-        running = workers.count { |worker| status_for(worker) == :running }
-        passed = workers.count { |worker| status_for(worker) == :passed }
-        failed = workers.count { |worker| [:failing, :failed].include?(status_for(worker)) }
         examples_seen = workers.sum { |worker| examples_seen_for(worker) }
         total_examples = workers.filter_map(&:example_total)
         example_summary = if total_examples.empty?
           "examples: #{examples_seen}"
         else
           summary = "examples: #{examples_seen}/#{total_examples.sum}"
-          summary += ' known' unless total_examples.size == workers.size
+          summary += " known" unless total_examples.size == workers.size
           summary
         end
 
         truncate(
-          [
-            'Parallel RSpec dashboard',
-            "workers: #{workers.size}",
-            "running: #{running}",
-            "passed: #{passed}",
-            "failed: #{failed}",
-            example_summary,
-            "elapsed: #{format_duration(elapsed_seconds)}"
-          ].join(' | '),
+          [example_summary, "elapsed: #{format_duration(elapsed_seconds)}"].join(" | "),
           terminal_width
         )
       end
@@ -242,65 +242,23 @@ module ParallelSpecs
           failed: worker.failed,
           pending: worker.pending
         )
-        line += " | #{worker.current_example}" if worker.current_example
         truncate(line, terminal_width)
       end
 
       def plain_header_line
-        running = workers.count { |worker| status_for(worker) == :running }
-        passed = workers.count { |worker| status_for(worker) == :passed }
-        failed = workers.count { |worker| [:failing, :failed].include?(status_for(worker)) }
-        examples_seen = workers.sum { |worker| examples_seen_for(worker) }
-        total_examples = workers.filter_map(&:example_total)
-
-        parts = [
-          'dashboard',
-          "workers=#{workers.size}",
-          "running=#{running}",
-          "passed=#{passed}",
-          "failed=#{failed}",
-          "examples_seen=#{examples_seen}",
-          "elapsed=#{format_duration(elapsed_seconds)}"
-        ]
-
-        unless total_examples.empty?
-          parts << "examples_total=#{total_examples.sum}"
-          parts << "examples_known=#{total_examples.size == workers.size}"
-        end
-
-        parts.join(' ')
-      end
-
-      def plain_worker_line(worker)
-        parts = [
-          "worker=#{worker.label}",
-          "status=#{plain_status_text_for(worker)}",
-          "passed=#{worker.passed}",
-          "failed=#{worker.failed}",
-          "pending=#{worker.pending}",
-          "current_example=#{encode_plain_value(worker.current_example.to_s)}"
-        ]
-
-        if worker.example_total
-          parts << "completed=#{examples_seen_for(worker)}"
-          parts << "total=#{worker.example_total}"
-        else
-          parts << "files=#{worker.files_count}"
-        end
-
-        parts.join(' ')
+        header_line
       end
 
       def progress_summary_for(worker)
         if worker.example_total
-          format('%<completed>d/%<total>d', completed: examples_seen_for(worker), total: worker.example_total)
+          format("%<completed>d/%<total>d", completed: examples_seen_for(worker), total: worker.example_total)
         else
-          format('files:%<count>3d', count: worker.files_count)
+          format("files:%<count>3d", count: worker.files_count)
         end
       end
 
       def progress_bar_for(worker)
-        return "[#{'.' * PROGRESS_BAR_WIDTH}]" unless worker.example_total
+        return "[#{"." * PROGRESS_BAR_WIDTH}]" unless worker.example_total
 
         total = worker.example_total
         completed = [examples_seen_for(worker), total].min
@@ -310,7 +268,7 @@ module ParallelSpecs
           [(completed.to_f / total * PROGRESS_BAR_WIDTH).round, PROGRESS_BAR_WIDTH].min
         end
         empty = PROGRESS_BAR_WIDTH - filled
-        "[#{'#' * filled}#{'-' * empty}]"
+        "[#{"#" * filled}#{"-" * empty}]"
       end
 
       def examples_seen_for(worker)
@@ -335,21 +293,11 @@ module ParallelSpecs
 
       def status_text_for(worker)
         case status_for(worker)
-        when :queued then '· queued'
+        when :queued then "· queued"
         when :running then "#{SPINNER[@spinner_index % SPINNER.length]} running"
-        when :failing then '! failing'
-        when :failed then '✗ failed'
-        when :passed then '✓ passed'
-        end
-      end
-
-      def plain_status_text_for(worker)
-        case status_for(worker)
-        when :queued then 'queued'
-        when :running then 'running'
-        when :failing then 'failing'
-        when :failed then 'failed'
-        when :passed then 'passed'
+        when :failing then "! failing"
+        when :failed then "✗ failed"
+        when :passed then "✓ passed"
         end
       end
 
@@ -362,10 +310,6 @@ module ParallelSpecs
         end
       end
 
-      def encode_plain_value(value)
-        URI.encode_www_form_component(value)
-      end
-
       def colorize(text, color)
         return text unless @use_colors
 
@@ -388,27 +332,63 @@ module ParallelSpecs
         remaining_seconds = seconds % 60
 
         if hours > 0
-          format('%<hours>d:%<minutes>02d:%<seconds>02d', hours: hours, minutes: minutes, seconds: remaining_seconds)
+          format("%<hours>d:%<minutes>02d:%<seconds>02d", hours: hours, minutes: minutes, seconds: remaining_seconds)
         else
-          format('%<minutes>02d:%<seconds>02d', minutes: minutes, seconds: remaining_seconds)
+          format("%<minutes>02d:%<seconds>02d", minutes: minutes, seconds: remaining_seconds)
         end
       end
 
       def terminal_width
-        @terminal_width ||= @width || begin
+        return @render_width if @render_width
+
+        width = if @width.respond_to?(:call)
+          @width.call
+        elsif @width
+          @width
+        else
           console = IO.console
           console&.winsize&.last || 120
-        rescue StandardError
-          120
+        end
+
+        [width.to_i - 1, 1].max
+      rescue
+        119
+      end
+
+      def rendered_rows_for(output, width)
+        return 0 if output.to_s.empty?
+
+        output.lines.sum do |line|
+          visible_width = visible_length(line.chomp)
+          [((visible_width - 1) / width) + 1, 1].max
         end
       end
 
       def truncate(text, max_length)
-        return '' if max_length <= 0
-        return text if text.length <= max_length
-        return text[0, max_length] if max_length <= 1
+        return "" if max_length <= 0
+        return text if visible_length(text) <= max_length
+        return "…" if max_length <= 1
+
+        truncated = +""
+        visible_count = 0
+        scanner = StringScanner.new(text)
+
+        until scanner.eos? || visible_count >= max_length - 1
+          if (escape_sequence = scanner.scan(/\e\[[\d;]*m/))
+            truncated << escape_sequence
+          else
+            truncated << scanner.getch
+            visible_count += 1
+          end
+        end
+
+        truncated << "…"
+        truncated << "\e[0m" if text.include?("\e[")
+        truncated
+      end
 
-        "#{text[0, max_length - 1]}…"
+      def visible_length(text)
+        text.gsub(/\e\[[\d;]*m/, "").length
       end
     end
   end