RubyGems - phlex-reactive - Versions diffs - 0.11.1 → 0.11.3 - Mend

phlex-reactive 0.11.1 → 0.11.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +49 -0
data/app/javascript/phlex/reactive/reactive_controller.js +114 -7
data/app/javascript/phlex/reactive/reactive_controller.min.js +2 -2
data/app/javascript/phlex/reactive/reactive_controller.min.js.map +3 -3
data/lib/phlex/reactive/test_helpers/system.rb +193 -0
data/lib/phlex/reactive/test_helpers.rb +6 -0
data/lib/phlex/reactive/version.rb +1 -1
data/lib/phlex/reactive.rb +5 -0
metadata +2 -1

data/lib/phlex/reactive/test_helpers/system.rb ADDED Viewed

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+# System/browser test helpers for reactive components (issue #201). Loaded lazily
+# by Phlex::Reactive::TestHelpers ONLY when Capybara is present (the pgbus/mcp
+# optional-require precedent), so the gem never hard depends on Capybara and this
+# module stays out of the request/unit path.
+#
+# Mix it into your system examples from rails_helper:
+#
+#   RSpec.configure do |c|
+#     c.include Phlex::Reactive::TestHelpers::System, type: :system
+#   end
+#
+# It is built on the GLOBAL reactive-activity signal the client runtime exposes:
+# a <html data-reactive-active> marker present while ANY reactive operation (a
+# dispatch round trip OR a deferred render) is in flight, cleared when the whole
+# layer settles. That is the clean primitive to wait on — instead of each spec
+# scraping the union of per-root busy/pending/seed selectors, or holding a node
+# that a morph detaches (StaleReferenceError).
+#
+#   wait_for_reactive                       # block until the layer is idle
+#   expect(page).to have_reactive_value("total", "6")  # a field, re-resolved each poll
+#   expect(page).to have_reactive_text("recap", "6 items") # a mirror node, re-resolved
+#
+# All three re-resolve the DOM every poll cycle (Capybara's waiting behavior), so
+# a compute re-seed / morph / in-flight round trip that REPLACES the node after
+# the triggering action returns can never surface a StaleReferenceError or read a
+# transient blank — the matcher waits for the value to SETTLE.
+module Phlex
+  module Reactive
+    module TestHelpers
+      module System
+        # The <html> marker the client sets while the reactive layer is busy. Kept
+        # in lockstep with reactive_controller.js's ACTIVE_ATTR — the ONE selector
+        # every wait keys off. A [data-reactive-active] presence check is the system
+        # twin of wait_for_turbo watching the Turbo progress bar.
+        ACTIVE_MARKER = "data-reactive-active"
+        # Block until the reactive layer is IDLE — every dispatch round trip and
+        # deferred render has settled and the <html data-reactive-active> marker is
+        # gone. The system-test twin of wait_for_turbo (which watches the Turbo
+        # progress bar, NOT a reactive morph/seed, so it can't cover this).
+        #
+        # Implemented as a Capybara WAITING assertion (have_no_css on the document
+        # element with the default max wait), so it re-checks the live DOM each poll
+        # and raises a readable Capybara::ElementNotFound-style error if the layer
+        # never settles inside `timeout` — never a bare sleep, never a stale read.
+        #
+        # `timeout:` overrides Capybara.default_max_wait_time for a slow operation
+        # (a deferred render behind a real job). Returns nil; call it as a barrier
+        # BEFORE asserting a settled value if you are not already using one of the
+        # waiting matchers below.
+        def wait_for_reactive(timeout: nil)
+          # Scope the check to <html> via the :xpath "/html" so the marker is read
+          # on the document element the client writes it to — not a descendant.
+          # assert_no_selector WAITS (retries) until the marker clears or the wait
+          # budget elapses; a persistent marker fails LOUDLY with Capybara's own
+          # timeout error rather than a silent pass. Called on `page` (the current
+          # session) so it works regardless of whether the example group mixed in
+          # Capybara::DSL.
+          page.assert_no_selector(:xpath, "/html[@#{ACTIVE_MARKER}]", **wait_option(timeout))
+          nil
+        end
+        # Assert (waiting) that the field with DOM id `id` has value `value`,
+        # RE-RESOLVING the field by its id on every poll and reading its live
+        # `.value` PROPERTY (issue #204) — NOT the value attribute. A
+        # reactive_compute reducer paints a computed output with `el.value = …`
+        # (the property); for a DISABLED / read-only output the value attribute
+        # never reflects that, so an attribute-based matcher reads "" and fails.
+        # Reading the property covers enabled AND disabled/computed fields — the
+        # exact case this matcher was built for — and keeps the morph-immunity
+        # (each poll re-finds the node by id, so a re-seed/morph that replaces the
+        # input can't surface a stale node or a transient blank).
+        #
+        #   expect(page).to have_reactive_value("total", "6")
+        #
+        # `timeout:` (or `wait:`) overrides Capybara's default max wait. The
+        # `have_` prefix is Capybara-matcher convention (have_field/have_css), NOT
+        # a predicate — hence the PredicatePrefix disable, mirroring matchers.rb.
+        # rubocop:disable Naming/PredicatePrefix
+        def have_reactive_value(id, value, timeout: nil, wait: nil)
+          ReactiveValueMatcher.new(id, value, wait: timeout || wait)
+        end
+        # Assert (waiting) that the node with DOM id `id` has TEXT `value`,
+        # re-resolving by id each poll — the mirror/recap twin of
+        # have_reactive_value for a text sink (a reactive_compute `text:`/mirror
+        # target, a recap node) rather than a form field.
+        #
+        #   expect(page).to have_reactive_text("recap", "6 items")
+        def have_reactive_text(id, value, **)
+          have_css("##{id}", text: value, **)
+        end
+        # rubocop:enable Naming/PredicatePrefix
+        # A waiting matcher that asserts a field's live `.value` PROPERTY (issue
+        # #204), read by id via evaluate_script so it sees a value a reducer set
+        # on a DISABLED output (where the value attribute stays blank). Polls until
+        # the property equals the expected value or the wait budget elapses,
+        # re-resolving the node by id every cycle (morph-immune). Supports negation
+        # (`not_to`) the Capybara way: the negative holds as soon as the property
+        # differs from the expected value (an absent field reads nil, which never
+        # equals a String expectation — so a missing field satisfies `not_to`).
+        #
+        # A plain class (not RSpec::Matchers.define) so it needs no RSpec at load
+        # time beyond the duck-typed matcher protocol RSpec calls (matches?,
+        # does_not_match?, failure_message*), keeping System loadable under Capybara
+        # alone. The expected value is stringified because a DOM `.value` is always
+        # a JS string on the wire (a numeric literal like 6 compares as "6").
+        class ReactiveValueMatcher
+          def initialize(id, value, wait: nil)
+            @id = id
+            @expected = value.to_s
+            @wait = wait
+          end
+          def matches?(page)
+            @page = page
+            poll_until { current_value == @expected }
+          end
+          # does_not_match? is RSpec's REQUIRED negated-matcher protocol method — its
+          # name is fixed by RSpec, not a predicate we get to rename.
+          # rubocop:disable Naming/PredicatePrefix
+          def does_not_match?(page)
+            @page = page
+            # The negative is satisfied the moment the property is NOT the expected
+            # value (or the field is absent → nil). poll_until returns true as soon
+            # as that holds, false if it stayed equal for the whole budget.
+            poll_until { current_value != @expected }
+          end
+          # rubocop:enable Naming/PredicatePrefix
+          def failure_message
+            "expected ##{@id} to have value #{@expected.inspect} (its .value property), " \
+              "but after waiting it was #{current_value.inspect}"
+          end
+          def failure_message_when_negated
+            "expected ##{@id} NOT to have value #{@expected.inspect} (its .value property), but it did"
+          end
+          private
+          # The field's live `.value` property, re-resolved each call. The
+          # identifier is matched by DOM id OR name (mirroring Capybara's
+          # have_field, which matches id/name/label) — reactive_field emits a
+          # `name`, not an `id`, so an id-only lookup would find nothing. Returns
+          # the String value, or nil when the field is absent (Playwright serializes
+          # a JS null as an empty Hash, so a non-String result is normalized to nil
+          # — the matcher then treats it as "not settled yet" and keeps polling
+          # rather than comparing a Hash to the expected String).
+          def current_value
+            raw = @page.evaluate_script(<<~JS)
+              (() => {
+                const k = #{@id.to_json}
+                const el = document.getElementById(k) || document.getElementsByName(k)[0]
+                return el ? el.value : null
+              })()
+            JS
+            raw.is_a?(::String) ? raw : nil
+          end
+          # Bounded poll on a JS-property condition Capybara can't express as a
+          # built-in waiting matcher. Uses the monotonic clock and the configured
+          # (or overridden) Capybara max wait — the same shape the system specs'
+          # hand-rolled wait_for used, now lifted into the helper.
+          def poll_until
+            deadline = now + (@wait || ::Capybara.default_max_wait_time)
+            loop do
+              return true if yield
+              return false if now >= deadline
+              sleep 0.05
+            end
+          end
+          def now = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+        end
+        private
+        # Fold an explicit `timeout:` into Capybara's `wait:` option, or omit it so
+        # Capybara's configured default applies. Kept tiny so every waiter shares
+        # one timeout convention.
+        def wait_option(timeout)
+          timeout.nil? ? {} : { wait: timeout }
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/test_helpers.rb CHANGED Viewed

