snapshot_inspector 0.1.1

data/app/models/snapshot_inspector/snapshot/mail_type.rb

@@ -0,0 +1,35 @@
+require "mail"
+
+module SnapshotInspector
+  class Snapshot
+    class MailType < Type
+      snapshotee ActionMailer::MessageDelivery
+
+      # @private
+      def extract(snapshotee)
+        @message = snapshotee.to_s
+        @bcc = snapshotee.bcc
+      end
+
+      # @private
+      def from_hash(hash)
+        @message = hash[:message]
+        @bcc = hash[:bcc]
+      end
+
+      def message
+        message = Mail::Message.new(@message)
+        message.bcc = @bcc
+        message
+      end
+
+      def mailer_name
+        message.header["X-SnapshotInspector-Mailer-Name"].value
+      end
+
+      def action_name
+        message.header["X-SnapshotInspector-Action-Name"].value
+      end
+    end
+  end
+end

data/app/models/snapshot_inspector/snapshot/response_type.rb

@@ -0,0 +1,19 @@
+module SnapshotInspector
+  class Snapshot
+    class ResponseType < Type
+      snapshotee ActionDispatch::TestResponse
+
+      attr_reader :body
+
+      # @private
+      def extract(snapshotee)
+        @body = snapshotee.parsed_body
+      end
+
+      # @private
+      def from_hash(hash)
+        @body = hash[:body]
+      end
+    end
+  end
+end

data/app/models/snapshot_inspector/snapshot/rspec_context.rb

@@ -0,0 +1,52 @@
+module SnapshotInspector
+  class Snapshot
+    class RspecContext < Context
+      test_framework :rspec
+
+      attr_reader :test_framework, :example, :take_snapshot_index
+
+      # @private
+      def extract(context)
+        @test_framework = context[:test_framework]
+        @example = context[:example]
+        @take_snapshot_index = context[:take_snapshot_index]
+      end
+
+      # @private
+      def from_hash(hash)
+        @test_framework = hash[:test_framework].to_sym
+        @example = hash[:example]
+        @take_snapshot_index = hash[:take_snapshot_index]
+      end
+
+      def to_slug
+        spec_path_without_extension = @example[:file_path].delete_suffix(File.extname(@example[:file_path])).delete_prefix("./")
+        [spec_path_without_extension, @example[:line_number], @take_snapshot_index].join("_")
+      end
+
+      def name
+        @example[:full_description].gsub(test_group, "").strip
+      end
+
+      def test_group
+        root_example_group_description(@example)
+      end
+
+      def order_index
+        [@example[:file_path], @example[:line_number], @take_snapshot_index]
+      end
+
+      private
+
+      def root_example_group_description(hash)
+        if hash[:example_group].present?
+          root_example_group_description(hash[:example_group])
+        elsif hash[:parent_example_group].present?
+          root_example_group_description(hash[:parent_example_group])
+        else
+          hash[:description]
+        end
+      end
+    end
+  end
+end

data/app/models/snapshot_inspector/snapshot/test_unit_context.rb

@@ -0,0 +1,44 @@
+module SnapshotInspector
+  class Snapshot
+    class TestUnitContext < Context
+      test_framework :test_unit
+
+      attr_reader :test_framework, :test_case_name, :method_name, :source_location, :take_snapshot_index
+
+      # @private
+      def extract(context)
+        @test_framework = context[:test_framework]
+        @test_case_name = context[:test_case_name]
+        @method_name = context[:method_name]
+        @source_location = context[:source_location]
+        @take_snapshot_index = context[:take_snapshot_index]
+      end
+
+      # @private
+      def from_hash(hash)
+        @test_framework = hash[:test_framework].to_sym
+        @test_case_name = hash[:test_case_name]
+        @method_name = hash[:method_name]
+        @source_location = hash[:source_location]
+        @take_snapshot_index = hash[:take_snapshot_index]
+      end
+
+      def to_slug
+        spec_path_without_extension = source_location[0].delete_suffix(File.extname(source_location[0])).delete_prefix(Rails.root.to_s + "/")
+        [spec_path_without_extension, source_location[1], take_snapshot_index].join("_")
+      end
+
+      def name
+        method_name.gsub(/^test_/, "").humanize(capitalize: false)
+      end
+
+      def test_group
+        test_case_name
+      end
+
+      def order_index
+        source_location.dup << take_snapshot_index
+      end
+    end
+  end
+end

data/app/models/snapshot_inspector/snapshot/type.rb

