rspec-html_messages 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ddb6067bea7df00b60a4a696657f5bb4e6f2e16d889474b3c4aeb486b4f62932
+  data.tar.gz: 7637184a8d916d43fd76c63e97d198b39887d415c563d6291ab6f0396f334405
+SHA512:
+  metadata.gz: c727f783901d4cac2166281397d08c377742b772d6da96a7411b983730cc0cedcb6eb780660bd004dc97e982a86284c6e0f7147c67e891e1578bde816ac9dc22
+  data.tar.gz: 8e2a42829abb1483db1466c955da35d321be7be82f1b8ce3ad354b02643c4248cd44a1bdda4b5c89f85ddf12d6acd1b01e84bcaf769ceb71406c1cf3d885a24f

data/LICENSE.md

@@ -0,0 +1,134 @@
+= Hippocratic License
+
+Version: 2.1.0.
+
+Purpose. The purpose of this License is for the Licensor named above to
+permit the Licensee (as defined below) broad permission, if consistent
+with Human Rights Laws and Human Rights Principles (as each is defined
+below), to use and work with the Software (as defined below) within the
+full scope of Licensor’s copyright and patent rights, if any, in the
+Software, while ensuring attribution and protecting the Licensor from
+liability.
+
+Permission and Conditions. The Licensor grants permission by this
+license ("License"), free of charge, to the extent of Licensor’s
+rights under applicable copyright and patent law, to any person or
+entity (the "Licensee") obtaining a copy of this software and
+associated documentation files (the "Software"), to do everything with
+the Software that would otherwise infringe (i) the Licensor’s copyright
+in the Software or (ii) any patent claims to the Software that the
+Licensor can license or becomes able to license, subject to all of the
+following terms and conditions:
+
+* Acceptance. This License is automatically offered to every person and
+entity subject to its terms and conditions. Licensee accepts this
+License and agrees to its terms and conditions by taking any action with
+the Software that, absent this License, would infringe any intellectual
+property right held by Licensor.
+* Notice. Licensee must ensure that everyone who gets a copy of any part
+of this Software from Licensee, with or without changes, also receives
+the License and the above copyright notice (and if included by the
+Licensor, patent, trademark and attribution notice). Licensee must cause
+any modified versions of the Software to carry prominent notices stating
+that Licensee changed the Software. For clarity, although Licensee is
+free to create modifications of the Software and distribute only the
+modified portion created by Licensee with additional or different terms,
+the portion of the Software not modified must be distributed pursuant to
+this License. If anyone notifies Licensee in writing that Licensee has
+not complied with this Notice section, Licensee can keep this License by
+taking all practical steps to comply within 30 days after the notice. If
+Licensee does not do so, Licensee’s License (and all rights licensed
+hereunder) shall end immediately.
+* Compliance with Human Rights Principles and Human Rights Laws.
+[arabic]
+. Human Rights Principles.
+[loweralpha]
+.. Licensee is advised to consult the articles of the United Nations
+Universal Declaration of Human Rights and the United Nations Global
+Compact that define recognized principles of international human rights
+(the "Human Rights Principles"). Licensee shall use the Software in a
+manner consistent with Human Rights Principles.
+.. Unless the Licensor and Licensee agree otherwise, any dispute,
+controversy, or claim arising out of or relating to (i) Section 1(a)
+regarding Human Rights Principles, including the breach of Section 1(a),
+termination of this License for breach of the Human Rights Principles,
+or invalidity of Section 1(a) or (ii) a determination of whether any Law
+is consistent or in conflict with Human Rights Principles pursuant to
+Section 2, below, shall be settled by arbitration in accordance with the
+Hague Rules on Business and Human Rights Arbitration (the "Rules");
+provided, however, that Licensee may elect not to participate in such
+arbitration, in which event this License (and all rights licensed
+hereunder) shall end immediately. The number of arbitrators shall be one
+unless the Rules require otherwise.
++
+Unless both the Licensor and Licensee agree to the contrary: (1) All
+documents and information concerning the arbitration shall be public and
+may be disclosed by any party; (2) The repository referred to under
+Article 43 of the Rules shall make available to the public in a timely
+manner all documents concerning the arbitration which are communicated
+to it, including all submissions of the parties, all evidence admitted
+into the record of the proceedings, all transcripts or other recordings
+of hearings and all orders, decisions and awards of the arbitral
+tribunal, subject only to the arbitral tribunal’s powers to take such
+measures as may be necessary to safeguard the integrity of the arbitral
+process pursuant to Articles 18, 33, 41 and 42 of the Rules; and (3)
+Article 26(6) of the Rules shall not apply.
+. Human Rights Laws. The Software shall not be used by any person or
+entity for any systems, activities, or other uses that violate any Human
+Rights Laws. "Human Rights Laws" means any applicable laws,
+regulations, or rules (collectively, "Laws") that protect human,
+civil, labor, privacy, political, environmental, security, economic, due
+process, or similar rights; provided, however, that such Laws are
+consistent and not in conflict with Human Rights Principles (a dispute
+over the consistency or a conflict between Laws and Human Rights
+Principles shall be determined by arbitration as stated above). Where
+the Human Rights Laws of more than one jurisdiction are applicable or in
+conflict with respect to the use of the Software, the Human Rights Laws
+that are most protective of the individuals or groups harmed shall
+apply.
+. Indemnity. Licensee shall hold harmless and indemnify Licensor (and
+any other contributor) against all losses, damages, liabilities,
+deficiencies, claims, actions, judgments, settlements, interest, awards,
+penalties, fines, costs, or expenses of whatever kind, including
+Licensor’s reasonable attorneys’ fees, arising out of or relating to
+Licensee’s use of the Software in violation of Human Rights Laws or
+Human Rights Principles.
+* Failure to Comply. Any failure of Licensee to act according to the
+terms and conditions of this License is both a breach of the License and
+an infringement of the intellectual property rights of the Licensor
+(subject to exceptions under Laws, e.g., fair use). In the event of a
+breach or infringement, the terms and conditions of this License may be
+enforced by Licensor under the Laws of any jurisdiction to which
+Licensee is subject. Licensee also agrees that the Licensor may enforce
+the terms and conditions of this License against Licensee through
+specific performance (or similar remedy under Laws) to the extent
+permitted by Laws. For clarity, except in the event of a breach of this
+License, infringement, or as otherwise stated in this License, Licensor
+may not terminate this License with Licensee.
+* Enforceability and Interpretation. If any term or provision of this
+License is determined to be invalid, illegal, or unenforceable by a
+court of competent jurisdiction, then such invalidity, illegality, or
+unenforceability shall not affect any other term or provision of this
+License or invalidate or render unenforceable such term or provision in
+any other jurisdiction; provided, however, subject to a court
+modification pursuant to the immediately following sentence, if any term
+or provision of this License pertaining to Human Rights Laws or Human
+Rights Principles is deemed invalid, illegal, or unenforceable against
+Licensee by a court of competent jurisdiction, all rights in the
+Software granted to Licensee shall be deemed null and void as between
+Licensor and Licensee. Upon a determination that any term or provision
+is invalid, illegal, or unenforceable, to the extent permitted by Laws,
+the court may modify this License to affect the original purpose that
+the Software be used in compliance with Human Rights Principles and
+Human Rights Laws as closely as possible. The language in this License
+shall be interpreted as to its fair meaning and not strictly for or
+against any party.
+* Disclaimer. TO THE FULL EXTENT ALLOWED BY LAW, THIS SOFTWARE COMES
+"AS IS," WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED, AND LICENSOR AND
+ANY OTHER CONTRIBUTOR SHALL NOT BE LIABLE TO ANYONE FOR ANY DAMAGES OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+OR THIS LICENSE, UNDER ANY KIND OF LEGAL CLAIM.
+
+This Hippocratic License is an link:https://ethicalsource.dev[Ethical Source license] and is offered
+for use by licensors and licensees at their own risk, on an "AS IS" basis, and with no warranties
+express or implied, to the maximum extent permitted by Laws.

