snapshot_ui 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d083a6167cbd33d814565a34c6da82c32f920bf1fef6faa8171e1cf4bae1f86
-  data.tar.gz: 15f7d8346e5f192e4b8901760b64a1d91362507bb7adf91cbaed37e30a257613
+  metadata.gz: 69cf45167a5e8d9a8bd93ad9494521ef09da395e5224471de4023b93c926ede0
+  data.tar.gz: 75866a6374d237f1a526b15f563d287a713e6c6b8fa5f619fe811190f08c7ae5
 SHA512:
-  metadata.gz: 07c26236a62e772945eb5165e2552d2a278493acb7b65d4429f445e98b2401b5ee39acfe842b2a5c9787220b5444ac3f0a1ecab1f7e8cb0a7f87e2f01726b2b2
-  data.tar.gz: 5fa30fbda712efff8c596acca55ec3811fee661a6684fa7d34aee7a30b2032255e14930c8288f90e5e5fe15d82424cef66848a4860d560241d9631e57837b94a
+  metadata.gz: 954c2b1b6bc354e3d36e2bfe91237969ba7f3c3f0a7587681ad59783d38a6199d581a853cfbd33855e2180e3b7039b1ac81349d80ef52aed63ed21d749b8ad2f
+  data.tar.gz: 5681185428385eba65beefd0647b205b7ac2ce40bb67b1cf17a04764f086529db0af68df33c614152f416593da66f9157610988371e1ad13e3b9a93604187ec3

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-26
+
+- Snapshots now carry a type. "response" (the default) is unchanged; other gems can register additional types
+  and renderers (snapshot_ui-rails adds "mail"). Snapshots written before this are read as responses.
+
+- Live updates no longer need the `snapshot_ui live` command or a separate WebSocket server. The web UI polls a new
+  `version` endpoint (`<mount path>/version`, e.g. `/ui/snapshots/version`) once a second and refreshes the page
+  through Turbo when the published snapshots change.
+- Removed the `snapshot_ui` executable. Setting `config.live_websocket_url` now prints a deprecation warning and has
+  no effect.
+- Dropped the `falcon`, `async-websocket`, `listen` and `thor` dependencies, as well as the ActionCable JavaScript.
+- Turbo and Stimulus are now bundled with the gem instead of being loaded from a CDN, so the web UI works offline.
+- Publishing snapshots moves the previous ones aside instead of deleting them first, so the list of snapshots is never
+  briefly empty while a test run finishes.
+- Fixed `NoMethodError: undefined method 'rmtree'` on Ruby 4.0 by requiring `pathname` explicitly.
+- Works with minitest 6, which no longer discovers plugins on its own: requiring `snapshot_ui/test/minitest_helpers`
+  now registers the minitest plugin, so `--take-snapshots` and publishing at the end of a run keep working
+  (`Minitest.load :snapshot_ui` works as well).
+- Development dependencies updated; CI runs on Ruby 3.3 to 4.0 with both minitest 5 and 6.
+- Requires Ruby 3.3 or newer.
+- Works with Rack 2.2 as well as Rack 3, so it can be used in Rails 6.1 and 7.0 applications.
+- Terminal colours are only used when writing to a terminal, and not when `NO_COLOR` is set.
+- Snapshot files no longer record the class of the object passed to `take_snapshot`; it was never used.
+- `rake vendor:update` downloads the latest Turbo and Stimulus into the gem.
+- Pages for snapshots that can't be found respond with 404 instead of 200.
+- The Rack application serving the UI is built once instead of on every request.
+- A malformed snapshot file, or a URL whose slug would point outside the snapshots directory, now renders the not-found page instead of raising a 500 or reading an arbitrary file.
+
 ## [0.1.0] - 2024-06-09
 
 - Initial release

data/README.md

@@ -1,8 +1,149 @@
 # Snapshot UI
 
-Take snapshots of responses in integration tests, and display them in a browser.
+Take snapshots of responses in your integration tests and view them in a browser.
 
-Works with any kind of Rack application and minitest testing framework.
+When a test makes a request, add `take_snapshot` and Snapshot UI saves the response. Run your tests with snapshots
+enabled, then open the web interface to see exactly what each response rendered — useful for reviewing pages, emails,
+or API payloads produced during testing. Snapshots are only captured when you ask for them, so normal test runs are
+unaffected.
 