@@ -0,0 +1,52 @@
+module SnapshotInspector
+  class Snapshot
+    class Type
+      class UnknownSnapshotee < StandardError; end
+
+      class_attribute :registry, default: {}, instance_writer: false, instance_predicate: false
+
+      def self.snapshotee(class_name)
+        registry[class_name] = self
+      end
+
+      def self.extract(snapshotee)
+        record = type_class(snapshotee.class).new
+        record.extract(snapshotee)
+        record
+      end
+
+      def self.from_hash(hash)
+        record = type_class(hash[:snapshotee_class].constantize).new
+        record.from_hash(hash)
+        record
+      end
+
+      private_class_method def self.type_class(snapshotee_class)
+        registry[snapshotee_class] || raise(UnknownSnapshotee.new(unknown_snapshotee_class_message(snapshotee_class)))
+      end
+
+      private_class_method def self.unknown_snapshotee_class_message(snapshotee_class)
+        list_of_known_classes = registry.keys.map(&:to_s).sort.map { |class_name| "`#{class_name}`" }.join(" or ")
+        "#take_snapshot only accepts an argument of kind #{list_of_known_classes}. You provided `#{snapshotee_class}`."
+      end
+
+      # @private
+      def extract(_snapshotee)
+        raise "Implement in a child class."
+      end
+
+      # @private
+      def from_hash(_hash)
+        raise "Implement in a child class."
+      end
+
+      def type
+        self.class.to_s.underscore.split("/").last.gsub("_type", "")
+      end
+
+      def as_json(data = {})
+        {snapshotee_class: registry.key(self.class)}.merge(super)
+      end
+    end
+  end
+end

data/app/models/snapshot_inspector/snapshot.rb

@@ -0,0 +1,86 @@
+require "snapshot_inspector/snapshot/response_type"
+require "snapshot_inspector/snapshot/mail_type"
+require "snapshot_inspector/snapshot/test_unit_context"
+require "snapshot_inspector/snapshot/rspec_context"
+
+module SnapshotInspector
+  class Snapshot
+    class NotFound < StandardError; end
+
+    attr_reader :context, :slug, :created_at
+    delegate_missing_to :@type_data
+
+    def self.persist(snapshotee:, context:)
+      new.extract(snapshotee: snapshotee, context: context).persist
+    end
+
+    def self.find(slug)
+      hash = JSON.parse(Storage.read(slug), symbolize_names: true)
+      new.from_hash(hash)
+    rescue Errno::ENOENT
+      raise NotFound.new("Snapshot with a slug `#{slug}` can't be found.")
+    end
+
+    def self.grouped_by_test_case
+      all.group_by do |snapshot|
+        snapshot.context.test_group
+      end
+    end
+
+    private_class_method def self.all
+      snapshots = Storage.list.map { |slug| find(slug) }
+
+      order_by_line_number(snapshots)
+    end
+
+    private_class_method def self.order_by_line_number(snapshots)
+      snapshots.sort_by do |snapshot|
+        snapshot.context.order_index
+      end
+    end
+
+    # @private
+    def extract(snapshotee:, context:)
+      extract_type_specific_data(snapshotee)
+      extract_context(context)
+
+      @slug = @context.to_slug
+      @created_at = Time.current
+      self
+    end
+
+    # @private
+    def persist
+      Storage.write(slug, JSON.pretty_generate(as_json))
+      self
+    end
+
+    # @private
+    def from_hash(hash)
+      from_hash_type_specific_data(hash)
+      from_hash_context(hash)
+
+      @slug = hash[:slug]
+      @created_at = Time.zone.parse(hash[:created_at])
+      self
+    end
+
+    private
+
+    def extract_type_specific_data(snapshotee)
+      @type_data = Type.extract(snapshotee)
+    end
+
+    def extract_context(context)
+      @context = Context.extract(context)
+    end
+
+    def from_hash_type_specific_data(hash)
+      @type_data = Type.from_hash(hash[:type_data])
+    end
+
+    def from_hash_context(hash)
+      @context = Context.from_hash(hash[:context])
+    end
+  end
+end

data/app/views/layouts/snapshot_inspector/application.html.erb

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Snapshot Inspector</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag "snapshot_inspector/application", media: "all" %>
+  <%= snapshot_inspector_importmap_tags %>
+  <%= javascript_import_module_tag "snapshot_inspector/application" %>
+  <% if defined?(Hotwire::Livereload::DISABLE_FILE) && !File.exist?(Rails.root.join(Hotwire::Livereload::DISABLE_FILE)) %>
+    <%= hotwire_livereload_tags %>
+  <% end %>
+</head>
+<body id="<%= "#{controller_name}_#{action_name}" %>">
+  <%= yield %>
+</body>
+</html>

