snapshot_ui 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db2e79495a612dd8f9e73f84537b5237c214faf5290915f40a451b27c517fb10
+  data.tar.gz: 5f68e150a5439073be54508096b9a085277d1cfe03292a78e396c6f790c17a0d
+SHA512:
+  metadata.gz: e20faf53a0f05035d90e76e10d08a7a067728899df4bc6e5dc9c3dda944c7414579b334650c4b9a8edfc1ad2889bb7b65537d22120cb9cbc2a92b4b0378d2598
+  data.tar.gz: c6fa887d47cfec6bf20f91146e37f0165655601b4d3a38bb43e74b735dcde65da4453a672d147cb305f0cc67dc4d5338ece722b7224f428527917e8f49b30370

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-06-09
+
+- Initial release

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,16 @@
+# SnapshotUI
+
+## Things to do next
+
+- Live reloads after a test run and new snapshots become published
+- Accept not only "response" objects but also just plain strings for testing UI helpers (think buttons, etc.)
+- Make it easier to navigate between a list of snapshots and the code
+- Ability to disable or enable javascript of the rendered snapshots
+
+## Things to do in the far future
+
+- Different representations of snapshot lists
+- Spatially display snapshots and how they connect to each other to demonstrate UI flows
+- Extract more information out of response snapshots - path, page title, how they connect to other snapshots
+- Possibility to add notes to snapshots from within tests (`take_snapshot response, note: "...")
+

data/bin/snapshot_ui

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), '../lib'))
+
+require "snapshot_ui/cli"
+
+SnapshotUI::CLI.start(ARGV)

data/lib/snapshot_ui/cli/watcher.ru

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/http/endpoint"
+require "async/websocket/client"
+require "async/websocket/adapters/rack"
+require "listen"
+require "set"
+
+SNAPSHOT_DIRECTORY = ENV.fetch("SNAPSHOT_DIRECTORY")
+WEBSOCKET_ENDPOINT = "http://localhost:7070/cable"
+
+REFRESH_MESSAGE = {identifier: "{\"channel\":\"RefreshChannel\"}", message: "refresh"}.to_json
+CONFIRM_SUBSCRIPTION_MESSAGE = {identifier: "{\"channel\":\"RefreshChannel\"}", type: "confirm_subscription"}.to_json
+PING_MESSAGE = {type: "ping", message: Time.now.to_i.to_s}.to_json
+
+@connections = Set.new
+
+run lambda { |env|
+  if env["REQUEST_PATH"] == "/cable"
+    Async::WebSocket::Adapters::Rack.open(env, protocols: ["actioncable-v1-json"]) do |connection|
+      @connections << connection
+
+      Console.info "Client connected."
+      connection.write(CONFIRM_SUBSCRIPTION_MESSAGE)
+      connection.flush
+
+      Async do |ping_task|
+        loop do
+          connection.write(PING_MESSAGE)
+          connection.flush
+          sleep(2)
+        end
+      ensure
+        ping_task&.stop
+      end
+
+      while connection.read
+      end
+    rescue Protocol::WebSocket::ClosedError
+      Console.info "Client disconnected."
+      @connections.delete(connection)
+    ensure
+      Console.info "Client disconnected."
+      @connections.delete(connection)
+    end
+  else
+    [404, {}, ["404 Not Found"]]
+  end
+}
+
+Async do |client_task|
+  endpoint = Async::HTTP::Endpoint.parse(WEBSOCKET_ENDPOINT)
+
+  Async::WebSocket::Client.connect(endpoint) do |connection|
+    Async do |listener_task|
+      detect_snapshots_update(listener_task)
+    end
+
+    while (message = connection.read)
+      if message == REFRESH_MESSAGE
+        Console.info "Snapshots updated."
+      end
+    end
+  ensure
+    client_task&.stop
+  end
+end
+
+def detect_snapshots_update(task)
+  Pathname.new(SNAPSHOT_DIRECTORY).mkpath
+  listener = Listen.to(SNAPSHOT_DIRECTORY) { |_modified, _added, _removed| broadcast_update }
+
+  task.async do
+    listener.start
+    task.sleep
+  end
+
+  Console.info("Watching for snapshots updates in #{SNAPSHOT_DIRECTORY}...")
+end
+
+def broadcast_update
+  @connections.each do |connection|
+    connection.write(REFRESH_MESSAGE)
+    connection.flush
+  rescue => e
+    Console.error "Failed to send message to client: #{e.message}"
+  end
+end

data/lib/snapshot_ui/cli.rb

@@ -0,0 +1,26 @@
+require "bundler/setup"
+require "thor"
+require "pathname"
+
+module SnapshotUI
+  class CLI < Thor
+    WEBSOCKET_HOST = "localhost:7070"
+
+    desc "watch SNAPSHOT_DIRECTORY", "Watches for snapshot changes in SNAPSHOT_DIRECTORY and broadcasts them on ws://#{WEBSOCKET_HOST}/cable."
+    def watch(snapshot_directory)
+      unless File.exist?(snapshot_directory)
+        puts "The provided directory `#{snapshot_directory}` doesn't exist. Please double check the path."
+        exit 1
+      end
+
+      websocket_host = "http://#{WEBSOCKET_HOST}"
+      config_path = Pathname.new(__dir__).join("cli", "watcher.ru").cleanpath.to_s
+
+      exec "SNAPSHOT_DIRECTORY=#{snapshot_directory} bundle exec falcon serve --bind #{websocket_host} --count 1 --config #{config_path}"
+    end
+
+    def self.exit_on_failure?
+      true
+    end
+  end
+end

data/lib/snapshot_ui/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SnapshotUI
+  class Configuration
+    attr_writer :storage_directory, :project_root_directory
+
+    def initialize(project_root_directory:, storage_directory:)
+      @project_root_directory = project_root_directory
+      @storage_directory = storage_directory
+    end
+
+    def storage_directory
+      Pathname.new(@storage_directory)
+    end
+
+    def project_root_directory
+      Pathname.new(@project_root_directory)
+    end
+  end
+end

data/lib/snapshot_ui/snapshot/context.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SnapshotUI
+  class Snapshot
+    class Context
+      attr_reader :test_framework, :test_case_name, :method_name, :source_location, :take_snapshot_index
+
+      def initialize(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
+
+      def to_slug
+        test_path_without_extension =
+          source_location[0]
+            .delete_suffix(File.extname(source_location[0]))
+            .delete_prefix(SnapshotUI.configuration.project_root_directory.to_s + "/")
+
+        [test_path_without_extension, source_location[1], take_snapshot_index].join("_")
+      end
+
+      def name
+        method_name
+      end
+
+      def test_group
+        test_case_name
+      end
+
+      def order_index
+        source_location.dup << take_snapshot_index
+      end
+    end
+  end
+end

data/lib/snapshot_ui/snapshot/storage.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SnapshotUI
+  class Snapshot
+    class Storage
+      class << self
+        def snapshots_directory
+          SnapshotUI.configuration.storage_directory.join("snapshots")
+        end
+
+        def in_progress_directory
+          SnapshotUI.configuration.storage_directory.join("in_progress")
+        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)
+          to_file_path_for_reading(key).read
+        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 :in_progress
+            in_progress_directory.rmtree
+          else
+            snapshots_directory.rmtree
+            in_progress_directory.rmtree
+          end
+        end
+
+        def publish_snapshots_in_progress
+          clear(:snapshots)
+          in_progress_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)
+          in_progress_directory.join("#{key}.json")
+        end
+      end
+    end
+  end
+end

