snapshot_inspector 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 571c9cf5b244dabba8c02e82927bef51de92ee803425cdaba8d959f6c326680d
+  data.tar.gz: 568238234e8cfb20cc5cfd2662fb81c303b35a74f6baeb44dfbea4bfe5af6144
+SHA512:
+  metadata.gz: 0feb058a79241aff473b9111e6c1ee85c6e1e1806c08614f592f1714ca6eba05040db9b5a93fff255d8217b5a3e399803ca082047abe1b1aaeacb65506a805bc
+  data.tar.gz: 497dff7826caf2b15c86fc904401e27d77c65a85af85bb0a55720ab0ea4929fc3cfbef11d4a30f2e064afb647888939cdc56c03c4424dcef0a00bd906715944f

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2023 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,227 @@
+# Snapshot Inspector
+
+Take snapshots of responses and mail messages while testing, and inspect them in a browser. A Ruby on Rails engine. Works with the default Ruby on Rails testing framework and RSpec.
+
+> **NOTICE**
+>
+> The library is actively used during the development of apps running in production, however, treat it as beta software.
+>
+> So far it's been tested on the latest version of Ruby on Rails (7.0.x) and Ruby (> 3.1.x).
+
+A sneak peek into what the library is about:
+
+![A list of snapshots](doc/snapshots_index.png)
+
+## Rationale
+
+Imagine that I'm working on a website for a local urban gardening community. It's a server side rendered
+app, using sprinkles of JavaScript on top.
+
+While writing view related tests, like integration or mailer tests, I wish to see how a
+response body (or mail message body) looks like in a browser for a given test setup.
+
+It's quite easy to do that in some cases. Let's say I'm writing an integration test for a form for signing
+up gardeners to the garden's waiting list.
+I can simply start the development server, go to a URL of the page that displays the form
+and I can see and inspect the rendered HTML that exactly reflects the response body I'm dealing
+with in the integration test.
+
+Now imagine I'm writing an integration test for a success page that is displayed after a new gardener fills
+in the form and submits it. Or imagine, that I'm writing a test for a membership details page of
+an expired membership that is visible only to a specific registered gardener.
+
+In such cases, I need to put much more effort into recreating the state in a browser, while I already put effort
+into creating the test setup in the first place.
+
+In JavaScript heavy applications it's natural to use system tests (or similar) for such purposes. It's possible
+to [take screenshots](https://api.rubyonrails.org/classes/ActionDispatch/SystemTesting/TestHelpers/ScreenshotHelper.html#method-i-take_screenshot),
+and even save the HTML of the page being screenshotted for later inspection.
+
+However, in the world of server rendered applications with sprinkles of JavaScript on top, the integration tests
+(where a system under test deals with controller/model/view) can cover a lot of the testing needs that
+in JavaScript heavy context can only be fulfilled with system tests (javascript/controller/model/view
+running via a browser).
+
+It would be convenient to use integration tests for such cases since they are much faster to run. However,
+writing assertions against HTML can become quickly cumbersome because of the reasons explained above.
+
+Alternatively, I could use a debugger to inspect the state of a response body through a shell,
+but that makes me feel like peeking through a peephole compared to inspecting HTML with a Web Inspector.
+
+Enter **Snapshot Inspector**.
+
+All that is keeping me away from using Web Inspector for such purposes is one drop of a line
+
+```ruby
+take_snapshot response
+```
+
+after a request is made in a test and a response object has been populated.
+
+Take a look at an example of a rendered response snapshot of a thank you page in a browser:
+
+![Response snapshot example: thank you page](doc/response_snapshot_example_thank_you_page.png)
+
+### Exploring a new codebase
+
+Imagine you are new to a codebase (or it's been months since you've looked at it) and you
+are investigating a reported UI bug. You know to which route
+the bug is related to, but since you haven't worked in that area of the codebase, it's not clear how
+to recreate the state of the application in a browser to replicate the bug. Maybe you don't even know
+what the UI related to the route looks like since you haven't managed to click around
+through all the permutations of the state of the whole application.
+
+With Snapshot Inspector, you can simply drop a bunch of `take_snapshot response` in all the tests
+of the related controller, and you'll get a pretty good picture of how the UI looks like.
+That might be all you need to do to replicate the bug. Or you can create a new test that
+will replicate the state of the UI the bug reporter was in, and generate snapshots as you explore.
+
+### A case for taking snapshots of mail messages
+
+There is an established practice of using [Action Mailer Previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails).
+
+Imagine that I'm working on a mailer that I wish to send to a gardener that has signed up for the
+waiting list.
+
+Without Snapshot Inspector I would write the mailer test and the mailer preview. I would need to
+do the same setup of the mailer state twice to keep the parity between the two.
+
+With Snapshot Inspector, I can simply drop one line of code into the mailer test and avoid writing
+the mailer preview altogether.
+
+```ruby
+take_snapshot mail
+```
+
+An example of a rendered mail message snapshot of a thank you email in a browser:
+
+![A mail message snapshot](doc/mail_snapshot_example_1.png)
+
+The duplicated effort between mailer previews and tests is gone. I can look and inspect all
+interesting variations of a mailer that I'm already testing anyhow, without putting any effort into
+creating previews.
+
+### Summary
+
+Taking snapshots is to integration and mailer tests what taking screenshots is to system tests.
+
+### The added bonus: UI library
+
+While not the primary goal of the Snapshot Inspector, a side effect of taking snapshots is a library
+of the UI surface area of the application.
+
+One of the benefits of automated tests with well written test descriptions is to document the
+behavior of a system under test. Since the output of a system under test in the case of integration
+and mailer tests is a renderable UI, if we take snapshots of all tested responses and emails, we
+consequently generate a browsable UI library of the whole application.
+
+Of course, that only applies to applications that are heavy on the server side rendering and use
+a tiny bit of JavaScript on top. In the world of [Hotwire](https://hotwired.dev), I imagine there can
+be quite a few applications like that.
+
+## Installation
+
+Add the gem to your application's Gemfile under `:development` and `:test` groups. Snapshots are taken in the test environment and inspected in the development environment.
+
+```ruby
+group [:development, :test] do
+  gem "snapshot_inspector"
+end
+```
+
+Then execute:
+```bash
+bundle install
+```
+
+## Usage
+
+Take snapshots by placing a helper method `take_snapshot` in tests that deal with instances of `ActionDispatch::TestResponse` or `ActionMailer::MessageDelivery`.
+For example, in controller, integration, or mailer tests.
+
+For the best experience, take snapshots before assertions. That way it is possible to inspect them as part of the investigation of why an assertion failed.
+
+An example from an integration test:
+
+```ruby
+test "should get index" do
+  get root_path
+  
+  take_snapshot response # <-- takes a snapshot of the response (an instance of ActionDispatch::TestResponse)
+  
+  assert_response :success
+end
+```
+
+An example of a mailer test:
+
+```ruby
+test "welcome mail" do
+  mail = NotifierMailer.welcome
+
+  take_snapshot mail # <-- takes a snapshot of the mail (an instance of ActionMailer::MessageDelivery)
+
+  assert_equal "Welcome!", mail.subject
+end
+```
+
+When the tests are run, to avoid the performance overhead, the snapshot taking is skipped by default.
+To enable them, run the tests with a flag `--take-snapshots`. The flag works with the default testing framework only.
+
+```bash
+bin/rails test --take-snapshots
+TAKE_SNAPSHOTS=1 bin/rails test
+```
+
+If you are using RSpec, use the environment variable `TAKE_SNAPSHOTS`. The variable also works with the default testing framework.
+
+```bash
+TAKE_SNAPSHOTS=1 bin/rspec
+```
+
+Then start your local server and visit http://localhost:300/rails/snapshots.
+
+### Live Reloading
+
+If you wish for the snapshots in a browser to live reload whenever a test run is completed,
+Snapshot Inspector works out of the box with [hotwire-livereload](https://github.com/kirillplatonov/hotwire-livereload).
+Besides the general installation instructions, add the following lines into `development.rb`.
+
+```ruby
+config.hotwire_livereload.listen_paths << SnapshotInspector::Storage.snapshots_directory
+config.hotwire_livereload.force_reload_paths << SnapshotInspector::Storage.snapshots_directory
+```
+
+## How it works
+
+- By default, snapshot taking is skipped to preserve the performance of a test suit in CI and similar environments.
+- Snapshots are stored in `tmp/snapshot_inspector` folder.
+- For every test run, existing snapshots are cleared and new snapshots are generated.
+- The testing framework (Rails' default or RSpec) is autodetected.
+- By default, when a snapshot is rendered all JavaScript related tags (`<script>` and `<link>`) are removed
+  from the HTML. That way we can pretty closely simulate how a page looks like with JavaScript turned off
+  without going into the trouble of turning it off in a browser, and still taking advantage of live reloading.
+
+## Unresolved Challenges
+
+Imagine that you are building a page with form. You wish to test drive the development while at the
+same time use the Snapshot Inspector to see how the page looks after every change.
+
+It takes more time to make a change in the view, run the test (and generate a snapshot),
+and reload the browser than to run a development server and use live reloading directly.
+Even with live reloading turned on and using things like [guard](https://github.com/guard/guard).
+
+It would be nice to find a way to speed up the tests. Perhaps there is a way to run them
+interactively from a console and to run something similar to `reload!` after every change? Please reach out
+via GitHub Issues if you have suggestions.
+
+## Contributing
+
+- Fork the repo
+- Create your feature branch (git checkout -b my-new-feature)
+- Commit your changes (git commit -am 'Add some feature')
+- Push to the branch (git push origin my-new-feature)
+- Create a new Pull Request
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/snapshot_inspector/manifest.js

@@ -0,0 +1,2 @@
+//= link_directory ../../stylesheets/snapshot_inspector .css
+//= link_tree ../../javascripts/snapshot_inspector .js

data/app/assets/javascripts/snapshot_inspector/application.js

@@ -0,0 +1 @@
+import "controllers"

data/app/assets/stylesheets/snapshot_inspector/application.css

@@ -0,0 +1,33 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */
+
+html {
+  height: 100%;
+}
+
+body {
+  background-color: #fff;
+  color: #333;
+  margin: 0;
+  padding: 0;
+  height: 100%;
+}
+
+body, p, ol, ul, td {
+  font-family: helvetica, verdana, arial, sans-serif;
+  font-size:   20px;
+  line-height: 1.7em;
+}

data/app/assets/stylesheets/snapshot_inspector/snapshots/mail.css

@@ -0,0 +1,48 @@
+body#mail_show {
+  display: flex;
+  flex-flow: column;
+  height: 100%;
+}
+
+body#mail_show header {
+  width: 100%;
+  padding: 10px 0 0 0;
+  margin: 0;
+  background: white;
+  font: 12px "Lucida Grande", sans-serif;
+  border-bottom: 1px solid #dedede;
+  overflow: hidden;
+}
+
+body#mail_show dl {
+  margin: 0 0 10px 0;
+  padding: 0;
+}
+
+body#mail_show dt {
+  width: 80px;
+  padding: 1px;
+  float: left;
+  clear: left;
+  text-align: right;
+  color: #7f7f7f;
+}
+
+body#mail_show dd {
+  margin-left: 90px; /* 80px + 10px */
+  padding: 1px;
+}
+
+body#mail_show dd:empty:before {
+  content: "\00a0"; //  
+}
+
+body#mail_show td {
+  font: 12px "Lucida Grande", sans-serif;
+}
+
+body#mail_show iframe {
+  border: 0;
+  width: 100%;
+  flex: 1 1 auto;
+}