data/app/views/snapshot_inspector/snapshots/index.html.erb

@@ -0,0 +1,29 @@
+<main>
+  <h1>Snapshots</h1>
+
+  <% if @grouped_by_test_class.blank? %>
+    <p>Place `take_screenshot response` in your integration tests after a `response` object is populated and run the tests. Snapshots will appear below.</p>
+  <% end %>
+
+  <%= form_tag "", method: :get, class: "enable_javascript" do %>
+    <%= label_tag :enable_javascript do %>
+      <%= check_box_tag :enable_javascript, "true", params[:enable_javascript] == "true", onclick: "submit()" %>
+      <span>Open snapshots with JavaScript enabled (by default all JavaScript tags are removed)</span>
+    <% end %>
+  <% end %>
+
+  <% @grouped_by_test_class.each do |test_group, snapshots| %>
+    <h2><%= test_group %></h2>
+
+    <ul>
+      <% snapshots.each do |snapshot| %>
+        <li>
+          <%= link_to SnapshotInspector::SnapshotsHelper.snapshot_path(snapshot, enable_javascript: params[:enable_javascript]) do %>
+            <%= snapshot.context.name %>
+            <%= if snapshot.context.take_snapshot_index > 0 then "(#{(snapshot.context.take_snapshot_index + 1).ordinalize} in the same test)" end %>
+          <% end %>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+</main>

data/app/views/snapshot_inspector/snapshots/mail/show.html.erb

@@ -0,0 +1,107 @@
+<header>
+  <dl>
+    <% if @email.respond_to?(:smtp_envelope_from) && Array(@email.from) != Array(@email.smtp_envelope_from) %>
+      <dt>SMTP-From:</dt>
+      <dd id="smtp_from"><%= @email.smtp_envelope_from %></dd>
+    <% end %>
+
+    <% if @email.respond_to?(:smtp_envelope_to) && @email.to != @email.smtp_envelope_to %>
+      <dt>SMTP-To:</dt>
+      <dd id="smtp_to"><%= @email.smtp_envelope_to %></dd>
+    <% end %>
+
+    <dt>From:</dt>
+    <dd id="from"><%= @email.header['from'] %></dd>
+
+    <% if @email.reply_to %>
+      <dt>Reply-To:</dt>
+      <dd id="reply_to"><%= @email.header['reply-to'] %></dd>
+    <% end %>
+
+    <dt>To:</dt>
+    <dd id="to"><%= @email.header['to'] %></dd>
+
+    <% if @email.cc %>
+      <dt>CC:</dt>
+      <dd id="cc"><%= @email.header['cc'] %></dd>
+    <% end %>
+
+    <% if @email.bcc %>
+      <dt>BCC:</dt>
+      <dd id="bcc"><%= @email.header['bcc'] %></dd>
+    <% end %>
+
+    <dt>Date:</dt>
+    <dd id="date"><%= Time.current.rfc2822 %></dd>
+
+    <dt>Subject:</dt>
+    <dd><strong id="subject"><%= @email.subject %></strong></dd>
+
+    <% unless @email.attachments.nil? || @email.attachments.empty? %>
+      <dt>Attachments:</dt>
+      <dd>
+        <% @email.attachments.each do |a| %>
+          <% filename = a.respond_to?(:original_filename) ? a.original_filename : a.filename %>
+          <%= link_to filename, "data:application/octet-stream;charset=utf-8;base64,#{Base64.encode64(a.body.to_s)}", download: filename %>
+        <% end %>
+      </dd>
+    <% end %>
+
+    <dt>Format:</dt>
+    <% if @email.html_part && @email.text_part %>
+      <dd>
+        <select id="part" onchange="refreshBody();">
+          <option <%= request.format == Mime[:html] ? 'selected' : '' %> value="<%= part_query('text/html') %>">View as HTML email</option>
+          <option <%= request.format == Mime[:text] ? 'selected' : '' %> value="<%= part_query('text/plain') %>">View as plain-text email</option>
+        </select>
+      </dd>
+    <% elsif @part %>
+      <dd id="mime_type" data-mime-type="<%= part_query(@part.mime_type) %>"><%= @part.mime_type == 'text/html' ? 'HTML email' : 'plain-text email' %></dd>
+    <% else %>
+      <dd id="mime_type" data-mime-type=""></dd>
+    <% end %>
+
+    <% unless @email.header_fields.blank? %>
+      <dt>Headers:</dt>
+      <dd>
+        <details>
+          <summary>Show all headers</summary>
+          <table>
+            <% @email.header_fields.each do |field| %>
+              <tr>
+                <td align="right" style="color: #7f7f7f"><%= field.name %>:</td>
+                <td><%= field.value %></td>
+              </tr>
+            <% end %>
+          </table>
+        </details>
+      </dd>
+    <% end %>
+
+    <dt>EML File:</dt>
+    <dd><%= link_to "Download", format: :eml %></dd>
+  </dl>
+</header>
+
+<% if @part && @part.mime_type %>
+  <iframe name="messageBody" src="<%= raw_mail_snapshot_path(slug: @snapshot.slug, part: @part.mime_type) %>"></iframe>
+<% else %>
+  <p>
+    You are trying to preview an email that does not have any content.
+    This is probably because the <em>mail</em> method has not been called in <em><%= @preview.preview_name %>#<%= @email_action %></em>.
+  </p>
+<% end %>
+
+<script>
+  function refreshBody() {
+    const part_select = document.querySelector('select#part');
+    const part_param = part_select ?
+      part_select.options[part_select.selectedIndex].value :
+      document.querySelector('#mime_type').dataset.mimeType;
+
+    const url = location.pathname.replace(/\.(txt|html)$/, '');
+    const format = /html/.test(part_param) ? '.html' : '.txt';
+
+    location.href = url + format;
+  }
+</script>