data/lib/snapshot_ui/snapshot.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "snapshot/context"
+require_relative "snapshot/storage"
+require "json"
+
+module SnapshotUI
+  class Snapshot
+    attr_reader :slug, :context, :body
+
+    class NotFound < StandardError; end
+
+    def self.persist(snapshotee:, context:)
+      new.extract(snapshotee: snapshotee, context: context).persist
+    end
+
+    def self.find(slug)
+      json = JSON.parse(Storage.read(slug), symbolize_names: true)
+      new.from_json(json)
+    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
+
+    def self.publish_snapshots_in_progress
+      return unless SnapshotUI::Snapshot::Storage.in_progress_directory.exist?
+      SnapshotUI::Snapshot::Storage.publish_snapshots_in_progress
+    end
+
+    def self.clear_snapshots_in_progress
+      Storage.clear(:in_progress)
+    end
+
+    def self.clear_snapshots
+      Storage.clear
+    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
+
+    def extract(snapshotee:, context:)
+      @body = snapshotee.body
+      @snapshotee_class = snapshotee.class.to_s
+      @context = Context.new(context)
+      self
+    end
+
+    def persist
+      Storage.write(context.to_slug, JSON.pretty_generate(as_json))
+    end
+
+    def as_json
+      {
+        type_data: {
+          snapshotee_class: @snapshotee_class,
+          body: body
+        },
+        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
+        },
+        slug: context.to_slug
+      }
+    end
+
+    def from_json(json)
+      @body = json[:type_data][:body]
+      @context = Context.new(json[:context])
+      @slug = json[:slug]
+      self
+    end
+  end
+end