data/app/assets/stylesheets/snapshot_inspector/snapshots/not_found.css

@@ -0,0 +1,15 @@
+main#not_found {
+  padding: 100px;
+}
+
+main#not_found h1 {
+  margin: 0;
+  font-size: 30px;
+  font-weight: normal;
+  color: #666666;
+}
+
+main#not_found p {
+  margin: 18px 0 0;
+  color: #666666;
+}

data/app/assets/stylesheets/snapshot_inspector/snapshots/response.css

@@ -0,0 +1,9 @@
+body#response_show {
+  overflow: hidden;
+}
+
+body#response_show iframe#body {
+  border: 0;
+  width: 100%;
+  height: 100%;
+}

data/app/assets/stylesheets/snapshot_inspector/snapshots.css

@@ -0,0 +1,73 @@
+body#snapshots_index main {
+  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 pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+  white-space: pre-wrap;
+}
+
+body#snapshots_index a { color: #000; text-decoration: none; }
+body#snapshots_index a:hover { text-decoration: underline; }
+
+body#snapshots_index form.enable_javascript {
+  margin-top: 20px;
+}
+
+body#snapshots_index form.enable_javascript input {
+  transform: scale(1.4);
+  cursor: pointer;
+}
+
+body#snapshots_index form.enable_javascript label {
+  cursor: pointer;
+  user-select: none;
+  font-size: 19px;
+  display: flex;
+  align-items: center;
+}
+
+body#snapshots_index form.enable_javascript label span {
+  margin: 0 0 0 10px;
+  color: #666666;
+}
+
+@media (prefers-color-scheme: dark) {
+  body#snapshots_index {
+    background-color: #222;
+    color: #ececec;
+  }
+
+  body#snapshots_index pre {
+    background-color: #333;
+  }
+
+  body#snapshots_index a { color: #fff; }
+  body#snapshots_index a:hover { color: #fff; text-decoration: underline; }
+}