data/app/views/snapshot_inspector/snapshots/not_found.html.erb

@@ -0,0 +1,8 @@
+<main id="not_found">
+  <h1>Not Found</h1>
+
+  <p>
+    <%= @error %>
+    Go back to <%= link_to "a list of snapshots", root_path, style: "text-decoration: underline; color: #666" %>.
+  </p>
+</main>

data/app/views/snapshot_inspector/snapshots/response/raw.html.erb

@@ -0,0 +1 @@
+<%= prepare_for_render(@snapshot.body, enable_javascript: params[:enable_javascript]) %>

data/app/views/snapshot_inspector/snapshots/response/show.html.erb

@@ -0,0 +1 @@
+<iframe id="body" src="<%= raw_response_snapshot_path(@snapshot.slug, enable_javascript: params[:enable_javascript]) %>"></iframe>

data/config/importmap.rb

@@ -0,0 +1,12 @@
+require "snapshot_inspector"
+
+SnapshotInspector.configuration.importmap.draw do
+  pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
+  pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true
+  pin "stimulus-use", to: "https://ga.jspm.io/npm:stimulus-use@0.51.3/dist/index.js"
+  pin "hotkeys-js", to: "https://ga.jspm.io/npm:hotkeys-js@3.10.1/dist/hotkeys.esm.js"
+
+  pin "application", to: "snapshot_inspector/application.js", preload: true
+
+  pin_all_from SnapshotInspector::Engine.root.join("app/assets/javascripts/snapshot_inspector/controllers"), under: "controllers", to: "snapshot_inspector/controllers"
+end

data/config/routes.rb

@@ -0,0 +1,9 @@
+SnapshotInspector::Engine.routes.draw do
+  root to: "snapshots#index"
+
+  get "mail/raw/*slug", to: "snapshots/mail#raw", as: :raw_mail_snapshot
+  get "mail/*slug", to: "snapshots/mail#show", as: :mail_snapshot
+
+  get "response/raw/*slug", to: "snapshots/response#raw", as: :raw_response_snapshot
+  get "response/*slug", to: "snapshots/response#show", as: :response_snapshot
+end

data/lib/minitest/snapshot_inspector_plugin.rb

@@ -0,0 +1,28 @@
+require "snapshot_inspector"
+require "snapshot_inspector/storage"
+require "minitest"
+
+module Minitest
+  class SnapshotInspectorReporter < Reporter
+    def report
+      SnapshotInspector::Storage.move_files_from_processing_directory_to_snapshots_directory if SnapshotInspector::Storage.processing_directory.exist?
+
+      io.print "\n\nInspect snapshots on #{SnapshotInspector.configuration.host + SnapshotInspector.configuration.route_path}"
+    end
+  end
+
+  class << self
+    def plugin_snapshot_inspector_options(opts, _options)
+      opts.on "--take-snapshots", "Take snapshots of responses for inspecting at #{SnapshotInspector.configuration.host + SnapshotInspector.configuration.route_path}" do
+        SnapshotInspector.configuration.snapshot_taking_enabled = true
+      end
+    end
+
+    def plugin_snapshot_inspector_init(_options)
+      return unless SnapshotInspector.configuration.snapshot_taking_enabled
+
+      reporter << SnapshotInspectorReporter.new
+      SnapshotInspector::Storage.clear(:processing)
+    end
+  end
+end