@@ -314,3 +314,9 @@ end
 # them only when RSpec is present, so a Minitest app can mix in TestHelpers and
 # assert on Result predicates directly with no RSpec dependency.
 require "phlex/reactive/test_helpers/matchers" if defined?(RSpec::Matchers)
+# The system/browser helpers (wait_for_reactive + the re-resolving value/text
+# matchers, issue #201) are optional too: load them only when Capybara is present
+# (a dev/test dependency), keeping them entirely out of the runtime path — the
+# same optional-require gate as the matchers above and the engine below.
+require "phlex/reactive/test_helpers/system" if defined?(Capybara)

data/lib/phlex/reactive/version.rb CHANGED Viewed

@@ -2,6 +2,6 @@
 module Phlex
   module Reactive
-    VERSION = "0.11.1"
+    VERSION = "0.11.3"
   end
 end

data/lib/phlex/reactive.rb CHANGED Viewed

@@ -978,6 +978,11 @@ loader.ignore("#{lib}/generators")
 # Zeitwerk's naming — test_helpers.rb requires it explicitly (only when RSpec is
 # present), and the loader must ignore it.
 loader.ignore("#{lib}/phlex/reactive/test_helpers/matchers.rb")
+# The system/browser test helpers (issue #201) are Capybara-only — a dev/test
+# dependency, never a runtime one. test_helpers.rb requires this file explicitly
+# only when Capybara is present, so the loader must ignore it (otherwise an
+# eager-load in production would define browser helpers with no Capybara).
+loader.ignore("#{lib}/phlex/reactive/test_helpers/system.rb")
 # The MCP diagnostic tool tree (issue #168) subclasses the OPTIONAL `mcp` gem's
 # constants (MCP::Tool) at class-definition time, so the whole mcp/ subdirectory
 # must stay out of the autoloader — Phlex::Reactive::MCP.load! requires it in

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.11.3
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -177,6 +177,7 @@ files:
 - lib/phlex/reactive/streamable.rb
 - lib/phlex/reactive/test_helpers.rb
 - lib/phlex/reactive/test_helpers/matchers.rb
+- lib/phlex/reactive/test_helpers/system.rb
 - lib/phlex/reactive/version.rb
 - lib/tasks/phlex_reactive.rake
 homepage: https://github.com/mhenrixon/phlex-reactive