data/app/controllers/snapshot_inspector/application_controller.rb

@@ -0,0 +1,14 @@
+module SnapshotInspector
+  class ApplicationController < ActionController::Base
+    helper SnapshotInspector::Engine.helpers
+
+    content_security_policy(false)
+
+    private
+
+    def snapshot_not_found(error)
+      @error = error
+      render "snapshot_inspector/snapshots/not_found", status: 404
+    end
+  end
+end

data/app/controllers/snapshot_inspector/snapshots/mail_controller.rb

@@ -0,0 +1,57 @@
+module SnapshotInspector
+  class Snapshots::MailController < ApplicationController
+    helper_method :part_query
+
+    rescue_from Snapshot::NotFound, with: :snapshot_not_found
+
+    def show
+      @snapshot = Snapshot.find(params[:slug])
+      @email = @snapshot.message
+
+      if params[:format] == "eml"
+        send_data @email.to_s, filename: "#{@snapshot.mailer_name}##{@snapshot.action_name}.eml"
+      else
+        @part = find_preferred_part(request.format, Mime[:html], Mime[:text])
+        render :show, formats: [:html]
+      end
+    end
+
+    def raw
+      @snapshot = Snapshot.find(params[:slug])
+      @email = @snapshot.message
+      part_type = Mime::Type.lookup(params[:part] || "text/html")
+
+      if (part = find_part(part_type))
+        response.content_type = part_type
+        render plain: part.respond_to?(:decoded) ? part.decoded : part
+      else
+        raise AbstractController::ActionNotFound, "Email part `#{part_type}` not found in a snapshot #{@snapshot.context.test_case_name}##{@snapshot.context.method_name}"
+      end
+    end
+
+    private
+
+    def find_preferred_part(*formats)
+      formats.each do |format|
+        if (part = @email.find_first_mime_type(format))
+          return part
+        end
+      end
+      if formats.any? { |f| @email.mime_type == f }
+        @email
+      end
+    end
+
+    def find_part(format)
+      if (part = @email.find_first_mime_type(format))
+        part
+      elsif @email.mime_type == format
+        @email
+      end
+    end
+
+    def part_query(mime_type)
+      request.query_parameters.merge(part: mime_type).to_query
+    end
+  end
+end

