dommy-rails 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62f4ed9c4e72fad6e37235d7831a24fed0f941d5832be21a9469972f04cc40d8
-  data.tar.gz: dc94f1a8349a01b22819c66602d38a9795670f917e5b55aeba313eddaafea918
+  metadata.gz: 50d6da0920fbd92140fcbba4bb15ca4a0b3290827746785c8d5c46e55caaab0c
+  data.tar.gz: d9788d25d33b9d74b7bc7ff5e06e15b754391d0ab841de86f870282ca22dd6cb
 SHA512:
-  metadata.gz: 2ed06d6d5570260669b7cb7626566aeeaed03f1771a4afc0f0c99377079e68a15f0283068f6b00f749a62a5cf92d16adbaa6849f424f9af22a08ee07f88084ec
-  data.tar.gz: 01e9d6f47a22a8a60dac0a88efe08835b5be3d0fb0c2fdc28fd0d30c387aaab6fdfa3f3489e20c35ce7b4875c6aed531c314a3771cf4fa731a01d33bb426e717
+  metadata.gz: cbe6783f0111e3034bd2c26adb2a947f0b43337db68911679af0cdc7892a7a387a082f300c36fca0448b773b0b4cb509a77611fde462249207616c3d86985966
+  data.tar.gz: f52246bc241b4a4e67e1fc3ac0fa3cc194bf42895c484291e38f98aedb00fe17cc653aee5482b0470622b357102d9b7facc08de1b59414f75a5499a839756624

data/README.md