data/lib/snapshot_ui/test/minitest_helpers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../../snapshot_ui"
+require_relative "../snapshot"
+
+module SnapshotUI
+  module Test
+    module MinitestHelpers
+      def take_snapshot(snapshotee)
+        return unless SnapshotUI.snapshot_taking_enabled?
+
+        unless snapshotee.respond_to?(:body)
+          message =
+            "#take_snapshot only accepts an argument that responds to a method `#body`. " \
+            "You provided an argument of type `#{snapshotee.class}` that does not respond to `#body`."
+          raise ArgumentError.new(message)
+        end
+
+        increment_take_snapshot_counter_scoped_by_test
+
+        SnapshotUI::Snapshot.persist(
+          snapshotee: snapshotee,
+          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
+          }
+        )
+      end
+
+      private
+
+      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

data/lib/snapshot_ui/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SnapshotUI
+  VERSION = "0.1.0"
+end

data/lib/snapshot_ui/web/application.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "erb"
+require "rack/static"
+require_relative "../snapshot"
+require "listen"
+
+module SnapshotUI
+  class Web
+    class Application
+      def call(env)
+        @request = Rack::Request.new(env)
+
+        if parse_root_path(@request.path_info)
+          @grouped_by_test_class = SnapshotUI::Snapshot.grouped_by_test_case
+          if @request.get_header("HTTP_ACCEPT") != "text/event-stream"
+            render("snapshots/index", status: 200)
+          else
+            [200, {"content-type" => "text/event-stream", "cache-control" => "no-cache", "connection" => "keep-alive"}, file_event_stream(SnapshotUI.configuration.storage_directory)]
+          end
+        elsif (slug = parse_raw_snapshot_path(@request.path_info))
+          @snapshot = Snapshot.find(slug)
+          render_raw_response_body(@snapshot.body)
+        elsif (slug = parse_snapshot_path(@request.path_info))
+          @snapshot = Snapshot.find(slug)
+          render("snapshots/show", status: 200)
+        else
+          render("snapshots/not_found", status: 200)
+        end
+      rescue SnapshotUI::Snapshot::NotFound
+        render("snapshots/not_found", status: 200)
+      end
+
+      private
+
+      def file_event_stream(directory)
+        message = '<turbo-stream action="refresh"></turbo-stream>'
+
+        Enumerator.new do |stream|
+          listener = Listen.to(directory) do |_modified, _added, _removed|
+            stream << "data: #{message}\n\n"
+          end
+
+          listener.start
+          sleep
+        rescue Puma::ConnectionError
+          listener.stop
+          puts "Puma::ConnectionError"
+        rescue Errno::EPIPE
+          listener.stop
+          puts "Errno::EPIPE"
+        end
+      end
+
+      def render_raw_response_body(response_body)
+        [200, {"content-type" => "text/html; charset=utf-8"}, [response_body]]
+      end
+
+      def render(template, status:)
+        rendered_view = ERB.new(read_template(template)).result(binding)
+        response_body = ERB.new(read_template("layout")).result(get_binding { rendered_view })
+        response_headers = {"content-type" => "text/html; charset=utf-8"}
+
+        [status, response_headers, [response_body]]
+      end
+
+      def get_binding
+        binding
+      end
+
+      def read_template(template)
+        File.read(template_path(template))
+      end
+
+      def template_path(template)
+        "#{File.dirname(__FILE__)}/views/#{template}.html.erb"
+      end
+
+      def root_path
+        @request.env["SCRIPT_NAME"]
+      end
+
+      def stylesheet_path(stylesheet)
+        [root_path, "stylesheets", stylesheet].join("/")
+      end
+
+      def javascript_path(stylesheet)
+        [root_path, "javascripts", stylesheet].join("/")
+      end
+
+      def snapshot_path(slug)
+        [root_path, "response", slug].join("/")
+      end
+
+      def raw_snapshot_path(slug)
+        [root_path, "response", "raw", slug].join("/")
+      end
+
+      def parse_snapshot_path(path)
+        pattern = %r{^/response/(?<slug>.+)$}
+
+        if (match = pattern.match(path))
+          match[:slug]
+        end
+      end
+
+      def parse_raw_snapshot_path(path)
+        pattern = %r{^/response/raw/(?<slug>.+)$}
+
+        if (match = pattern.match(path))
+          match[:slug]
+        end
+      end
+
+      def parse_root_path(path)
+        path == "" || path == "/"
+      end
+
+      def refresh_controller
+        'data-controller="refresh" data-action="refresh-connected@window->refresh#connected refresh-disconnected@window->refresh#disconnected turbo:before-render@window->refresh#display_status"'
+      end
+    end
+  end
+end