data/app/controllers/snapshot_inspector/snapshots/response_controller.rb

@@ -0,0 +1,15 @@
+module SnapshotInspector
+  class Snapshots::ResponseController < ApplicationController
+    rescue_from Snapshot::NotFound, with: :snapshot_not_found
+
+    layout false, only: [:raw]
+
+    def show
+      @snapshot = Snapshot.find(params[:slug])
+    end
+
+    def raw
+      @snapshot = Snapshot.find(params[:slug])
+    end
+  end
+end

data/app/controllers/snapshot_inspector/snapshots_controller.rb

@@ -0,0 +1,7 @@
+module SnapshotInspector
+  class SnapshotsController < ApplicationController
+    def index
+      @grouped_by_test_class = Snapshot.grouped_by_test_case
+    end
+  end
+end

data/app/helpers/snapshot_inspector/application_helper.rb

@@ -0,0 +1,15 @@
+module SnapshotInspector
+  module ApplicationHelper
+    def snapshot_inspector_importmap_tags(entry_point = "application", shim: true)
+      safe_join(
+        [
+          javascript_inline_importmap_tag(SnapshotInspector.configuration.importmap.to_json(resolver: self)),
+          javascript_importmap_module_preload_tags(SnapshotInspector.configuration.importmap),
+          (javascript_importmap_shim_nonce_configuration_tag if shim),
+          (javascript_importmap_shim_tag if shim),
+          javascript_import_module_tag(entry_point)
+        ].compact, "\n"
+      )
+    end
+  end
+end