@@ -108,6 +108,35 @@ expect(mail).to have_html_text("Confirm your account")
 expect(mail).to have_plain_text("Welcome")
 ```
 
+## Failure traces in CI
+
+A failed browser test saves a self-contained bundle under
+`tmp/dommy/failures/<example-slug>/` — the page HTML, the readable trace,
+and a machine-readable `trace.ndjson` (with Rails-internals spans:
+controller, SQL, renders, jobs, mail) that the standalone `dommylizer`
+viewer opens. The failure output prints the exact path and command.
+
+To keep them from CI runs, upload the directory as an artifact:
+
+```yaml
+# GitHub Actions
+- uses: actions/upload-artifact@v4
+  if: failure()
+  with:
+    name: dommy-traces
+    path: tmp/dommy/failures/
+```
+
+Then download the artifact locally and run
+`dommylizer tmp/dommy/failures/<example>/trace.ndjson`.
+
+SQL bind values are excluded from traces by default. To include them
+(masked through the same sensitive-key filter as form params):
+
+```ruby
+Dommy::Rails::TraceInstrumentation.install!(binds: true)
+```
+
 ## URL normalization
 
 `have_link(href:)`, `have_form(action:)`, and their Minitest counterparts

data/lib/dommy/rails/browser_spec.rb

@@ -25,8 +25,14 @@ module Dommy
       def self.included(base)
         if base.respond_to?(:after)
           base.after do |example|
-            dommy_browser_after(failed: example.exception ? true : false,
+            dir = dommy_browser_after(failed: example.exception ? true : false,
               label: example.full_description, exception: example.exception)
+            # Point the failure output at the saved bundle and the one command
+            # that opens it in the standalone viewer.
+            if dir && example.respond_to?(:metadata)
+              (example.metadata[:extra_failure_lines] ||= []) <<
+                "Trace bundle: #{dir}" << "View it with: dommylizer #{::File.join(dir, "trace.ndjson")}"
+            end
           end
         end
       end
@@ -34,18 +40,21 @@ module Dommy
       # Minitest teardown hook (no-op outside Minitest).
       def after_teardown
         failures = respond_to?(:failures) ? self.failures : []
-        dommy_browser_after(failed: !failures.empty?, label: (name if respond_to?(:name)),
+        dir = dommy_browser_after(failed: !failures.empty?, label: (name if respond_to?(:name)),
           exception: failures.first)
+        warn "Trace bundle: #{dir}\nView it with: dommylizer #{::File.join(dir, "trace.ndjson")}" if dir
       ensure
         super if defined?(super)
       end
 
       # On a failed example, write debugging artifacts (page HTML + trace +
       # visible text) before disposing, then run the normal teardown. Shared by
-      # the RSpec and Minitest hooks.
+      # the RSpec and Minitest hooks. Returns the artifacts directory (nil when
+      # nothing was saved).
       def dommy_browser_after(failed:, label: nil, exception: nil)
-        dommy_save_failure_artifacts(label, exception: exception) if failed && browser_started?
+        dir = (dommy_save_failure_artifacts(label, exception: exception) if failed && browser_started?)
         dommy_browser_teardown
+        dir
       end
 
       # The Rack app the browser drives. Defaults to the Rails application;
@@ -63,6 +72,9 @@ module Dommy
       def browser
         @dommy_browser ||= begin
           require "dommy/js/quickjs/rack"
+          # Rails-internals spans (controller/SQL/render/job/mail) on every
+          # traced request; idempotent, no-op without ActiveSupport.
+          Dommy::Rails::TraceInstrumentation.install!
           ::Dommy::Rack::Session.new(dommy_browser_app, javascript: true, trace: true, trace_dom: true,
             trace_snapshots: true)
         end
@@ -89,7 +101,7 @@ module Dommy
         return unless browser_started?
 
         pending = browser.js_errors[(@dommy_browser_acked || 0)..] || []
-        browser.dispose_js
+        browser.dispose
         @dommy_browser = nil
         return if @dommy_allow_js_errors || pending.empty?
 

data/lib/dommy/rails/trace_instrumentation.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Rails
+    # Fills the inside of a traced request: subscribes to the Rails
+    # ActiveSupport::Notifications topics (controller action, SQL, template /
+    # partial rendering, job enqueue/perform, mail delivery) and buffers each
+    # finished event as a completed span on the trace whose request is in
+    # flight — Dommy calls the app synchronously, so
+    # `Thread.current[:__dommy_active_trace__]` (set by Dommy::Rack::Trace
+    # around the Rack call) IS the request's trace.
+    #
+    # Installed automatically when a BrowserSpec test boots its browser;
+    # callable directly (idempotent) from a suite hook too:
+    #
+    #   Dommy::Rails::TraceInstrumentation.install!
+    #   Dommy::Rails::TraceInstrumentation.install!(binds: true)
+    #
+    # SQL bind values are excluded by default; `binds: true` includes them as
+    # {name => value}, masked through the same sensitive-key filter the trace
+    # applies to form params (password/token/… become [FILTERED]).
+    module TraceInstrumentation
+      TOPICS = {
+        "process_action.action_controller" => :controller,
+        "sql.active_record" => :db,
+        "render_template.action_view" => :render,
+        "render_partial.action_view" => :render,
+        "enqueue.active_job" => :job,
+        "perform.active_job" => :job,
+        "deliver.action_mailer" => :mail,
+      }.freeze
+
+      # Statement names carrying no application information.
+      SKIPPED_SQL_NAMES = ["SCHEMA", "TRANSACTION"].freeze
+
+      module_function
+
+      # `binds:` is applied on EVERY call, including calls that find the
+      # subscriptions already installed, so a suite hook can turn SQL bind
+      # recording on — and back off — without a way to un-subscribe.
+      def install!(binds: false)
+        @include_binds = binds
+        return false if @installed
+        return false unless defined?(::ActiveSupport::Notifications)
+        return false unless ::ActiveSupport::Notifications.respond_to?(:monotonic_subscribe)
+
+        TOPICS.each do |topic, kind|
+          ::ActiveSupport::Notifications.monotonic_subscribe(topic) do |_name, started, finished, _id, payload|
+            record(kind, topic, (finished - started) * 1000.0, payload)
+          end
+        end
+        @installed = true
+      end
+
+      def record(kind, topic, duration_ms, payload)
+        trace = Thread.current[active_trace_key]
+        return unless trace.respond_to?(:__internal_record_span__)
+
+        span = build_span(kind, topic, payload)
+        return unless span
+
+        trace.__internal_record_span__(kind: kind, label: span[:label],
+          duration_ms: duration_ms, data: span[:data])
+      rescue StandardError
+        nil # instrumentation must never break the request
+      end
+
+      def build_span(kind, topic, payload)
+        case kind
+        when :controller
+          {label: "#{payload[:controller]}##{payload[:action]}",
+           data: {format: payload[:format].to_s, status: payload[:status]}.compact}
+        when :db then db_span(payload)
+        when :render
+          identifier = payload[:identifier].to_s
+          # The app-relative template path reads better than the absolute one.
+          label = identifier.sub(%r{\A.*/app/views/}, "")
+          {label: "#{topic.start_with?("render_partial") ? "partial" : "template"} #{label}",
+           data: nil}
+        when :job
+          job = payload[:job]
+          {label: "#{topic.start_with?("enqueue") ? "enqueue" : "perform"} #{job.class.name}",
+           data: ({queue: job.queue_name.to_s} if job.respond_to?(:queue_name))}
+        when :mail
+          {label: payload[:mailer].to_s, data: nil}
+        end
+      end
+
+      def db_span(payload)
+        name = payload[:name].to_s
+        return nil if SKIPPED_SQL_NAMES.include?(name)
+
+        data = {sql: payload[:sql].to_s}
+        if @include_binds && (masked = masked_binds(payload))
+          data[:binds] = masked
+        end
+        {label: name.empty? ? "SQL" : name, data: data}
+      end
+
+      # {attribute name => type-cast value}, sensitive keys masked with the
+      # in-flight trace's OWN filter (so custom filter keys apply to binds
+      # exactly as to form params), falling back to the shared default. nil
+      # when the payload carries no usable binds.
+      def masked_binds(payload)
+        names = Array(payload[:binds]).map { |b| b.respond_to?(:name) ? b.name.to_s : b.to_s }
+        values = Array(type_casted_binds(payload[:type_casted_binds]))
+        return nil if names.empty? || names.length != values.length
+
+        bind_filter.form_params(names.zip(values))
+      end
+
+      # Some adapters/versions publish `type_casted_binds` as a callable that
+      # defers the (potentially expensive) casting until a subscriber asks for
+      # it — exactly what ActiveRecord::LogSubscriber unwraps before reading it.
+      # Without this, a single-bind statement would record the Proc ITSELF as
+      # the bind value, and every other statement would silently drop its binds
+      # on the names/values length check.
+      def type_casted_binds(casted_binds)
+        casted_binds.respond_to?(:call) ? casted_binds.call : casted_binds
+      end
+
+      def bind_filter
+        trace = Thread.current[active_trace_key]
+        return trace.__internal_param_filter__ if trace.respond_to?(:__internal_param_filter__)
+
+        @default_filter ||= Dommy::Rack::Trace::ParamFilter.new(Dommy::Rack::Trace::ParamFilter::DEFAULT)
+      end
+
+      # The Trace owns the thread-local's name; read it from there when
+      # dommy-rack is loaded so the two can never drift apart.
+      def active_trace_key
+        if defined?(::Dommy::Rack::Trace::TRACE_THREAD_KEY)
+          ::Dommy::Rack::Trace::TRACE_THREAD_KEY
+        else
+          :__dommy_active_trace__
+        end
+      end
+    end
+  end
+end

data/lib/dommy/rails/version.rb

@@ -1,5 +1,5 @@
 module Dommy
   module Rails
-    VERSION = "0.9.0"
+    VERSION = "0.11.0"
   end
 end

data/lib/dommy/rails.rb

@@ -10,6 +10,7 @@ require_relative "rails/mail_part"
 require_relative "rails/match_target"
 require_relative "rails/dom_source"
 require_relative "rails/page_inspector"
+require_relative "rails/trace_instrumentation"
 require_relative "rails/aria_snapshot_matching"
 
 module Dommy

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dommy-rails
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - takahashim
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.11.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.11.0
 description: Rails-specific matchers and assertions for Dommy, including form helper
   understanding, Turbo Stream support, Stimulus attribute checking, and HTML quality
   linting.
@@ -50,6 +50,7 @@ files:
 - lib/dommy/rails/rspec/integration.rb
 - lib/dommy/rails/rspec/matchers.rb
 - lib/dommy/rails/stimulus.rb
+- lib/dommy/rails/trace_instrumentation.rb
 - lib/dommy/rails/turbo_stream.rb
 - lib/dommy/rails/url_matcher.rb
 - lib/dommy/rails/url_normalizer.rb