data/lib/snapshot_ui/web/assets/javascripts/application.js

@@ -0,0 +1,8 @@
+import { Application } from "@hotwired/stimulus"
+import "@hotwired/turbo"
+import "channels"
+
+import RefreshController from "controllers/refresh_controller"
+
+window.Stimulus = Application.start()
+Stimulus.register("refresh", RefreshController)

data/lib/snapshot_ui/web/assets/javascripts/channels/consumer.js

@@ -0,0 +1,3 @@
+import { createConsumer } from "@rails/actioncable"
+
+export default createConsumer()

data/lib/snapshot_ui/web/assets/javascripts/channels/index.js

@@ -0,0 +1 @@
+import "channels/refresh_channel"

data/lib/snapshot_ui/web/assets/javascripts/channels/refresh_channel.js

@@ -0,0 +1,27 @@
+import consumer from "channels/consumer"
+import * as Turbo from "@hotwired/turbo"
+
+consumer.subscriptions.create("RefreshChannel", {
+  connected() {
+    console.log("Connected. Waiting for snapshots updates...")
+
+    const connected_event = new CustomEvent("refresh-connected");
+    window.dispatchEvent(connected_event);
+  },
+
+  disconnected() {
+    console.log("Unsubscribed from snapshots updates. Trying to reconnect...")
+
+    const disconnected_event = new CustomEvent("refresh-disconnected");
+    window.dispatchEvent(disconnected_event);
+  },
+
+  received(_data) {
+    console.log("Snapshots updated.")
+    Turbo.visit(location, { action: "replace" })
+
+    if (document.querySelector("iframe#raw")) {
+      document.querySelector("iframe#raw").contentWindow.location.reload()
+    }
+  }
+});

