rspec-capturing-formatter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be7b57d6badad05069b5d4bed0fc557a75ddd0de583aa4b5c64a45bd21c96766
+  data.tar.gz: 1633b80c3ea60608b64401b4dca9e92c3d9ebb7ca11bcf18b4e7ce2021894037
+SHA512:
+  metadata.gz: 2cc8b9cc8124ce483eb6b130b61256340c6891c06ec4c6483b39177825022433bf58f9378c089bca4991070c3a3b5fb025662cd5e2da37a8faa7f112b330fe9b
+  data.tar.gz: 3cd510e72dedce015cb6ab9fc9fd5a76513d93511f609fa72e902d0cc90395e93070d2e6e13470a91343ee908ffd7b8dfb7f3d79aee862791bf210c463e74fd5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hongli Lai
+
+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,111 @@
+# rspec-capturing-formatter
+
+`rspec-capturing-formatter` is an RSpec formatter that keeps test progress readable when examples write logs to stdout or stderr. This is especially helpful in CI, where interleaved output can make it difficult to tell which example produced a particular log message. By keeping output clearly associated with the example that produced it, the formatter makes failures easier to understand and debug.
+
+Example:
+
+```text
+A car › it is red
+  ✅ succeeded
+
+A car › it beeps when there is danger
+  stdout | starting engine
+  stderr | warning: beeper initialization delayed
+  ✅ succeeded  812 ms
+
+A car › during maintenance mode
+  suite stdout | preparing maintenance fixtures
+
+A car › during maintenance mode › it disables safety guardrails
+  stdout | frobnicating the door
+  ❌ failed  2.00 s
+  rerun  | rspec ./spec/car_spec.rb:20
+
+  Failure/Error: raise "test"
+
+  RuntimeError:
+    test
+
+  diagnostic state: maintenance
+
+  # ./spec/car_spec.rb:20
+
+1 deprecation warning total
+
+Summary
+  3 total  2 succeeded  1 failed  0 pending
+  Finished in 2.90 s  |  files loaded in 98.9 ms
+
+Failed examples
+  rspec ./spec/car_spec.rb:20
+```
+
+Color and emphasis are omitted from this example. Actual output uses color and emoji when supported.
+
+> [!NOTE]
+> On Windows, rerun lines look super weird, like this:
+>
+> ```
+>   rerun  | ruby -e ^"ARGV^[0^]=ARGV.fetch^(0^).unpack1^(\^"m0\^"^).force_encoding^(\^"UTF-8\^"^)^;load^(Gem.bin_path^(\^"rspec-core\^"^,\^"rspec\^"^)^)^" Li9zcGVjL3VuaXQvd2luZG93c19jb21tYW5kX2xpbmVfc3BlYy5yYjo3Ng==
+> ```
+>
+> This is because Windows cmd.exe escaping rules are super complicated. On Windows, RubyGems-installed commands such as `rspec` are actually `.bat` files, thus involving multiple layers of cmd.exe quoting. It's not as straightforward as on Unix where you just escape the value multiple times.
+>
+> So I gave up. On Windows, rerun commands invoke Ruby directly and contain a Base64-encoded target that doesn't produce any escaping issues. It looks weird, but it works. The LLM gave up trying to solve this problem "properly" after many hours of runs. If you care to improve this, a pull request (with extensive tests) is welcome.
+
+## Usage
+
+Add to your Gemfile:
+
+```ruby
+gem "rspec-capturing-formatter"
+
+# For terminal color support on Windows
+gem "fiddle", platforms: [:windows]
+```
+
+Add the formatter to `.rspec`:
+
+```text
+--require rspec/capturing_formatter
+--format RSpec::CapturingFormatter
+```
+
+List `rspec/capturing_formatter` before other early-required files that construct loggers. This allows output from those loggers to be included in the report.
+
+Before an RSpec run starts, requiring the formatter does not hide or buffer boot output. Code that requires `$stdout` or `$stderr` to be an actual `IO` should not require this gem unless it uses the formatter.
+
+Use this as the sole human-readable console formatter. Machine formatters may still write to separate files:
+
+```sh
+bundle exec rspec \
+  --require rspec/capturing_formatter \
+  --format RSpec::CapturingFormatter \
+  --format json --out tmp/rspec.json
+```
+
+## Configuration
+
+Defaults can be changed with a Ruby configuration block:
+
+```ruby
+RSpec::CapturingFormatter.configure do |config|
+  config.slow_threshold = 0.5 # seconds; nil disables per-example timing
+  config.separator = " › "
+  config.color = true
+  config.emoji = :auto       # :auto, true, or false
+  config.pending_failure_output = :full # :full, :no_backtrace, or :skip
+end
+```
+
+When `config.color == true`, coloring is enabled even when there is no TTY. Coloring is always disabled when `NO_COLOR` or when RSpec's `--no-color` option is set.
+
+On Windows, interactive coloring is supported in Windows Terminal. Legacy Windows console sessions are not supported color targets and receive plain-text output instead of raw ANSI escape sequences. Redirected reports keep ANSI coloring when enabled, so they can be viewed by ANSI-aware CI logs or tools.
+
+## Output capture limitations
+
+The formatter captures writes made through `$stdout` and `$stderr` after the formatter is loaded. This includes calls to bare `puts`, `print`, `warn`, and calls to typical Ruby `Logger` instances that log to stdout or stderr.
+
+This formatter does not capture direct native writes to file descriptors 1 or 2, or output written by subprocesses.
+
+Same-process parallel example runners are unsupported because the formatter cannot reliably assign simultaneous stdout and stderr writes to individual examples. Multi-process runners may be used, but the runner is responsible for keeping each process's report together.