data/README.md

@@ -0,0 +1,289 @@
+# RSpec HTML Messages
+
+[![CI](https://github.com/firstdraft/rspec-html_messages/actions/workflows/ci.yml/badge.svg)](https://github.com/firstdraft/rspec-html_messages/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/rspec-html_messages.svg)](https://badge.fury.io/rb/rspec-html_messages)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)
+
+Transform RSpec's JSON output into formatted HTML with syntax highlighting, side-by-side diffs, and Bootstrap styling.
+
+## Overview
+
+`rspec-html_messages` takes the enriched JSON output from [`rspec-enriched_json`](https://github.com/firstdraft/rspec-enriched_json) and renders it as HTML. It provides:
+
+- **Beautiful formatting** - Clean, Bootstrap-styled output.
+- **Side-by-side diffs** - Visual comparison of expected vs actual values.
+- **Smart data rendering** - Pretty-printing for complex objects.
+- **Composable API** - Use individual components or the full renderer.
+- **Flexible options** - Control diff display and message formatting.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rspec-html_messages"
+```
+
+Or install directly:
+
+```bash
+$ gem install rspec-html_messages
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require "rspec/html_messages"
+
+# Get enriched JSON from RSpec
+# (typically from running with rspec-enriched_json formatter)
+example_json = {
+  "id" => "spec/example_spec.rb[1:1]",
+  "description" => "should equal 42",
+  "status" => "failed",
+  "file_path" => "spec/example_spec.rb",
+  "line_number" => 10,
+  "details" => {
+    "expected" => '"42"',
+    "actual" => '"41"',
+    "matcher_name" => "RSpec::Matchers::BuiltIn::Eq",
+    "diffable" => true
+  },
+  "exception" => {
+    "message" => "expected: \"42\"\n     got: \"41\"\n\n(compared using ==)"
+  }
+}
+
+# Render as HTML
+renderer = Rspec::HtmlMessages.new(example_json)
+html = renderer.render_html
+
+# Output includes styled HTML with diff
+puts html
+```
+
+### Using Individual Components
+
+The gem provides a composable API where you can use individual components to build your own custom layouts:
+
+```ruby
+renderer = Rspec::HtmlMessages.new(example_json)
+
+# Check what content is available
+if renderer.has_output?
+  output_html = renderer.output_html
+end
+
+if renderer.has_failure_message?
+  failure_html = renderer.failure_message_html
+end
+
+if renderer.has_exception_details?
+  exception_html = renderer.exception_details_html
+end
+
+if renderer.has_backtrace?
+  exception_html = renderer.backtrace_html
+end
+
+# Build your own custom layout
+html = <<~HTML
+  <div class="my-custom-test-result">
+    #{output_html if renderer.has_output?}
+    #{failure_html if renderer.has_failure_message?}
+    #{exception_html if renderer.has_exception_details?}
+  </div>
+HTML
+```
+
+### Options
+
+You can customize the rendering with various options:
+
+```ruby
+# Options can be passed to the render_html method
+html = renderer.render_html(
+  force_diffable: ["CustomMatcher"],  # Array of matchers to always show diffs for
+  force_not_diffable: ["RSpec::Matchers::BuiltIn::Include"],  # Array of matchers to never show diffs for
+  rspec_diff_in_message: true,   # Include RSpec's text diff in failure message (default: false)
+  backtrace_max_lines: 10,       # Maximum backtrace lines to show (default: 10)
+  backtrace_silence_gems: true   # Filter out gem frames from backtraces (default: true)
+)
+
+# Or to individual component methods
+output_html = renderer.output_html(force_diffable: ["CustomMatcher"])
+```
+
+#### Option Details
+
+- **`force_diffable`**: Array of matcher class names that should always show diffs, even if they report as non-diffable.
+  - Default: `["RSpec::Matchers::BuiltIn::ContainExactly"]` (used by `contain_exactly` and `match_array`).
+  - Override by passing your own array.
+
+- **`force_not_diffable`**: Array of matcher class names that should never show diffs, even if they report as diffable.
+  - Default: `["RSpec::Matchers::BuiltIn::Include", "RSpec::Matchers::BuiltIn::Compound::And", "RSpec::Matchers::BuiltIn::Compound::Or"]`.
+  - Override by passing your own array.
+
+- **`rspec_diff_in_message`**: By default, RSpec's text-based diff is stripped from failure messages since we show a visual diff. Set to `true` to keep it.
+
+- **`backtrace_max_lines`**: Maximum number of backtrace lines to display for errors.
+  - Default: `10`.
+  - Set to a higher number to see more of the stack trace.
+
+- **`backtrace_silence_gems`**: Whether to filter out gem frames from backtraces.
+  - Default: `true` (hides frames from installed gems).
+  - Set to `false` to see the complete backtrace including gem internals.
+
+### Complete Example
+
+Here's a complete example that processes RSpec output and generates an HTML report:
+
+```ruby
+require "json"
+require "rspec/html_messages"
+
+# Run RSpec with enriched JSON formatter
+json_output = `bundle exec rspec --require rspec/enriched_json \
+  -f RSpec::EnrichedJson::Formatters::EnrichedJsonFormatter`
+
+# Parse the JSON
+results = JSON.parse(json_output)
+
+# Generate HTML report
+html = <<~HTML
+<!DOCTYPE html>
+<html>
+<head>
+  <title>RSpec Results</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+</head>
+<body>
+  <div class="container my-4">
+    <h1>Test Results</h1>
+    <p>#{results["summary_line"]}</p>
+    
+HTML
+
+# Render each example
+results["examples"].each do |example|
+  renderer = Rspec::HtmlMessages.new(example)
+  html << <<~EXAMPLE
+    <div class="mb-4">
+      <h3>#{example["description"]}</h3>
+      #{renderer.render_html}
+    </div>
+  EXAMPLE
+end
+
+html << <<~HTML
+  </div>
+</body>
+</html>
+HTML
+
+File.write("rspec_results.html", html)
+```
+
+## Output Examples
+
+### Passing Test
+
+For a passing test, you'll see:
+- Green checkmark and background.
+- Test description and file location.
+- No failure message or diff.
+
+### Failing Test with Diff
+
+For a failing test with diffable values:
+- Red X and background.
+- Test description and file location.
+- Side-by-side comparison showing differences.
+- Failure message (with RSpec's diff stripped by default).
+
+### Error Display
+
+For tests that encounter errors (exceptions) before assertions:
+- Exception class name highlighted in red.
+- Stack trace with configurable depth.
+- Gem frames filtered by default (configurable).
+
+## Working with rspec-enriched_json
+
+This gem is designed to work with [`rspec-enriched_json`](https://github.com/firstdraft/rspec-enriched_json), which provides structured data about test failures including:
+
+- Expected and actual values as structured data (not just strings).
+- Matcher information.
+- Diffable status.
+- Original failure messages.
+
+To use both gems together:
+
+1. Add both gems to your Gemfile:
+   ```ruby
+   gem "rspec-enriched_json"
+   gem "rspec-html_messages"
+   ```
+
+2. Run RSpec with the enriched JSON formatter:
+   ```bash
+   bundle exec rspec --require rspec/enriched_json \
+     -f RSpec::EnrichedJson::Formatters::EnrichedJsonFormatter
+   ```
+
+3. Process the output with rspec-html_messages as shown in the examples above.
+
+## API Reference
+
+### Instance Methods
+
+#### `new(example)`
+Creates a new renderer instance with the example JSON data.
+
+#### `has_output?`
+Returns `true` if the example has output to display (failed tests or tests with actual values).
+
+#### `has_failure_message?`
+Returns `true` if the example has a failure message to display.
+
+#### `has_exception_details?`
+Returns `true` if the example has exception/error details to display.
+
+#### `has_backtrace?`
+Returns `true` if the example has a backtrace to display.
+
+#### `output_html(**options)`
+Renders just the output section (diff or actual value). Returns `nil` if no output to display.
+
+#### `failure_message_html(**options)`
+Renders just the failure message section. Returns `nil` if no failure message.
+
+#### `exception_details_html(**options)`
+Renders just the exception details section. Returns `nil` if no exception.
+
+#### `backtrace_html(**options)`
+Renders just the backtrace section. Returns `nil` if no backtrace.
+
+#### `render_html(**options)`
+Convenience method that renders all three sections in a standard layout.
+
+### Class Methods
+
+#### `Rspec::HtmlMessages.diff_css`
+Returns the CSS needed for diff display styling.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/firstdraft/rspec-html_messages.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rspec/html_messages/diff_formatter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "diffy"
+
+module Rspec
+  class HtmlMessages
+    module DiffFormatter
+      def effective_diffable?(force_diffable: [], force_not_diffable: [])
+        return true if force_diffable&.include?(matcher_name)
+        return false if force_not_diffable&.include?(matcher_name)
+
+        details["diffable"]
+      end
+
+      # Creates side-by-side HTML diff using Diffy
+      # Note: Diffy generates safe HTML with properly escaped content, so we render it unescaped in templates
+      def create_diff(actual_value, expected_value)
+        split_diff = Diffy::SplitDiff.new(actual_value, expected_value, format: :html)
+
+        {
+          left: split_diff.left,
+          right: split_diff.right
+        }
+      end
+    end
+  end
+end

data/lib/rspec/html_messages/template_renderer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "action_view"
+
+module Rspec
+  class HtmlMessages
+    module TemplateRenderer
+      include ActionView::Helpers::TagHelper
+      include ActionView::Helpers::TextHelper
+      include ActionView::Helpers::OutputSafetyHelper
+
+      def render_template(template_name, locals = {})
+        template_path = template_path_for(template_name)
+        erb = ERB.new(File.read(template_path))
+
+        # Create a binding with access to helper methods and locals
+        binding_with_locals = binding
+        locals.each do |key, value|
+          binding_with_locals.local_variable_set(key, value)
+        end
+
+        erb.result(binding_with_locals)
+      end
+
+      private
+
+      def template_path_for(template_name)
+        File.join(templates_dir, "#{template_name}.html.erb")
+      end
+
+      def templates_dir
+        @templates_dir ||= File.expand_path("templates", __dir__)
+      end
+
+      def html_escape(text)
+        ERB::Util.html_escape(text)
+      end
+    end
+  end
+end

data/lib/rspec/html_messages/templates/_actual.html.erb

@@ -0,0 +1,8 @@
+<div class="card">
+  <div class="card-header">
+    <h5 class="h6 mb-0">Actual</h5>
+  </div>
+  <div class="card-body">
+    <pre class="mb-0 fs-6"><code><%= html_escape(prettified_actual) %></code></pre>
+  </div>
+</div>

data/lib/rspec/html_messages/templates/_backtrace.html.erb

@@ -0,0 +1,13 @@
+<% if exception_backtrace.any? %>
+  <% backtrace_lines = formatted_backtrace(max_lines: @backtrace_max_lines, silence_gems: @backtrace_silence_gems) %>
+  <div>
+    <h5 class="h6 text-muted mb-2">Backtrace:</h5>
+    <pre class="bg-dark text-white p-3 rounded backtrace"><code><% backtrace_lines.each do |line| %><%= html_escape(line) %>
+<% end %></code></pre>
+    <% if exception_backtrace.size > backtrace_lines.size %>
+      <small class="text-muted mt-1 d-block">
+        (<%= exception_backtrace.size - backtrace_lines.size %> more frames omitted)
+      </small>
+    <% end %>
+  </div>
+<% end %>

data/lib/rspec/html_messages/templates/_diff.html.erb

@@ -0,0 +1,22 @@
+<div class="card-group">
+  <div class="card">
+    <div class="card-header">
+      <h5 class="h6 mb-0">Actual</h5>
+    </div>
+    <div class="card-body">
+      <div class="font-monospace">
+        <%= diff_html[:left] %>
+      </div>
+    </div>
+  </div>
+  <div class="card">
+    <div class="card-header">
+      <h5 class="h6 mb-0">Expected</h5>
+    </div>
+    <div class="card-body">
+      <div class="font-monospace">
+        <%= diff_html[:right] %>
+      </div>
+    </div>
+  </div>
+</div>

data/lib/rspec/html_messages/templates/_exception_details.html.erb

@@ -0,0 +1,12 @@
+<% if exception_message.present? %>
+  <div class="card border-danger">
+    <div class="card-header">
+      <h5 class="h6 mb-0 text-danger">Error in code</h5>
+    </div>
+    <div class="card-body">
+      <pre class="text-danger fs-6 error-message mb-0"><code class="fw-bold"><%= html_escape(exception_message) %>
+
+<% location = friendly_error_location %><% if location %><span class="text-body fw-normal"><%= html_escape(location) %></span><% end %></code></pre>
+    </div>
+  </div>
+<% end %>

data/lib/rspec/html_messages/templates/_failure_message.html.erb

@@ -0,0 +1,8 @@
+<div class="card border-warning">
+  <div class="card-header">
+    <h5 class="h6 mb-0" style="color: var(--bs-orange)">Test failure message</h5>
+  </div>
+  <div class="card-body">
+    <pre class="failure-message mb-0 fs-6"><code><%= html_escape(@failure_message_text) %></code></pre>
+  </div>
+</div>

data/lib/rspec/html_messages/templates/example.html.erb

@@ -0,0 +1,19 @@
+<div class="rspec-html-messages">
+  <% if output_content = output_html(**@options) %>
+    <div>
+      <%= output_content %>
+    </div>
+  <% end %>
+
+  <% if failure_content = failure_message_html(**@options) %>
+    <div class="mt-3">
+      <%= failure_content %>
+    </div>
+  <% end %>
+
+  <% if exception_content = exception_details_html(**@options) %>
+    <div class="mt-3">
+      <%= exception_content %>
+    </div>
+  <% end %>
+</div>

data/lib/rspec/html_messages/value_formatter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "oj"
+require "amazing_print"
+
+module Rspec
+  class HtmlMessages
+    module ValueFormatter
+      # Oj options for deserializing - use object mode to restore symbols
+      # but keep safety options to prevent code execution
+      OJ_LOAD_OPTIONS = {
+        mode: :object,        # Restore Ruby objects and symbols
+        auto_define: false,   # DON'T auto-create classes (safety)
+        symbol_keys: false,   # Preserve symbols as they were serialized
+        circular: true,       # Handle circular references
+        create_additions: false, # Don't allow custom deserialization (safety)
+        create_id: nil # Disable create_id (safety)
+      }.freeze
+
+      AWESOME_PRINT_OPTIONS = {
+        plain: true,        # No color codes
+        index: false,       # No array indices
+        indent: -2,         # 2-space indentation
+        sort_keys: true,    # Consistent hash ordering
+        object_id: false,   # No object IDs
+        raw: true # Show instance variables
+      }
+
+      def prettify_for_diff(value)
+        case value
+        when String then value
+        when nil then "nil"
+        else value.awesome_inspect(AWESOME_PRINT_OPTIONS)
+        end
+      end
+
+      def deserialize_value(serialized_value)
+        return nil unless serialized_value
+
+        Oj.load(serialized_value, OJ_LOAD_OPTIONS)
+      rescue Oj::ParseError, EncodingError, TypeError
+        serialized_value
+      end
+    end
+  end
+end

data/lib/rspec/html_messages/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rspec
+  class HtmlMessages
+    VERSION = "0.1.0"
+  end
+end

data/lib/rspec/html_messages.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "active_support/backtrace_cleaner"
+
+Zeitwerk::Loader.new.then do |loader|
+  loader.tag = "rspec-html_messages"
+  loader.push_dir "#{__dir__}/.."
+  loader.setup
+end
+
+module Rspec
+  # Main renderer class for converting enriched JSON examples to HTML
+  class HtmlMessages
+    include HtmlMessages::ValueFormatter
+    include HtmlMessages::DiffFormatter
+    include HtmlMessages::TemplateRenderer
+
+    # Matchers that should always show diffs regardless of their diffable flag
+    FORCE_DIFFABLE_MATCHERS = ["RSpec::Matchers::BuiltIn::ContainExactly"].freeze
+    
+    # Matchers that should never show diffs regardless of their diffable flag
+    FORCE_NOT_DIFFABLE_MATCHERS = [
+      "RSpec::Matchers::BuiltIn::Include",
+      "RSpec::Matchers::BuiltIn::Compound::And",
+      "RSpec::Matchers::BuiltIn::Compound::Or"
+    ].freeze
+
+    attr_reader :example
+
+    def initialize(example)
+      validate_example!(example)
+      @example = example
+    end
+    
+    def options
+      @options ||= default_options
+    end
+
+    # Individual rendering methods - return nil when no content to display
+    def output_html(**options)
+      return nil unless has_output?
+
+      @options = default_options.merge(options)
+      @force_diffable = @options[:force_diffable]
+      @force_not_diffable = @options[:force_not_diffable]
+
+      if should_show_diff?
+        render_template("_diff")
+      else
+        render_template("_actual")
+      end
+    end
+
+    def failure_message_html(**options)
+      @options = default_options.merge(options)
+      
+      # Don't show failure message for errors - that goes in exception details
+      return nil unless has_failure_message?
+
+      @failure_message_text = failure_message
+
+      render_template("_failure_message")
+    end
+
+    def exception_details_html(**options)
+      return nil unless has_exception_details?
+
+      @options = default_options.merge(options)
+
+      render_template("_exception_details")
+    end
+
+    def backtrace_html(**options)
+      return nil unless has_backtrace?
+
+      @options = default_options.merge(options)
+      @backtrace_max_lines = @options[:backtrace_max_lines]
+      @backtrace_silence_gems = @options[:backtrace_silence_gems]
+
+      render_template("_backtrace")
+    end
+
+    # Public boolean methods so users can make their own decisions
+    def has_output?
+      # Don't show output for errors before assertions
+      return false if error_before_assertion?
+
+      status == "failed" || has_actual?
+    end
+
+    def has_failure_message?
+      status == "failed" && !error_before_assertion? && failure_message.present?
+    end
+
+    def has_exception_details?
+      error_before_assertion?
+    end
+
+    def has_backtrace?
+      exception_backtrace.any?
+    end
+
+    # Example of how to use all three together
+    def render_html(**options)
+      @options = default_options.merge(options)
+      render_template("example")
+    end
+
+    def self.diff_css
+      # Minimal CSS for displaying diffs generated by Diffy
+      <<~CSS
+        .diff { overflow: auto; }
+        .diff ul {
+          overflow: auto;
+          list-style: none;
+          margin: 0;
+          padding: 0;
+          display: table;
+          width: 100%;
+        }
+        .diff del, .diff ins {
+          display: block;
+          text-decoration: none;
+        }
+        .diff li {
+          padding: 0;
+          display: table-row;
+          margin: 0;
+          height: 1em;
+        }
+        .diff li.ins { background: #dfd; color: #080; }
+        .diff li.del { background: #fee; color: #b00; }
+        .diff li:hover { background: #ffc; }
+        .diff del, .diff ins, .diff span { white-space: pre-wrap; }
+        .diff del strong { font-weight: normal; background: #fcc; }
+        .diff ins strong { font-weight: normal; background: #9f9; }
+        .diff li.diff-comment { display: none; }
+        .diff li.diff-block-info { background: none repeat scroll 0 0 gray; }
+      CSS
+    end
+
+    private
+
+    def default_options
+      {
+        force_diffable: FORCE_DIFFABLE_MATCHERS,
+        force_not_diffable: FORCE_NOT_DIFFABLE_MATCHERS,
+        rspec_diff_in_message: false,
+        backtrace_max_lines: 10,
+        backtrace_silence_gems: true
+      }
+    end
+
+    def should_show_diff?
+      show_diff?(force_diffable: @force_diffable, force_not_diffable: @force_not_diffable)
+    end
+
+    # Helper methods for templates
+    def status
+      example["status"]
+    end
+
+    def details
+      @details ||= example["details"] || {}
+    end
+
+    def matcher_name
+      details["matcher_name"] || "Unknown"
+    end
+
+    def failure_message
+      @failure_message ||= calculate_failure_message
+    end
+
+    def calculate_failure_message
+      return nil unless status == "failed"
+
+      message = example.dig("exception", "message")
+      return nil unless message
+
+      # Strip leading newline that RSpec's built-in matchers add
+      message = message.sub(/\A\n/, "")
+
+      # Strip RSpec's diff section if requested
+      if !options[:rspec_diff_in_message]
+        # RSpec appends diffs with "\nDiff:" or "\nDiff for (...):"
+        # The diff always contains @@ markers (unified diff format) or the empty diff message
+        # This regex requires either @@ or "The diff is empty" to appear after Diff:
+        # to avoid false positives where "Diff:" might appear in user data
+        message = message.sub(
+          /\n\s*Diff(?:\s+for\s+\([^)]+\))?:.*?(?:@@|The diff is empty).*\z/m,
+          ""
+        )
+      end
+
+      message
+    end
+
+    def exception_class
+      example.dig("exception", "class")
+    end
+
+    def exception_message
+      example.dig("exception", "message")
+    end
+
+    def exception_backtrace
+      example.dig("exception", "backtrace") || []
+    end
+
+    def has_exception?
+      example.key?("exception")
+    end
+
+    def error_before_assertion?
+      # Check if this is an error (not a matcher failure)
+      has_exception? && !has_actual? && !has_expected?
+    end
+
+    def has_expected?
+      details.key?("expected")
+    end
+
+    def backtrace_cleaner(silence_gems: true)
+      ActiveSupport::BacktraceCleaner.new.tap do |bc|
+        # Clean up paths by removing project root
+        bc.add_filter { |line| line.gsub("#{project_root}/", "") }
+
+        # Optionally silence gem frames
+        if silence_gems
+          bc.add_silencer { |line| line.include?("/gems/") && !line.include?(project_root) }
+          bc.add_silencer { |line| line.include?("/bundle/") }
+          bc.add_silencer { |line| line.match?(%r{/ruby/\d+\.\d+\.\d+/}) }
+        end
+
+        # Always silence RSpec internals
+        bc.add_silencer { |line| line.match?(%r{/lib/rspec/(core|expectations|mocks)/}) }
+      end
+    end
+
+    def project_root
+      @project_root ||= File.expand_path("../..", File.dirname(example["file_path"]))
+    end
+
+    def has_actual?
+      details.key?("actual")
+    end
+
+    def actual_value
+      @actual_value ||= deserialize_value(details["actual"]) if has_actual?
+    end
+
+    def expected_value
+      @expected_value ||= deserialize_value(details["expected"]) if has_expected?
+    end
+
+    def prettified_actual
+      @prettified_actual ||= prettify_for_diff(actual_value)
+    end
+
+    def prettified_expected
+      @prettified_expected ||= prettify_for_diff(expected_value)
+    end
+
+    def negated?
+      details["negated"]
+    end
+
+    def show_diff?(force_diffable: [], force_not_diffable: [])
+      return false if status == "passed"
+      return false unless expected_value && actual_value
+      return false if negated?
+
+      # Check if values are identical (likely a negated matcher)
+      return false if prettified_actual == prettified_expected
+
+      effective_diffable?(force_diffable: force_diffable, force_not_diffable: force_not_diffable)
+    end
+
+    def diff_html
+      @diff_html ||= create_diff(prettified_actual, prettified_expected)
+    end
+
+    def formatted_backtrace(max_lines: 10, silence_gems: true)
+      return [] if exception_backtrace.empty?
+
+      cleaned = backtrace_cleaner(silence_gems: silence_gems).clean(exception_backtrace)
+
+      # If all lines were filtered out, show original with cleaned paths
+      if cleaned.empty?
+        cleaned = ActiveSupport::BacktraceCleaner.new.tap do |bc|
+          bc.add_filter { |line| line.gsub("#{project_root}/", "") }
+        end.clean(exception_backtrace)
+      end
+
+      cleaned.first(max_lines)
+    end
+
+    def friendly_error_location
+      return nil if exception_backtrace.empty?
+
+      first_line = exception_backtrace.first
+      # Remove absolute path prefix to get relative path
+      first_line = first_line.gsub(/^#{Regexp.escape(project_root)}\//, "")
+
+      # Parse the backtrace line format: path:line:in 'method'
+      if match = first_line.match(/^(.+):(\d+):in ['`](.+)['`]$/)
+        path, line_number, method = match.captures
+        "#{exception_class} on line #{line_number} of #{path} in '#{method}'"
+      else
+        # Fallback to original format if parsing fails
+        "#{exception_class}: #{first_line}"
+      end
+    end
+
+    private
+
+    def validate_example!(example)
+      raise ArgumentError, "Example cannot be nil" if example.nil?
+      raise ArgumentError, "Example must be a Hash" unless example.is_a?(Hash)
+      
+      # Validate required fields
+      required_fields = %w[id description status file_path line_number]
+      missing_fields = required_fields - example.keys
+      
+      unless missing_fields.empty?
+        raise ArgumentError, "Example is missing required fields: #{missing_fields.join(', ')}"
+      end
+      
+      # Validate status value
+      valid_statuses = %w[passed failed pending]
+      unless valid_statuses.include?(example["status"])
+        raise ArgumentError, "Invalid status: #{example['status']}. Must be one of: #{valid_statuses.join(', ')}"
+      end
+    end
+  end
+end

data/rspec-html_messages.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/rspec/html_messages/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "rspec-html_messages"
+  spec.version = Rspec::HtmlMessages::VERSION
+  spec.authors = ["Raghu Betina"]
+  spec.email = ["raghu@firstdraft.com"]
+  spec.homepage = "https://github.com/firstdraft/rspec-html_messages"
+  spec.summary = "HTML formatting for RSpec enriched JSON output"
+  spec.license = "MIT"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/firstdraft/rspec-html_messages/issues",
+    "changelog_uri" => "https://github.com/firstdraft/rspec-html_messages/blob/main/CHANGELOG.md",
+    "label" => "Rspec Html Messages",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/firstdraft/rspec-html_messages"
+  }
+
+  spec.required_ruby_version = "~> 3.0"
+  spec.add_dependency "actionview", ">= 6.0", "< 8"
+  spec.add_dependency "activesupport", ">= 6.0", "< 8"
+  spec.add_dependency "amazing_print", "~> 1.6"
+  spec.add_dependency "diffy", "~> 3.4"
+  spec.add_dependency "oj", "~> 3.16"
+  spec.add_dependency "zeitwerk", "~> 2.7"
+
+  spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
+  spec.files = Dir["*.gemspec", "lib/**/*"]
+end

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: rspec-html_messages
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Raghu Betina
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: amazing_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: diffy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.16'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+email:
+- raghu@firstdraft.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.md
+- README.md
+files:
+- LICENSE.md
+- README.md
+- lib/rspec/html_messages.rb
+- lib/rspec/html_messages/diff_formatter.rb
+- lib/rspec/html_messages/template_renderer.rb
+- lib/rspec/html_messages/templates/_actual.html.erb
+- lib/rspec/html_messages/templates/_backtrace.html.erb
+- lib/rspec/html_messages/templates/_diff.html.erb
+- lib/rspec/html_messages/templates/_exception_details.html.erb
+- lib/rspec/html_messages/templates/_failure_message.html.erb
+- lib/rspec/html_messages/templates/example.html.erb
+- lib/rspec/html_messages/value_formatter.rb
+- lib/rspec/html_messages/version.rb
+- rspec-html_messages.gemspec
+homepage: https://github.com/firstdraft/rspec-html_messages
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/firstdraft/rspec-html_messages/issues
+  changelog_uri: https://github.com/firstdraft/rspec-html_messages/blob/main/CHANGELOG.md
+  label: Rspec Html Messages
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/firstdraft/rspec-html_messages
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.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: HTML formatting for RSpec enriched JSON output
+test_files: []