data/lib/snapshot_ui/web/assets/javascripts/controllers/refresh_controller.js

@@ -0,0 +1,25 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  connect() {
+    this.display_status()
+  }
+
+  connected(_event) {
+    window.refresh_status = "connected"
+    this.display_status()
+  }
+
+  disconnected(_event) {
+    window.refresh_status = undefined
+    this.display_status()
+  }
+
+  display_status() {
+    if (window.refresh_status === "connected") {
+      document.title = "Snapshot UI - ✅ Connected"
+    } else {
+      document.title = "Snapshot UI - ⏳ Reconnecting..."
+    }
+  }
+}

data/lib/snapshot_ui/web/assets/stylesheets/application.css

@@ -0,0 +1,108 @@
+html {
+    height: 100%;
+}
+
+body {
+    background-color: #fff;
+    color: #333;
+    margin: 0;
+    padding: 0;
+    height: 100%;
+}
+
+body, p, ul {
+    font-family: helvetica, verdana, arial, sans-serif;
+    font-size:   20px;
+    line-height: 1.7em;
+}
+
+body#snapshots_index {
+    padding: 100px;
+}
+
+body#snapshots_index h1 {
+    margin: 0;
+    font-size: 30px;
+}
+
+body#snapshots_index h2 {
+    margin: 30px 0 0;
+    font-size: 24px;
+}
+
+body#snapshots_index p {
+    margin: 18px 0 0;
+    color: #666666;
+}
+
+body#snapshots_index ul {
+    margin: 3px 0 0;
+}
+
+body#snapshots_index h1, h2, h3, h4, h5, h6 {
+    font-weight: normal;
+    color: #666666;
+}
+
+body#snapshots_index a { color: #000; text-decoration: none; }
+body#snapshots_index a:hover { text-decoration: underline; }
+
+body#snapshots_index code {
+    background: rgba(175, 184, 193, 0.2);
+    font-size: 85%;
+    padding: .2em .4em;
+    border-radius: 6px;
+    font-family: Menlo, Courier, monospace;
+}
+
+body#snapshots_index pre {
+    background: rgb(246, 248, 250);;
+    font-size: 75%;
+    padding: 16px;
+    margin: 15px 0 0;
+    display: inline-block;
+    border-radius: 6px;
+    line-height: 1.5em;
+    font-family: Menlo, Courier, monospace;
+}
+
+body#snapshots_index pre mark {
+    background: lightgoldenrodyellow;
+    border: 1px solid #f1f1c3;
+    padding: 2px 3px;
+    position: relative;
+    left: -4px;
+    border-radius: 6px;
+}
+
+body#snapshots_show {
+    overflow: hidden;
+}
+
+body#snapshots_show iframe#raw {
+    border: 0;
+    width: 100%;
+    height: 100%;
+}
+
+body#not_found {
+    padding: 100px;
+}
+
+body#not_found h1 {
+    margin: 0;
+    font-size: 30px;
+    font-weight: normal;
+    color: #666666;
+}
+
+body#not_found p {
+    margin: 18px 0 0;
+    color: #666666;
+}
+
+/* Hotwired Turbo related */
+.turbo-progress-bar {
+    height: 2px;
+    background-color: lightskyblue;
+}