data/app/helpers/snapshot_inspector/snapshots_helper.rb

@@ -0,0 +1,37 @@
+module SnapshotInspector
+  module SnapshotsHelper
+    def prepare_for_render(body, enable_javascript:)
+      prepared =
+        if enable_javascript == "true"
+          body
+        else
+          remove_traces_of_javascript(body)
+        end
+
+      prepared.html_safe
+    end
+
+    def remove_traces_of_javascript(html)
+      doc = Nokogiri.HTML(html)
+
+      doc.css("script").each do |element|
+        element.replace("")
+      end
+
+      doc.css('link[href$=".js"]').each do |element|
+        element.replace("")
+      end
+
+      doc.to_html
+    end
+
+    def self.snapshot_path(snapshot, enable_javascript:)
+      case snapshot.type
+      when "mail"
+        SnapshotInspector::Engine.routes.url_helpers.mail_snapshot_path(slug: snapshot.slug)
+      when "response"
+        SnapshotInspector::Engine.routes.url_helpers.response_snapshot_path(slug: snapshot.slug, enable_javascript: enable_javascript)
+      end
+    end
+  end
+end

data/app/mailers/snapshot_inspector/application_mailer.rb

@@ -0,0 +1,6 @@
+module SnapshotInspector
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

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

@@ -0,0 +1,49 @@
+module SnapshotInspector
+  class Snapshot
+    class Context
+      class_attribute :registry, default: {}, instance_writer: false, instance_predicate: false
+
+      def self.test_framework(name)
+        registry[name] = self
+      end
+
+      def self.extract(context)
+        record = registry[context[:test_framework]].new
+        record.extract(context)
+        record
+      end
+
+      def self.from_hash(hash)
+        record = registry[hash[:test_framework].to_sym].new
+        record.from_hash(hash)
+        record
+      end
+
+      # @private
+      def extract(_context)
+        raise "Implement in a child class."
+      end
+
+      # @private
+      def from_hash(_hash)
+        raise "Implement in a child class."
+      end
+
+      def to_slug
+        raise "Implement in a child class."
+      end
+
+      def name
+        raise "Implement in a child class."
+      end
+
+      def test_group
+        raise "Implement in a child class."
+      end
+
+      def order_index
+        raise "Implement in a child class."
+      end
+    end
+  end
+end