data/lib/snapshot_inspector/engine.rb

@@ -0,0 +1,67 @@
+require "importmap-rails"
+require "snapshot_inspector/test/action_mailer_headers"
+
+module SnapshotInspector
+  class Engine < ::Rails::Engine
+    isolate_namespace SnapshotInspector
+
+    config.before_configuration do |_app|
+      SnapshotInspector.configuration.storage_directory = Rails.root.join(SnapshotInspector::STORAGE_DIRECTORY)
+    end
+
+    unless Rails.env.test?
+      rake_tasks do
+        load "tasks/tmp.rake"
+      end
+    end
+
+    initializer "snapshot_inspector.importmap", before: "importmap" do |app|
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+    end
+
+    initializer "snapshot_inspector.assets.precompile" do |app|
+      app.config.assets.precompile += %w[snapshot_inspector/manifest]
+    end
+
+    initializer "snapshot_inspector.include_test_helpers" do |_app|
+      if defined?(RSpec)
+        RSpec.configure do |config|
+          config.include SnapshotInspector::Test::RSpecHelpers
+          config.after :suite do
+            SnapshotInspector::Storage.move_files_from_processing_directory_to_snapshots_directory if SnapshotInspector::Storage.processing_directory.exist?
+          end
+        end
+      else
+        ActiveSupport.on_load(:active_support_test_case) do
+          include SnapshotInspector::Test::TestUnitHelpers
+        end
+      end
+
+      ActiveSupport.on_load(:action_mailer) do
+        include SnapshotInspector::Test::ActionMailerHeaders
+      end
+    end
+
+    initializer "snapshot_inspector.configure_default_url_options" do |_app|
+      url_options =
+        if Rails.application.routes.default_url_options.present?
+          Rails.application.routes.default_url_options
+        elsif Rails.application.config.action_controller.default_url_options.present?
+          Rails.application.config.action_controller.default_url_options
+        end
+
+      SnapshotInspector.configuration.host = url_options ? [url_options[:host], url_options[:port]].join(":") : SnapshotInspector.configuration.host
+    end
+
+    initializer "snapshot_inspector.register_eml_mime_type" do |_app|
+      Mime::Type.register "application/octet-stream", :eml
+    end
+
+    config.after_initialize do |app|
+      app.routes.prepend do
+        mount SnapshotInspector::Engine, at: SnapshotInspector.configuration.route_path
+      end
+    end
+  end
+end

data/lib/snapshot_inspector/storage.rb

@@ -0,0 +1,60 @@
+module SnapshotInspector
+  class Storage
+    class << self
+      def snapshots_directory
+        SnapshotInspector.configuration.storage_directory.join("snapshots")
+      end
+
+      def processing_directory
+        SnapshotInspector.configuration.storage_directory.join("processing")
+      end
+
+      def write(key, value)
+        file_path = to_file_path_for_writing(key)
+        file_path.dirname.mkpath
+        file_path.write(value)
+      end
+
+      def read(key)
+        File.read(to_file_path_for_reading(key))
+      end
+
+      def list
+        Dir
+          .glob("#{snapshots_directory}/**/*.{json}")
+          .map { |file_path| to_key(file_path) }
+      end
+
+      def clear(directory = nil)
+        case directory
+        when :snapshots
+          snapshots_directory.rmtree
+        when :processing
+          processing_directory.rmtree
+        else
+          snapshots_directory.rmtree
+          processing_directory.rmtree
+        end
+      end
+
+      def move_files_from_processing_directory_to_snapshots_directory
+        clear(:snapshots)
+        processing_directory.rename(snapshots_directory)
+      end
+
+      private
+
+      def to_key(file_path)
+        file_path.gsub(snapshots_directory.to_s + "/", "").gsub(".json", "")
+      end
+
+      def to_file_path_for_reading(key)
+        snapshots_directory.join("#{key}.json")
+      end
+
+      def to_file_path_for_writing(key)
+        processing_directory.join("#{key}.json")
+      end
+    end
+  end
+end

data/lib/snapshot_inspector/test/action_mailer_headers.rb

@@ -0,0 +1,18 @@
+module SnapshotInspector
+  module Test
+    module ActionMailerHeaders
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :snapshot_inspector_headers, if: -> { Rails.env.test? }
+      end
+
+      private
+
+      def snapshot_inspector_headers
+        headers["X-SnapshotInspector-Mailer-Name"] = mailer_name
+        headers["X-SnapshotInspector-Action-Name"] = action_name
+      end
+    end
+  end
+end