snapshot_ui-rails 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0cf0d4ed677d5728c73352d9f2413512ca1ff519e10f7c8dd8915633c343ded6
+  data.tar.gz: dbbf6856befbbd129fb2ca9b684a755770c1d01ec4f5c81ea08b39f40a94f212
+SHA512:
+  metadata.gz: a41d4cb2b9e40cfe0f7300aaff7e74c44fa0affa0509eebbcce0bfad09cfb73dabcfdf46087192cd3383962860d4c20b645b89bb7bdb5e4f3fb1854243c34141
+  data.tar.gz: 80119bbeb6bc9bfe99e98d47a7688e86ccb6595ace6e2d151dfd0eab4f8e5cab35f38de399d73020053aa2c0261977a7c866d0d627e50658fdfb22c7369a49ab

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## [Unreleased]
+
+## [0.5.0] - 2026-10-26
+
+- Initial release. Rails integration for Snapshot UI:
+  - Snapshot UI is configured automatically from the Rails application (root, tmp directory, mount path and host);
+    with the defaults no initializer is required.
+  - The URL shown after a test run is derived from `config.snapshot_ui.mount_path` and `config.snapshot_ui.host`
+    (the host defaults from the app's `default_url_options`, then `PORT`, then `http://localhost:3000`).
+  - `mount_snapshot_ui` mounts the web interface in `config/routes.rb`; the default path is `/rails/ui_snapshots`.
+  - `take_snapshot` is available in `ActionDispatch::IntegrationTest` without an explicit `include`.
+  - `take_snapshot` also captures emails (`ActionMailer::MessageDelivery` or `Mail::Message`) in mailer and
+    integration tests, so mailers can be reviewed in the browser instead of maintaining Action Mailer previews.
+    Both the HTML and plain-text parts are captured, with attachments and an `.eml` download.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Tomaz Zlender
+
+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,178 @@
+# Snapshot UI for Rails
+
+Rails integration for [Snapshot UI](https://github.com/tomazzlender/snapshot_ui). Take snapshots of responses in your
+integration tests and view them in a browser — with no configuration.
+
+This gem wires Snapshot UI into a Rails application: it fills in Snapshot UI's configuration from what Rails already
+knows, adds a router helper to mount the web interface, and makes `take_snapshot` available in your integration tests.
+
+## Installation
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "snapshot_ui-rails"
+end
+```
+
+```sh
+bundle install
+```
+
+The `snapshot_ui` gem is pulled in automatically.
+
+## Usage
+
+With the defaults, the whole setup is one line in your routes — **no initializer, no configuration**.
+
+### 1. Mount the web interface
+
+Snapshot UI is a development tool: it displays artifacts captured during test runs and has nothing to show in
+production. Mount it only where you need it, the way you would Sidekiq's or Flipper's dashboards:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount_snapshot_ui if Rails.env.development?
+  # ...
+end
+```
+
+This mounts the UI at `/rails/ui_snapshots` — alongside Rails' own development tools such as `/rails/info` and
+`/rails/mailers`. Every snapshot you take shows up there, grouped by the test that produced it:
+
+![The list of snapshots](docs/images/snapshots_index.png)
+
+### 2. Take snapshots in your integration tests
+
+`take_snapshot` is available in every `ActionDispatch::IntegrationTest` — no `include` required:
+
+```ruby
+require "test_helper"
+
+class PlotsTest < ActionDispatch::IntegrationTest
+  test "shows a plot" do
+    get "/plots/A3"
+
+    take_snapshot(response)
+
+    assert_response :success
+  end
+end
+```
+
+Run the test with snapshots enabled and the response is captured and rendered exactly as it came back — here, a plot
+page from a community-garden site:
+
+![A page response rendered as a snapshot](docs/images/response_snapshot.png)
+
+`take_snapshot` accepts an object that responds to `#body` (such as the integration test's `response`) or a plain
+`String`, and two options:
+
+```ruby
+take_snapshot(response, title: "Plot detail", slug: "plot-A3")
+```
+
+* `title` — the name shown in the list (defaults to a name derived from the test).
+* `slug` — a custom, stable URL for the snapshot (`/rails/ui_snapshots/plot-A3`); must be unique.
+
+### 3. Snapshotting Action Mailer emails
+
+`take_snapshot` also accepts an email, so you can review mailers in the browser instead of maintaining Action Mailer
+previews:
+
+```ruby
+class NotifierMailerTest < ActionMailer::TestCase
+  test "welcome email" do
+    email = NotifierMailer.welcome(user)
+    take_snapshot(email)
+
+    assert_emails 0 # your usual assertions are unaffected
+  end
+end
+```
+
+One call captures the whole email, and the snapshot renders with the same chrome as any Rails view — the subject,
+mailer/action and address headers, attachments, and the rendered email itself:
+
+![An Action Mailer email rendered as a snapshot](docs/images/mail_snapshot_html.png)
+
+Because the whole message is captured, **both the HTML and the plain-text versions are available** from the one call —
+a switcher appears whenever the email has both, so there is nothing to keep in sync:
+
+![The same email viewed as plain text](docs/images/mail_snapshot_text.png)
+
+The snapshot also offers each attachment as a download and a **Download .eml** of the raw message, and the full header
+set is one click away under “All headers”.
+
+`take_snapshot` accepts an `ActionMailer::MessageDelivery` (what a mailer action returns) or a `Mail::Message`, and
+the same `title:` and `slug:` options as responses. It is available in `ActionMailer::TestCase` and in integration
+tests with no explicit `include`.
+
+### 4. Run the tests and view the snapshots
+
+Snapshots are only taken when you ask for them, via the `--take-snapshots` flag or `TAKE_SNAPSHOTS=1`:
+
+```sh
+bin/rails test test/integration --take-snapshots
+```
+
+At the end of the run the URL to review the snapshots is printed. Start your app (`bin/rails server`) and open
+<http://localhost:3000/rails/ui_snapshots>. The page refreshes automatically as you take new snapshots.
+
+You'll usually want the snapshots directory ignored by git:
+
+```
+# .gitignore
+/tmp/snapshot_ui/
+```
+
+## Configuration
+
+**None is required.** Everything is inferred from the Rails application:
+
+| Setting                  | Default                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `project_root_directory` | `Rails.root`                                                                     |
+| `storage_directory`      | `Rails.root/tmp/snapshot_ui`                                                     |
+| `mount_path`             | `/rails/ui_snapshots`                                                            |
+| `host`                   | the app's `default_url_options`, else `PORT`, else `http://localhost:3000`       |
+
+The mount path and host are only used to build the "ready for review" URL printed after a test run and the link on the
+UI's empty state; the interface itself works wherever it is mounted.
+
+To override, add an initializer — it runs after this gem's defaults, so your values win:
+
+```ruby
+# config/initializers/snapshot_ui.rb
+Rails.application.configure do
+  # Mount somewhere other than /rails/ui_snapshots (also change the argument to mount_snapshot_ui):
+  config.snapshot_ui.mount_path = "/admin/snapshots"
+
+  # Only needed if your development server isn't on http://localhost:3000:
+  config.snapshot_ui.host = "http://localhost:4000"
+end
+```
+
+```ruby
+# config/routes.rb — pass the same path when it isn't the default
+mount_snapshot_ui at: "/admin/snapshots" if Rails.env.development?
+```
+
+If you already set `config.action_controller.default_url_options`, the host is taken from there and you don't need to
+set `config.snapshot_ui.host` at all.
+
+## How it works
+
+The gem is a thin adapter over `snapshot_ui`. A Railtie:
+
+* fills in `SnapshotUI.configuration` from `Rails.root`, the mount path and the resolved host;
+* requires the `mount_snapshot_ui` router helper, which mounts the same `SnapshotUI::Web` Rack app the core gem ships;
+* includes `SnapshotUI::Test::MinitestHelpers` into `ActionDispatch::IntegrationTest` via `ActiveSupport.on_load`.
+
+For anything not specific to Rails, see the
+[Snapshot UI README](https://github.com/tomazzlender/snapshot_ui/tree/main/gems/snapshot_ui).
+
+## License
+
+MIT.

data/lib/snapshot_ui/rails/mail.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "mail"
+
+module SnapshotUI
+  module Rails
+    # Reads a stored "mail" snapshot back into a usable form: the reconstructed
+    # Mail::Message plus the parts and metadata the mail view needs.
+    class Mail
+      HTML = "text/html"
+      TEXT = "text/plain"
+
+      def initialize(snapshot)
+        @type_data = snapshot.type_data
+      end
+
+      def message
+        @message ||= begin
+          message = ::Mail::Message.new(@type_data[:message].to_s)
+          message.bcc = @type_data[:bcc] if @type_data[:bcc]
+          message
+        end
+      end
+
+      def mailer
+        @type_data[:mailer]
+      end
+
+      def action
+        @type_data[:action]
+      end
+
+      def html?
+        !part_for(HTML).nil?
+      end
+
+      def text?
+        !part_for(TEXT).nil?
+      end
+
+      # Both alternatives were captured — offer a switcher.
+      def multipart_alternatives?
+        html? && text?
+      end
+
+      def default_mime_type
+        if html?
+          HTML
+        else
+          (text? ? TEXT : message.mime_type)
+        end
+      end
+
+      # The decoded body for a MIME type, falling back to the message body for a
+      # single-part email whose type matches.
+      def part_body(mime_type)
+        if (part = part_for(mime_type))
+          part.respond_to?(:decoded) ? part.decoded : part.to_s
+        end
+      end
+
+      def attachments
+        message.attachments || []
+      end
+
+      def eml
+        message.to_s
+      end
+
+      private
+
+      def part_for(mime_type)
+        message.find_first_mime_type(mime_type) || ((message.mime_type == mime_type) ? message : nil)
+      end
+    end
+  end
+end

data/lib/snapshot_ui/rails/mail_snapshot.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "snapshot_ui/snapshot"
+
+module SnapshotUI
+  module Rails
+    # Captures an ActionMailer / Mail message as a snapshot.
+    #
+    # The whole email is serialized to its RFC-822 form (which keeps every MIME
+    # part — both the HTML and the plain-text alternatives, and any attachments),
+    # so a single stored string round-trips to both views. BCC is stored
+    # separately because it is not part of the serialized message.
+    module MailSnapshot
+      TYPE = "mail"
+
+      module_function
+
+      def persist(mail, context:)
+        message = to_mail_message(mail)
+
+        SnapshotUI::Snapshot.persist(
+          snapshotee: nil,
+          context: context,
+          type: TYPE,
+          type_data: {
+            message: message.to_s,
+            bcc: Array(message.bcc),
+            mailer: mailer_name(mail),
+            action: action_name(mail)
+          }
+        )
+      end
+
+      # ActionMailer hands tests a MessageDelivery; #message is the underlying
+      # Mail::Message. A bare Mail::Message is accepted too.
+      def to_mail_message(mail)
+        mail.respond_to?(:message) ? mail.message : mail
+      end
+
+      # The mailer class name. ActionMailer::MessageDelivery stores it as
+      # @mailer_class; #mailer_class is unreliable across Rails versions (on some
+      # it returns MessageDelivery itself), so prefer the ivar.
+      def mailer_name(mail)
+        mailer_class =
+          if mail.instance_variable_defined?(:@mailer_class)
+            mail.instance_variable_get(:@mailer_class)
+          elsif mail.respond_to?(:mailer_class)
+            mail.mailer_class
+          end
+
+        (mailer_class || mail.class).name
+      end
+
+      # ActionMailer::MessageDelivery stores the action as @action (a Symbol);
+      # some versions/objects expose #action_name. Fall back gracefully.
+      def action_name(mail)
+        if mail.respond_to?(:action_name)
+          mail.action_name
+        elsif mail.instance_variable_defined?(:@action)
+          mail.instance_variable_get(:@action)&.to_s
+        end
+      end
+    end
+  end
+end

data/lib/snapshot_ui/rails/railtie.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "snapshot_ui"
+
+module SnapshotUI
+  module Rails
+    # Wires Snapshot UI into a Rails application:
+    #
+    # * fills in the configuration Snapshot UI needs from what Rails already
+    #   knows (its root, its tmp directory and the mount path), so with the
+    #   defaults no initializer is required;
+    # * adds +mount_snapshot_ui+ to the router;
+    # * makes +take_snapshot+ available in integration tests.
+    #
+    # To override anything, set it under +config.snapshot_ui+ in
+    # +config/initializers/snapshot_ui.rb+ (or an environment file):
+    #
+    #   Rails.application.configure do
+    #     config.snapshot_ui.mount_path = "/admin/snapshots"
+    #     config.snapshot_ui.host       = "http://localhost:4000"
+    #   end
+    class Railtie < ::Rails::Railtie
+      config.snapshot_ui = ActiveSupport::OrderedOptions.new
+      # The path the UI is mounted at.
+      config.snapshot_ui.mount_path = nil
+      # The scheme://host[:port] the UI is reachable at, for the "ready for
+      # review" message. Defaults to the application's declared host, else
+      # http://localhost:3000. See SnapshotUI::Rails.default_host.
+      config.snapshot_ui.host = nil
+      # A full URL that overrides both of the above for the printed message.
+      # Rarely needed; prefer mount_path + host.
+      config.snapshot_ui.web_url = nil
+
+      # The mount path is known immediately, so the router helper and the
+      # storage paths can use it.
+      initializer "snapshot_ui.configure" do |app|
+        SnapshotUI::Rails.mount_path = app.config.snapshot_ui.mount_path if app.config.snapshot_ui.mount_path
+
+        SnapshotUI.configure do |config|
+          config.project_root_directory ||= ::Rails.root.to_s
+          config.storage_directory ||= ::Rails.root.join("tmp", "snapshot_ui").to_s
+        end
+      end
+
+      # The web URL is resolved after initialization so that a host declared in
+      # a user initializer (config.action_controller.default_url_options, or
+      # config.snapshot_ui.host) has already been set.
+      config.after_initialize do |app|
+        options = app.config.snapshot_ui
+
+        SnapshotUI.configuration.web_url =
+          options.web_url ||
+          SnapshotUI::Rails.web_url(host: options.host || SnapshotUI::Rails.default_host(app))
+      end
+
+      # The +mount_snapshot_ui+ router helper.
+      initializer "snapshot_ui.routes" do
+        require_relative "routes"
+      end
+
+      # Teach the web interface to render "mail" snapshots.
+      initializer "snapshot_ui.mail_renderer" do
+        require "snapshot_ui/web"
+        require_relative "mail_snapshot"
+        require_relative "web/mail_renderer"
+        SnapshotUI::Web.register_renderer(
+          SnapshotUI::Rails::MailSnapshot::TYPE,
+          SnapshotUI::Rails::Web::MailRenderer
+        )
+      end
+
+      # +take_snapshot+ in tests, without an explicit include. One helper covers
+      # both integration tests (responses) and mailer tests (emails).
+      initializer "snapshot_ui.test_helpers" do
+        ActiveSupport.on_load(:action_dispatch_integration_test) do
+          require_relative "test/helpers"
+          include SnapshotUI::Rails::Test::Helpers
+        end
+
+        ActiveSupport.on_load(:action_mailer_test_case) do
+          require_relative "test/helpers"
+          include SnapshotUI::Rails::Test::Helpers
+        end
+      end
+    end
+  end
+end

data/lib/snapshot_ui/rails/routes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "snapshot_ui/web"
+
+module ActionDispatch
+  module Routing
+    class Mapper
+      # Mounts the Snapshot UI web interface.
+      #
+      #   # config/routes.rb
+      #   mount_snapshot_ui
+      #   mount_snapshot_ui at: "/admin/snapshots"
+      #
+      # With no argument it mounts at +config.snapshot_ui.mount_path+
+      # (default +/rails/ui_snapshots+).
+      def mount_snapshot_ui(at: SnapshotUI::Rails.mount_path)
+        mount SnapshotUI::Web, at: at, as: "snapshot_ui"
+      end
+    end
+  end
+end

data/lib/snapshot_ui/rails/test/helpers.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "snapshot_ui"
+require_relative "../mail_snapshot"
+
+module SnapshotUI
+  module Rails
+    module Test
+      # A single +take_snapshot+ for Rails tests that dispatches by what it is
+      # given: an email (ActionMailer::MessageDelivery or Mail::Message) is
+      # captured as a mail snapshot; anything else (a response, or a String of
+      # HTML) is captured as a response snapshot.
+      #
+      # Included into both ActionDispatch::IntegrationTest and
+      # ActionMailer::TestCase by the railtie, so one method covers both.
+      module Helpers
+        def take_snapshot(snapshotee, title: nil, slug: nil)
+          return unless SnapshotUI.snapshot_taking_enabled?
+
+          type, type_data = classify(snapshotee)
+          SnapshotUI.exit_if_not_configured!
+          increment_take_snapshot_counter_scoped_by_test
+
+          context = {
+            test_framework: "minitest",
+            method_name: name,
+            source_location: build_source_location(caller_locations(1..1).first),
+            test_case_name: self.class.to_s,
+            take_snapshot_index: _take_snapshot_counter - 1,
+            metadata: {title: title, slug: slug}
+          }
+
+          if type == SnapshotUI::Rails::MailSnapshot::TYPE
+            SnapshotUI::Rails::MailSnapshot.persist(snapshotee, context: context)
+          else
+            SnapshotUI::Snapshot.persist(snapshotee: snapshotee, context: context, type: type, type_data: type_data)
+          end
+        end
+
+        private
+
+        # Returns [type, type_data]. type_data is nil for responses (the core
+        # extracts it from the snapshotee).
+        def classify(snapshotee)
+          if mail_like?(snapshotee)
+            [SnapshotUI::Rails::MailSnapshot::TYPE, nil]
+          elsif snapshotee.respond_to?(:body) || snapshotee.is_a?(String)
+            [SnapshotUI::Snapshot::DEFAULT_TYPE, nil]
+          else
+            raise ArgumentError,
+              "#take_snapshot accepts a response (something responding to #body), a String of HTML, " \
+              "or an email (ActionMailer::MessageDelivery / Mail::Message). You provided `#{snapshotee.class}`."
+          end
+        end
+
+        def mail_like?(object)
+          (defined?(ActionMailer::MessageDelivery) && object.is_a?(ActionMailer::MessageDelivery)) ||
+            (defined?(::Mail::Message) && object.is_a?(::Mail::Message))
+        end
+
+        attr_reader :_take_snapshot_counter
+
+        def increment_take_snapshot_counter_scoped_by_test
+          @_take_snapshot_counter ||= 0
+          @_take_snapshot_counter += 1
+        end
+
+        def build_source_location(caller_location)
+          [caller_location.path, caller_location.lineno]
+        end
+      end
+    end
+  end
+end

data/lib/snapshot_ui/rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "snapshot_ui/version"
+
+module SnapshotUI
+  module Rails
+    VERSION = SnapshotUI::VERSION
+  end
+end

data/lib/snapshot_ui/rails/web/mail_renderer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "base64"
+require "rack/utils"
+require_relative "../mail"
+
+module SnapshotUI
+  module Rails
+    module Web
+      # Renders "mail" snapshots for SnapshotUI::Web. Registered by the railtie.
+      #
+      # #show renders the email chrome (headers, an HTML/plain-text switcher when
+      # both parts exist, attachments, an .eml download) with the chosen part
+      # shown in an iframe. #raw serves a single part with its content type, or
+      # the .eml file.
+      module MailRenderer
+        VIEW = "snapshots/mail/show"
+
+        module_function
+
+        def show(snapshot, view)
+          mail = SnapshotUI::Rails::Mail.new(snapshot)
+          part = requested_part(view) || mail.default_mime_type
+
+          presenter = Presenter.new(snapshot: snapshot, mail: mail, part: part, view: view)
+          view.render_body_in_layout(presenter.render_body, status: 200)
+        end
+
+        def raw(snapshot, view)
+          mail = SnapshotUI::Rails::Mail.new(snapshot)
+
+          if view.request.params["eml"]
+            filename = [mail.mailer, mail.action].compact.join("#")
+            filename = "email" if filename.empty?
+            return [200,
+              {"content-type" => "message/rfc822",
+               "content-disposition" => %(attachment; filename="#{filename}.eml")},
+              [mail.eml]]
+          end
+
+          mime_type = view.request.params["part"] || mail.default_mime_type
+          body = mail.part_body(mime_type)
+
+          if body
+            [200, {"content-type" => "#{mime_type}; charset=utf-8"}, [body]]
+          else
+            [404, {"content-type" => "text/plain; charset=utf-8"},
+              ["Email part `#{mime_type}` not found in this snapshot."]]
+          end
+        end
+
+        def requested_part(view)
+          mime = view.request.params["part"]
+          mime if [SnapshotUI::Rails::Mail::HTML, SnapshotUI::Rails::Mail::TEXT].include?(mime)
+        end
+
+        # Passed as the render context so the template can call these helpers and
+        # still reach the core view's URL/asset helpers via method_missing.
+        class Presenter
+          H = Rack::Utils
+
+          def initialize(snapshot:, mail:, part:, view:)
+            @snapshot = snapshot
+            @mail = mail
+            @part = part
+            @view = view
+          end
+
+          attr_reader :snapshot, :mail, :part, :view
+
+          # Renders this gem's mail template to a <body> string. The template
+          # lives under this file's directory (web/views/...).
+          def render_body
+            template = File.expand_path("views/#{MailRenderer::VIEW}.html.erb", __dir__)
+            ERB.new(File.read(template), trim_mode: "-").result(binding)
+          end
+
+          def h(text)
+            H.escape_html(text.to_s)
+          end
+
+          def raw_part_url(mime_type)
+            base = view.raw_snapshot_path(snapshot.slug)
+            "#{base}?#{H.build_query("part" => mime_type)}"
+          end
+
+          def eml_url
+            "#{view.raw_snapshot_path(snapshot.slug)}?#{H.build_query("eml" => "1")}"
+          end
+
+          def show_url(mime_type)
+            "#{view.snapshot_path(snapshot.slug)}?#{H.build_query("part" => mime_type)}"
+          end
+
+          def attachment_data_uri(attachment)
+            "data:application/octet-stream;base64,#{Base64.strict_encode64(attachment.decoded)}"
+          end
+
+          def attachment_filename(attachment)
+            attachment.respond_to?(:original_filename) ? attachment.original_filename : attachment.filename
+          end
+
+          # Let the template reach the core Application helpers (root_path, etc.).
+          def method_missing(name, *args, &block)
+            view.respond_to?(name, true) ? view.send(name, *args, &block) : super
+          end
+
+          def respond_to_missing?(name, include_private = false)
+            view.respond_to?(name, include_private) || super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/snapshot_ui/rails/web/views/snapshots/mail/show.html.erb

@@ -0,0 +1,56 @@
+<body id="snapshots_mail" <%= refresh_controller %>>
+  <div class="mail">
+    <header class="mail_header">
+      <a class="back" href="<%= root_path %>">&larr; All snapshots</a>
+      <h1><%= h(mail.message.subject) %></h1>
+      <% if mail.mailer || mail.action %>
+        <p class="mailer"><%= h([mail.mailer, mail.action].compact.join("#")) %></p>
+      <% end %>
+
+      <dl class="fields">
+        <dt>From</dt><dd><%= h(mail.message.header["from"]) %></dd>
+        <dt>To</dt><dd><%= h(mail.message.header["to"]) %></dd>
+        <% if mail.message.cc %><dt>Cc</dt><dd><%= h(mail.message.header["cc"]) %></dd><% end %>
+        <% if mail.message.bcc && !Array(mail.message.bcc).empty? %><dt>Bcc</dt><dd><%= h(Array(mail.message.bcc).join(", ")) %></dd><% end %>
+        <% if mail.message.reply_to %><dt>Reply-To</dt><dd><%= h(mail.message.header["reply-to"]) %></dd><% end %>
+      </dl>
+
+      <div class="mail_toolbar">
+        <% if mail.multipart_alternatives? %>
+          <div class="parts">
+            <a class="part_tab <%= "is_active" if part == SnapshotUI::Rails::Mail::HTML %>" href="<%= show_url(SnapshotUI::Rails::Mail::HTML) %>">HTML</a>
+            <a class="part_tab <%= "is_active" if part == SnapshotUI::Rails::Mail::TEXT %>" href="<%= show_url(SnapshotUI::Rails::Mail::TEXT) %>">Plain text</a>
+          </div>
+        <% else %>
+          <span class="part_single"><%= part == SnapshotUI::Rails::Mail::HTML ? "HTML email" : "Plain-text email" %></span>
+        <% end %>
+
+        <a class="eml" href="<%= eml_url %>">Download .eml</a>
+      </div>
+
+      <% unless mail.attachments.empty? %>
+        <div class="attachments">
+          <span class="attachments_label">Attachments:</span>
+          <% mail.attachments.each do |attachment| %>
+            <a class="attachment" href="<%= attachment_data_uri(attachment) %>" download="<%= h(attachment_filename(attachment)) %>"><%= h(attachment_filename(attachment)) %></a>
+          <% end %>
+        </div>
+      <% end %>
+
+      <details class="all_headers">
+        <summary>All headers</summary>
+        <table>
+          <% mail.message.header_fields.each do |field| %>
+            <tr><td class="name"><%= h(field.name) %></td><td><%= h(field.value) %></td></tr>
+          <% end %>
+        </table>
+      </details>
+    </header>
+
+    <% if mail.part_body(part) %>
+      <iframe id="raw" class="mail_body <%= "is_text" if part == SnapshotUI::Rails::Mail::TEXT %>" src="<%= raw_part_url(part) %>"></iframe>
+    <% else %>
+      <p class="empty">This email has no <%= part == SnapshotUI::Rails::Mail::HTML ? "HTML" : "plain-text" %> part.</p>
+    <% end %>
+  </div>
+</body>

data/lib/snapshot_ui/rails.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "snapshot_ui"
+require_relative "rails/version"
+
+module SnapshotUI
+  # Rails integration for Snapshot UI. Requiring this file (which Bundler does
+  # automatically for the +snapshot_ui-rails+ gem) loads the railtie that
+  # configures Snapshot UI from the Rails application and adds the router and
+  # test helpers.
+  #
+  # With the defaults no configuration is needed. To override, set values under
+  # +config.snapshot_ui+ (see the README).
+  module Rails
+    DEFAULT_MOUNT_PATH = "/rails/ui_snapshots"
+    DEFAULT_HOST = "http://localhost:3000"
+
+    class << self
+      # The path the UI is mounted at. Set by the railtie from
+      # +config.snapshot_ui.mount_path+; used to build the default web URL and
+      # by +mount_snapshot_ui+.
+      attr_writer :mount_path
+
+      def mount_path
+        @mount_path || DEFAULT_MOUNT_PATH
+      end
+
+      # Builds the URL the "ready for review" message and the empty-state link
+      # point at, from a host (scheme://host:port) and the mount path.
+      def web_url(host:, mount_path: self.mount_path)
+        "#{host.to_s.chomp("/")}#{mount_path}"
+      end
+
+      # The host (scheme://host[:port]) to use when the application hasn't been
+      # told one explicitly. Rails does not know the address its development
+      # server will bind to, so this is a best effort: the host declared in
+      # +config.action_controller.default_url_options+ if present, then the PORT
+      # environment variable, then the conventional http://localhost:3000.
+      def default_host(app)
+        options = default_url_options(app)
+        return DEFAULT_HOST if options.empty? && !ENV.key?("PORT")
+
+        scheme = url_scheme(app, options)
+        host = options[:host] || "localhost"
+        port = options[:port] || ENV["PORT"] || 3000
+
+        "#{scheme}://#{host}:#{port}"
+      end
+
+      private
+
+      def default_url_options(app)
+        app.config.action_controller.default_url_options || {}
+      rescue
+        {}
+      end
+
+      def url_scheme(app, options)
+        scheme = options[:protocol] || (app.config.force_ssl ? "https" : "http")
+        scheme.to_s.sub(%r{://\z}, "")
+      end
+    end
+  end
+end
+
+require_relative "rails/railtie"

data/lib/snapshot_ui-rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# The gem is named "snapshot_ui-rails"; its code lives under SnapshotUI::Rails.
+require_relative "snapshot_ui/rails"

data/snapshot_ui-rails.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../snapshot_ui/lib/snapshot_ui/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "snapshot_ui-rails"
+  spec.version = SnapshotUI::VERSION
+  spec.authors = ["Tomaz Zlender"]
+  spec.email = ["tomaz@zlender.se"]
+
+  spec.summary = "Rails integration for Snapshot UI — take snapshots of responses in tests and view them in a browser."
+  spec.homepage = "https://github.com/tomazzlender/snapshot_ui"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/main/gems/snapshot_ui-rails"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/gems/snapshot_ui-rails/CHANGELOG.md"
+
+  gem_root = File.expand_path(__dir__)
+  spec.files = Dir.chdir(gem_root) do
+    Dir.glob(%w[lib/**/* snapshot_ui-rails.gemspec README.md CHANGELOG.md LICENSE.txt]).select { |path| File.file?(path) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "snapshot_ui", SnapshotUI::VERSION
+  spec.add_dependency "railties", ">= 7.1", "< 9"
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: snapshot_ui-rails
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Tomaz Zlender
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: snapshot_ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+email:
+- tomaz@zlender.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/snapshot_ui-rails.rb
+- lib/snapshot_ui/rails.rb
+- lib/snapshot_ui/rails/mail.rb
+- lib/snapshot_ui/rails/mail_snapshot.rb
+- lib/snapshot_ui/rails/railtie.rb
+- lib/snapshot_ui/rails/routes.rb
+- lib/snapshot_ui/rails/test/helpers.rb
+- lib/snapshot_ui/rails/version.rb
+- lib/snapshot_ui/rails/web/mail_renderer.rb
+- lib/snapshot_ui/rails/web/views/snapshots/mail/show.html.erb
+- snapshot_ui-rails.gemspec
+homepage: https://github.com/tomazzlender/snapshot_ui
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tomazzlender/snapshot_ui
+  source_code_uri: https://github.com/tomazzlender/snapshot_ui/tree/main/gems/snapshot_ui-rails
+  changelog_uri: https://github.com/tomazzlender/snapshot_ui/blob/main/gems/snapshot_ui-rails/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.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: Rails integration for Snapshot UI — take snapshots of responses in tests
+  and view them in a browser.
+test_files: []