data/lib/snapshot_ui/web/views/layout.html.erb

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Snapshot UI</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="turbo-refresh-method" content="morph">
+  <meta name="turbo-refresh-scroll" content="preserve">
+  <link rel="stylesheet" href="<%= stylesheet_path("application.css") %>">
+  <meta name="action-cable-url" content="ws://127.0.0.1:7070/cable" />
+  <script type="importmap" data-turbo-track="reload">
+    {
+      "imports": {
+        "application": "<%= javascript_path("application.js") %>",
+        "@hotwired/stimulus": "https://cdn.jsdelivr.net/npm/@hotwired/stimulus@3.2.2/+esm",
+        "@hotwired/turbo": "https://cdn.jsdelivr.net/npm/@hotwired/turbo@8.0.4/+esm",
+        "@rails/actioncable": "https://cdn.jsdelivr.net/npm/@rails/actioncable@7.1.3-4/+esm",
+        "controllers/refresh_controller": "<%= javascript_path("controllers/refresh_controller.js") %>",
+        "channels/consumer": "<%= javascript_path("channels/consumer.js") %>",
+        "channels": "<%= javascript_path("channels/index.js") %>",
+        "channels/refresh_channel": "<%= javascript_path("channels/refresh_channel.js") %>"
+      }
+    }
+  </script>
+  <script type="module">
+    import "application"
+  </script>
+</head>
+<%= yield %>
+</html>

data/lib/snapshot_ui/web/views/snapshots/index.html.erb

@@ -0,0 +1,60 @@
+<body id="snapshots_index" <%= refresh_controller %>>
+  <h1>Snapshots</h1>
+
+  <% if @grouped_by_test_class.empty? %>
+    <p>
+      In your integration tests, once a request has been made,
+      add <code>#take_screenshot</code>. Run the tests with <code>TAKE_SNAPSHOTS=1</code>, and the snapshot will appear here.
+    </p>
+
+    <p>Look below at an example integration test.</p>
+<pre>
+require "minitest/autorun"
+require "rack/test"
+require "application"
+<mark>require "snapshot_ui/test/minitest_helpers"</mark>
+
+class ApplicationTest < Minitest::Spec
+  include Rack::Test::Methods
+  <mark>include SnapshotUI::Test::MinitestHelpers</mark>
+
+  def app
+    @app ||= Application.new
+  end
+
+  it "renders the root page" do
+    get "/"
+
+    <mark>take_snapshot last_response</mark>
+
+    _(last_response.body).must_match("To see a world in a grain of sand...")
+  end
+end
+</pre>
+
+  <p>
+    To activate live updates for this page, execute the following command in your terminal.<br>
+  </p>
+  <pre>
+bundle exec snapshot_ui watch SNAPSHOT_DIRECTORY</pre>
+  <p>
+    where <code>SNAPSHOT_DIRECTORY</code> is a path to a directory that contains
+    snapshot UI data, e.g. <code>tmp/snapshot_ui</code>.
+  </p>
+  <% end %>
+
+  <% @grouped_by_test_class.each do |test_group, snapshots| %>
+  <h2><%= test_group %></h2>
+
+  <ul>
+    <% snapshots.each do |snapshot| %>
+      <li>
+        <a href="<%= snapshot_path(snapshot.slug) %>">
+          <%= snapshot.context.name %>
+          <%= if snapshot.context.take_snapshot_index > 0 then "(##{(snapshot.context.take_snapshot_index + 1)} in the same test)" end %>
+        </a>
+      </li>
+    <% end %>
+  </ul>
+<% end %>
+</body>

data/lib/snapshot_ui/web/views/snapshots/not_found.html.erb

@@ -0,0 +1,8 @@
+<body id="not_found" <%= refresh_controller %>>
+  <h1>Not Found</h1>
+
+  <p>
+    The snapshot you are looking for can't be found.
+    Go back to <a href="<%= root_path %>" style="text-decoration: underline; color: #666">a list of snapshots</a>.
+  </p>
+</body>

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

@@ -0,0 +1,3 @@
+<body id="snapshots_show" <%= refresh_controller %>>
+  <iframe id="raw" src="<%= raw_snapshot_path(@snapshot.slug) %>"></iframe>
+</body>