-> ℹ️ The Snapshot UI is the next generation of a similar library, [Snapshot Inspector](https://github.com/tomazzlender/snapshot_inspector).
-> It works with any kind of Rack application, not just Rails applications. Future development will take place here, and Snapshot Inspector will be eventually archived.
+Works with any Rack application and the minitest testing framework.
+
+**Using Rails?** The [`snapshot_ui-rails`](https://github.com/tomazzlender/snapshot_ui/tree/main/gems/snapshot_ui-rails)
+gem wires all of this into Rails so it works out of the
+box — no configuration, a `mount_snapshot_ui` route helper, and `take_snapshot` available in integration tests. If
+you're on Rails, read that gem's README instead; the rest of this one describes the plain-Rack setup it builds on.
+
+## Installation
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "snapshot_ui"
+end
+```
+
+```sh
+bundle install
+```
+
+## Setup
+
+### 1. Configure
+
+Tell Snapshot UI where your project lives, where to store snapshots, and the URL the web interface is served at:
+
+```ruby
+# e.g. config/snapshot_ui.rb, loaded by your app and your tests
+require "snapshot_ui"
+
+SnapshotUI.configure do |config|
+  config.storage_directory = File.expand_path("tmp/snapshot_ui", __dir__)
+  config.project_root_directory = File.expand_path(".", __dir__)
+  config.web_url = "http://localhost:3000/ui/snapshots"
+end
+```
+
+| Setting                  | What it is                                                                  |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `storage_directory`      | Where snapshot files are written (put it under `tmp`).                     |
+| `project_root_directory` | Your project root; used to build a snapshot's default name from its test.  |
+| `web_url`                | The URL the interface is mounted at; shown after a run and on the UI.      |
+
+You'll usually want the storage directory ignored by git:
+
+```
+# .gitignore
+/tmp/snapshot_ui/
+```
+
+### 2. Mount the web interface
+
+`SnapshotUI::Web` is a Rack application — mount it wherever your `web_url` points:
+
+```ruby
+# config.ru
+require "snapshot_ui/web"
+require_relative "config/snapshot_ui"
+
+map "/ui/snapshots" do
+  run SnapshotUI::Web
+end
+```
+
+The interface only displays snapshots captured during testing, so mount it where you view them (typically a local
+development server), not in production.
+
+### 3. Take snapshots in your tests
+
+Include the minitest helpers and call `take_snapshot` once a response is available:
+
+```ruby
+require "minitest/autorun"
+require "rack/test"
+require "snapshot_ui/test/minitest_helpers"
+
+class ApplicationTest < Minitest::Spec
+  include Rack::Test::Methods
+  include SnapshotUI::Test::MinitestHelpers
+
+  def app
+    @app ||= Application.new
+  end
+
+  it "renders the root page" do
+    get "/"
+
+    take_snapshot(last_response)
+
+    _(last_response.body).must_match("Hello")
+  end
+end
+```
+
+## Taking snapshots
+
+```ruby
+take_snapshot(snapshotee, title: nil, slug: nil)
+```
+
+* `snapshotee` — an object that responds to `#body` (such as `last_response`) or a plain `String` of HTML.
+* `title` — the name shown in the list. Defaults to a name derived from the test.
+* `slug` — a custom, stable URL for the snapshot (`/ui/snapshots/<slug>`); must be unique. Defaults to one derived
+  from where the snapshot was taken.
+
+You can take several snapshots in one test. `take_snapshot` does nothing unless snapshot-taking is enabled (see below),
+so it's safe to leave in your tests.
+
+## Running the tests and viewing snapshots
+
+Snapshots are captured only when you enable them, via the minitest flag or an environment variable:
+
+```sh
+ruby -Itest test/application_test.rb --take-snapshots
+# or
+TAKE_SNAPSHOTS=1 rake test
+```
+
+At the end of the run the URL to review the snapshots is printed. Start your application and open that URL (e.g.
+<http://localhost:3000/ui/snapshots>).
+
+The page refreshes itself as snapshots change: it polls a lightweight version endpoint and updates when a new test run
+publishes snapshots — no page reload, and no extra process or server to run. Everything the interface needs (styles
+and scripts) is served by the app itself, so it works offline.
+
+## How it works
+
+* `take_snapshot` records the response body under `storage_directory` while your tests run.
+* A minitest plugin (loaded when you require the helpers) publishes the run's snapshots at the end and prints the
+  review URL.
+* `SnapshotUI::Web` renders the list and each snapshot, and exposes a version endpoint the page polls for live updates.
+
+## Requirements
+
+* Ruby 3.3 or newer
+* Rack 2.2, or Rack 3
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/minitest/snapshot_ui_plugin.rb

@@ -4,6 +4,8 @@ require "minitest"
 module Minitest
   class << self
     def plugin_snapshot_ui_options(opts, _options)
+      return if opts.top.long.key?("take-snapshots")
+
       opts.on "--take-snapshots", "Take UI snapshots" do
         ENV["TAKE_SNAPSHOTS"] = "true"
       end
@@ -11,6 +13,9 @@ module Minitest
 
     def plugin_snapshot_ui_init(_options)
       return unless SnapshotUI.snapshot_taking_enabled?
+      # Minitest may list this plugin twice: registered below and discovered on its
+      # own (minitest 5) or loaded with `Minitest.load :snapshot_ui`. Set up once.
+      return if reporter.reporters.any? { |other| other.is_a?(SnapshotUIReporter) }
 
       SnapshotUI.exit_if_not_configured!
 
@@ -28,3 +33,7 @@ module Minitest
     end
   end
 end
+
+# Minitest 6 no longer discovers plugins on its own: requiring this file, which
+# `snapshot_ui/test/minitest_helpers` does, is what opts in.
+Minitest.register_plugin :snapshot_ui if Minitest.respond_to?(:register_plugin)

data/lib/snapshot_ui/colorize.rb

@@ -1,15 +1,26 @@
 # frozen_string_literal: true
 
 module SnapshotUI
+  # Colours terminal output, unless the output isn't a terminal or NO_COLOR is set.
   module Colorize
     module_function
 
-    def red(string)
-      "\e[31m#{string}\e[0m"
+    def red(string, io: $stdout)
+      colorize(string, 31, io: io)
     end
 
-    def green(string)
-      "\e[32m#{string}\e[0m"
+    def green(string, io: $stdout)
+      colorize(string, 32, io: io)
+    end
+
+    def colorize(string, code, io: $stdout)
+      return string unless enabled?(io)
+
+      "\e[#{code}m#{string}\e[0m"
+    end
+
+    def enabled?(io = $stdout)
+      io.respond_to?(:tty?) && io.tty? && ENV["NO_COLOR"].to_s.empty?
     end
   end
 end

data/lib/snapshot_ui/configuration.rb

@@ -5,13 +5,12 @@ require_relative "colorize"
 module SnapshotUI
   class Configuration
     attr_writer :storage_directory, :project_root_directory
-    attr_accessor :web_url, :live_websocket_url
+    attr_accessor :web_url
 
-    def initialize(project_root_directory:, storage_directory:, web_url:, live_websocket_url:)
+    def initialize(project_root_directory:, storage_directory:, web_url:)
       @project_root_directory = project_root_directory
       @storage_directory = storage_directory
       @web_url = web_url
-      @live_websocket_url = live_websocket_url
     end
 
     def storage_directory
@@ -22,6 +21,16 @@ module SnapshotUI
       Pathname.new(@project_root_directory) if @project_root_directory
     end
 
+    # Live updates no longer need a separate WebSocket server: the web UI polls
+    # for changes instead. Kept so that existing configuration files keep working.
+    def live_websocket_url=(_value)
+      warn(
+        "[snapshot_ui] `config.live_websocket_url` is deprecated and has no effect: " \
+        "the web UI now polls for snapshot updates. Remove it from your configuration.",
+        uplevel: 1
+      )
+    end
+
     def exit_if_not_configured!
       return unless project_root_directory.nil? || storage_directory.nil? || web_url.nil?
 

data/lib/snapshot_ui/snapshot/context.rb

@@ -3,7 +3,7 @@
 module SnapshotUI
   class Snapshot
     class Context
-      attr_reader :test_framework, :test_case_name, :method_name, :source_location, :take_snapshot_index
+      attr_reader :test_framework, :test_case_name, :method_name, :source_location, :take_snapshot_index, :metadata
 
       def initialize(context)
         @test_framework = context[:test_framework]
@@ -11,9 +11,12 @@ module SnapshotUI
         @method_name = context[:method_name]
         @source_location = context[:source_location]
         @take_snapshot_index = context[:take_snapshot_index]
+        @metadata = context[:metadata]
       end
 
       def to_slug
+        return metadata[:slug] if metadata[:slug]
+
         test_path_without_extension =
           source_location[0]
             .delete_suffix(File.extname(source_location[0]))

data/lib/snapshot_ui/snapshot/storage.rb

@@ -3,6 +3,8 @@
 module SnapshotUI
   class Snapshot
     class Storage
+      class InvalidKey < StandardError; end
+
       class << self
         def snapshots_directory
           SnapshotUI.configuration.storage_directory.join("snapshots")
@@ -12,6 +14,25 @@ module SnapshotUI
           SnapshotUI.configuration.storage_directory.join("in_progress")
         end
 
+        # Holds the previously published snapshots for the brief moment while the
+        # ones in progress take their place.
+        def previous_snapshots_directory
+          SnapshotUI.configuration.storage_directory.join("previous_snapshots")
+        end
+
+        # A token that changes whenever the published snapshots change.
+        #
+        # Publishing swaps in a freshly created directory (see
+        # .publish_snapshots_in_progress), so its inode identifies the published
+        # set even when the filesystem gives consecutive directories the same
+        # modification time.
+        def version
+          return "0" unless snapshots_directory.exist?
+
+          stat = snapshots_directory.stat
+          format("%d.%09d-%d", stat.mtime.to_i, stat.mtime.nsec, stat.ino)
+        end
+
         def write(key, value)
           file_path = to_file_path_for_writing(key)
           file_path.dirname.mkpath
@@ -22,6 +43,16 @@ module SnapshotUI
           to_file_path_for_reading(key).read
         end
 
+        # True when +key+ maps to a file inside the snapshots directory. A slug
+        # coming from the URL is untrusted, so paths escaping the directory
+        # (via "..", say) must be refused.
+        def readable?(key)
+          to_file_path_for_reading(key)
+          true
+        rescue InvalidKey
+          false
+        end
+
         def list
           Dir
             .glob("#{snapshots_directory}/**/*.{json}")
@@ -37,12 +68,19 @@ module SnapshotUI
           else
             snapshots_directory.rmtree
             in_progress_directory.rmtree
+            previous_snapshots_directory.rmtree if previous_snapshots_directory.exist?
           end
         end
 
+        # Replaces the published snapshots with the ones in progress. The published
+        # directory is moved aside rather than deleted first, so that there is
+        # practically no moment without published snapshots (the web UI polls for
+        # changes and would otherwise briefly show an empty list).
         def publish_snapshots_in_progress
-          clear(:snapshots)
+          previous_snapshots_directory.rmtree if previous_snapshots_directory.exist?
+          snapshots_directory.rename(previous_snapshots_directory) if snapshots_directory.exist?
           in_progress_directory.rename(snapshots_directory)
+          previous_snapshots_directory.rmtree if previous_snapshots_directory.exist?
         end
 
         private
@@ -52,11 +90,24 @@ module SnapshotUI
         end
 
         def to_file_path_for_reading(key)
-          snapshots_directory.join("#{key}.json")
+          within(snapshots_directory, key)
         end
 
         def to_file_path_for_writing(key)
-          in_progress_directory.join("#{key}.json")
+          within(in_progress_directory, key)
+        end
+
+        # Resolves +key+ to a "#{key}.json" file and ensures it stays inside
+        # +directory+, raising InvalidKey otherwise.
+        def within(directory, key)
+          directory = directory.expand_path
+          file_path = directory.join("#{key}.json").expand_path
+
+          unless file_path == directory || file_path.to_s.start_with?(directory.to_s + File::SEPARATOR)
+            raise InvalidKey, "#{key.inspect} is not a valid snapshot slug."
+          end
+
+          file_path
         end
       end
     end

data/lib/snapshot_ui/snapshot.rb

@@ -6,19 +6,27 @@ require "json"
 
 module SnapshotUI
   class Snapshot
-    attr_reader :slug, :context, :body
+    # The kind of thing a snapshot holds. "response" is the default and the only
+    # type the core gem knows how to capture; other types (e.g. "mail", added by
+    # snapshot_ui-rails) store their own data under +type_data+ and are rendered
+    # by a registered renderer (see SnapshotUI::Web).
+    DEFAULT_TYPE = "response"
+
+    attr_reader :slug, :context, :type, :type_data
 
     class NotFound < StandardError; end
 
-    def self.persist(snapshotee:, context:)
-      new.extract(snapshotee: snapshotee, context: context).persist
+    def self.persist(snapshotee:, context:, type: DEFAULT_TYPE, type_data: nil)
+      new.extract(snapshotee: snapshotee, context: context, type: type, type_data: type_data).persist
     end
 
     def self.find(slug)
       json = JSON.parse(Storage.read(slug), symbolize_names: true)
       new.from_json(json)
-    rescue Errno::ENOENT
+    rescue Errno::ENOENT, Errno::EISDIR, Storage::InvalidKey
       raise NotFound.new("Snapshot with a slug `#{slug}` can't be found.")
+    rescue JSON::ParserError => error
+      raise NotFound.new("Snapshot with a slug `#{slug}` can't be read: #{error.message}")
     end
 
     def self.grouped_by_test_case
@@ -40,6 +48,12 @@ module SnapshotUI
       Storage.clear
     end
 
+    # A token that changes whenever the published snapshots change. The web UI
+    # polls it to know when to refresh.
+    def self.version
+      Storage.version
+    end
+
     private_class_method def self.all
       snapshots = Storage.list.map { |slug| find(slug) }
 
@@ -52,9 +66,12 @@ module SnapshotUI
       end
     end
 
-    def extract(snapshotee:, context:)
-      @body = snapshotee.body
-      @snapshotee_class = snapshotee.class.to_s
+    # +type_data+ lets a caller supply the stored payload directly (used by
+    # snapshot_ui-rails for mail). When omitted, the response body is extracted
+    # from the snapshotee.
+    def extract(snapshotee:, context:, type: DEFAULT_TYPE, type_data: nil)
+      @type = type
+      @type_data = type_data || extract_response_type_data(snapshotee)
       @context = Context.new(context)
       self
     end
@@ -63,28 +80,52 @@ module SnapshotUI
       Storage.write(context.to_slug, JSON.pretty_generate(as_json))
     end
 
+    # The response body, for the default "response" type.
+    def body
+      type_data[:body]
+    end
+
+    def response?
+      type == DEFAULT_TYPE
+    end
+
     def as_json
       {
-        type_data: {
-          snapshotee_class: @snapshotee_class,
-          body: body
-        },
+        type: type,
+        type_data: type_data,
         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
+          take_snapshot_index: context.take_snapshot_index,
+          metadata: context.metadata
         },
         slug: context.to_slug
       }
     end
 
     def from_json(json)
-      @body = json[:type_data][:body]
+      # Snapshots written before types existed have no :type and their body sits
+      # directly under :type_data — treat them as responses.
+      @type = json[:type] || DEFAULT_TYPE
+      @type_data = json[:type_data] || {}
       @context = Context.new(json[:context])
       @slug = json[:slug]
       self
     end
+
+    private
+
+    def extract_response_type_data(snapshotee)
+      body =
+        if snapshotee.respond_to?(:body)
+          snapshotee.body
+        elsif snapshotee.is_a?(String)
+          snapshotee
+        end
+
+      {body: body}
+    end
   end
 end

data/lib/snapshot_ui/test/minitest_helpers.rb

@@ -2,18 +2,32 @@
 
 require_relative "../../snapshot_ui"
 require_relative "../snapshot"
+require_relative "../../minitest/snapshot_ui_plugin"
 
 module SnapshotUI
   module Test
     module MinitestHelpers
-      def take_snapshot(snapshotee)
+      # Takes a snapshot of a given +snapshotee+, with an optional +title+ metadata.
+      #
+      # A +snapshotee+ can be an object that responds to +#body+ or of class +String+.
+      #
+      # +take_snapshot+ needs to be called after the +snapshotee+ object becomes available
+      # for inspection in the lifecycle of the test. You can take one or more snapshots in a single test case.
+      #
+      # @param snapshotee [Object, String] an +Object+ that responds to the +#body+ method that returns a +String+, or a +String+
+      # @param title [String, nil] (optional) a title of the snapshotee. When not provided the title will be generated from a test description.
+      # @param slug [String, nil] (optional) a custom URL path for the snapshot (e.g. +/ui/snapshots/__SLUG__+). +slug+ must be unique across all snapshots.
+      #   If not provided, the slug will be automatically generated based on where the snapshot was taken.
+      # @return SnapshotUI::Snapshot
+      def take_snapshot(snapshotee, title: nil, slug: nil)
         return unless SnapshotUI.snapshot_taking_enabled?
 
-        unless snapshotee.respond_to?(:body)
+        unless snapshotee.respond_to?(:body) || snapshotee.is_a?(String)
           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)
+            "#take_snapshot only accepts an argument that responds to a method `#body` " \
+            "or an argument that is of type `String`. " \
+            "You provided an argument of type `#{snapshotee.class}` that does not respond to `#body` nor is a `String`."
+          raise ArgumentError, message
         end
 
         SnapshotUI.exit_if_not_configured!
@@ -27,7 +41,8 @@ module SnapshotUI
             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
+            take_snapshot_index: _take_snapshot_counter - 1,
+            metadata: {title: title, slug: slug}
           }
         )
       end

data/lib/snapshot_ui/version.rb

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