data/Rakefile

@@ -0,0 +1,80 @@
+require "bundler/gem_tasks"
+
+task default: :spec
+
+desc "Run RSpec code examples"
+task :spec do
+  rspec_args = []
+
+  if ENV["DOGFOOD"]
+    rspec_args << "--require"
+    rspec_args << "./lib/rspec/capturing_formatter"
+    rspec_args << "--format"
+    rspec_args << "RSpec::CapturingFormatter"
+  end
+  if ENV["FORCE_COLOR"]
+    rspec_args << "--force-color"
+  end
+  if (file = ENV["FILE"])
+    rspec_args << file
+  end
+  if (example = ENV["EXAMPLE"])
+    rspec_args << "-e"
+    rspec_args << example
+  end
+
+  ruby(*[
+    "--enable=frozen-string-literal",
+    "-S",
+    "rspec",
+    rspec_args
+  ].flatten.compact)
+end
+
+def tested_rspec_versions
+  @tested_rspec_versions ||= Dir["gemfiles/*.gemfile"].map do |path|
+    File.basename(path).sub(/\..*/, "")
+  end
+end
+
+desc "Run bundle install for all Gemfiles"
+task "bundle:install" => [
+  "bundle:install:main",
+  tested_rspec_versions.map { |rspec_version| "bundle:install:#{rspec_version}" }
+].flatten
+
+desc "Run bundle update for all Gemfiles"
+task "bundle:update" => [
+  "bundle:update:main",
+  tested_rspec_versions.map { |rspec_version| "bundle:update:#{rspec_version}" }
+].flatten
+
+desc "Run bundle install for main Gemfile"
+task "bundle:install:main" do
+  Bundler.with_unbundled_env do
+    sh "bundle install"
+  end
+end
+
+desc "Run bundle update for main Gemfile"
+task "bundle:update:main" do
+  Bundler.with_unbundled_env do
+    sh "bundle update --all"
+  end
+end
+
+tested_rspec_versions.each do |rspec_version|
+  desc "Run bundle install for #{rspec_version} Gemfile"
+  task "bundle:install:#{rspec_version}" do
+    Bundler.with_unbundled_env do
+      sh "env BUNDLE_GEMFILE=gemfiles/#{Shellwords.escape(rspec_version)}.gemfile bundle install"
+    end
+  end
+
+  desc "Run bundle update for #{rspec_version} Gemfile"
+  task "bundle:update:#{rspec_version}" do
+    Bundler.with_unbundled_env do
+      sh "env BUNDLE_GEMFILE=gemfiles/#{Shellwords.escape(rspec_version)}.gemfile bundle update --all"
+    end
+  end
+end

data/lib/rspec/capturing_formatter/configuration.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RSpec
+  class CapturingFormatter
+    class Configuration
+      attr_reader :slow_threshold, :separator, :color, :emoji
+
+      def initialize
+        @slow_threshold = 0.5
+        @separator = " › "
+        @color = true
+        @emoji = :auto
+        @pending_failure_output = nil
+      end
+
+      def slow_threshold=(value)
+        valid = value.nil? || (value.is_a?(Numeric) && value >= 0)
+        unless valid
+          raise ArgumentError, "slow_threshold must be a non-negative number or nil"
+        end
+
+        @slow_threshold = value
+      end
+
+      def separator=(value)
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError, "separator must be a non-empty string"
+        end
+
+        @separator = value
+      end
+
+      def color=(value)
+        unless value == true || value == false
+          raise ArgumentError, "color must be true or false"
+        end
+
+        @color = value
+      end
+
+      def emoji=(value)
+        unless [:auto, true, false].include?(value)
+          raise ArgumentError, "emoji must be :auto, true, or false"
+        end
+
+        @emoji = value
+      end
+
+      # Keep "unset" distinct from explicit :full so CapturingFormatter can inherit RSpec's setting.
+      def pending_failure_output=(value)
+        unless [:full, :no_backtrace, :skip].include?(value)
+          raise ArgumentError, "pending_failure_output must be :full, :no_backtrace, or :skip"
+        end
+
+        @pending_failure_output = value
+      end
+
+      def pending_failure_output
+        @pending_failure_output || :full
+      end
+
+      def pending_failure_output_configured?
+        !@pending_failure_output.nil?
+      end
+
+      def to_h
+        {
+          slow_threshold: @slow_threshold,
+          separator: @separator,
+          color: @color,
+          emoji: @emoji,
+          pending_failure_output: pending_failure_output
+        }
+      end
+    end
+  end
+end