data/lib/snapshot_ui/web.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "erb"
+require "rack"
+require "rack/static"
+require_relative "web/application"
+
+module SnapshotUI
+  class Web
+    def self.call(env)
+      new.call(env)
+    end
+
+    def call(env)
+      app =
+        Rack::Builder.app do
+          use Rack::Static,
+            root: "#{File.dirname(__FILE__)}/web/assets",
+            urls: %w[/stylesheets /javascripts]
+
+          run Application.new
+        end
+
+      app.call(env)
+    end
+  end
+end

data/lib/snapshot_ui.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "snapshot_ui/snapshot"
+require_relative "snapshot_ui/configuration"
+
+module SnapshotUI
+  DEFAULT_CONFIGURATION = {
+    project_root_directory: ".",
+    storage_directory: "tmp/snapshot_ui"
+  }.freeze
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new(**DEFAULT_CONFIGURATION)
+  end
+
+  def self.snapshot_taking_enabled?
+    %w[1 true].include?(ENV["TAKE_SNAPSHOTS"])
+  end
+
+  def self.publish_snapshots_in_progress
+    Snapshot.publish_snapshots_in_progress
+  end
+
+  def self.clear_snapshots_in_progress
+    Snapshot.clear_snapshots_in_progress
+  end
+
+  def self.clear_snapshots
+    Snapshot.clear_snapshots
+  end
+end

data/snapshot_ui.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/snapshot_ui/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "snapshot_ui"
+  spec.version = SnapshotUI::VERSION
+  spec.authors = ["Tomaz Zlender"]
+  spec.email = ["tomaz@zlender.se"]
+
+  spec.summary = "Take snapshots of UI during testing for inspection in a browser."
+  spec.homepage = "https://github.com/tomazzlender/snapshot_ui"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = (`git ls-files | grep -E '^(lib)'`.split("\n") + %w[snapshot_ui.gemspec README.md CHANGELOG.md LICENSE.txt bin/snapshot_ui])
+  spec.executables = ["snapshot_ui"]
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "rack", "~> 3.0"
+  spec.add_dependency "listen", "~> 3.9"
+  spec.add_dependency "async-websocket", "~> 0.26"
+  spec.add_dependency "falcon", "~> 0.47"
+  spec.add_dependency "thor", "~> 1.3"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: snapshot_ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tomaz Zlender
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: async-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+- !ruby/object:Gem::Dependency
+  name: falcon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.47'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.47'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description:
+email:
+- tomaz@zlender.se
+executables:
+- snapshot_ui
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bin/snapshot_ui
+- lib/snapshot_ui.rb
+- lib/snapshot_ui/cli.rb
+- lib/snapshot_ui/cli/watcher.ru
+- lib/snapshot_ui/configuration.rb
+- lib/snapshot_ui/snapshot.rb
+- lib/snapshot_ui/snapshot/context.rb
+- lib/snapshot_ui/snapshot/storage.rb
+- lib/snapshot_ui/test/minitest_helpers.rb
+- lib/snapshot_ui/version.rb
+- lib/snapshot_ui/web.rb
+- lib/snapshot_ui/web/application.rb
+- lib/snapshot_ui/web/assets/javascripts/application.js
+- lib/snapshot_ui/web/assets/javascripts/channels/consumer.js
+- lib/snapshot_ui/web/assets/javascripts/channels/index.js
+- lib/snapshot_ui/web/assets/javascripts/channels/refresh_channel.js
+- lib/snapshot_ui/web/assets/javascripts/controllers/refresh_controller.js
+- lib/snapshot_ui/web/assets/stylesheets/application.css
+- lib/snapshot_ui/web/views/layout.html.erb
+- lib/snapshot_ui/web/views/snapshots/index.html.erb
+- lib/snapshot_ui/web/views/snapshots/not_found.html.erb
+- lib/snapshot_ui/web/views/snapshots/show.html.erb
+- snapshot_ui.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
+  changelog_uri: https://github.com/tomazzlender/snapshot_ui/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Take snapshots of UI during testing for inspection in a browser.
+test_files: []