chore: release 0.4.0

Author: alec-c4

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-02-06
+
+### Added
+
+- **Auto-waiting matchers:** `have_text`, `have_content`, and `have_current_path` now automatically retry until the expected condition is met or the timeout expires, eliminating flaky tests caused by page transitions and async rendering
+- `have_current_path` matcher for asserting the current URL path with auto-waiting (supports exact strings and regexps)
+- `E2E.wait_until` helper method for custom waiting logic in tests
+- `wait_timeout` configuration option (default: 5 seconds) to control how long matchers wait before failing
+- `text` method on page/session for reading visible text content of the page body
+
+### Changed
+
+- `fill_in` now matches fields by label, placeholder, id, and name (Capybara-like behavior) instead of only CSS selectors, with fallback to direct CSS selector
+
 ## [0.3.2] - 2026-02-05
 
 ### Fixed

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    e2e (0.3.2)
+    e2e (0.4.0)
       playwright-ruby-client (>= 1.40.0)
       rack
       rackup
@@ -148,7 +148,7 @@ CHECKSUMS
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  e2e (0.3.2)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806

README.md

@@ -85,7 +85,8 @@ RSpec.describe "User Login", type: :e2e do
     fill_in "Password", with: "password"
     click_button "Sign In"
 
-    expect(page.body).to include("Welcome, User!")
+    expect(page).to have_current_path("/dashboard")
+    expect(page).to have_content("Welcome, User!")
   end
 end
 ```
@@ -159,7 +160,8 @@ click_button "Submit"
 click_link "Read more"
 click "#nav-menu" # CSS selector
 
-fill_in "Email", with: "test@example.com"
+fill_in "Email", with: "test@example.com"  # Matches by label, placeholder, id, or name
+fill_in "#email", with: "test@example.com" # CSS selector fallback
 check "I agree"
 uncheck "Subscribe"
 attach_file "#upload", "path/to/file.png"
@@ -175,11 +177,18 @@ find("button", text: "Save") # Filter by text
 
 #### Assertions & Matchers
 
+All text and path matchers **automatically wait** for the expected condition to be met (up to `wait_timeout` seconds), making your tests resilient to page transitions and async rendering.
+
 ```ruby
-# Check for content
-expect(page.body).to include("Success")
-expect(find(".alert")).to have_text("Success")
-expect(find(".alert")).to have_content("Success") # Alias
+# Check for content (auto-waiting)
+expect(page).to have_text("Success")
+expect(page).to have_content("Success")         # Alias for have_text
+expect(find(".alert")).to have_text("Success")   # Works on elements too
+expect(page).to have_text(/welcome/i)            # Regexp support
+
+# Check current path (auto-waiting)
+expect(page).to have_current_path("/dashboard")
+expect(page).to have_current_path(/\/users\/\d+/) # Regexp support
 
 # Check for classes
 expect(find(".alert")).to have_class("success")
@@ -206,6 +215,26 @@ evaluate("document.title") # Execute JS
 save_screenshot("tmp/screen.png")
 ```
 
+### Auto-Waiting
+
+The `have_text`, `have_content`, and `have_current_path` matchers automatically retry until the condition is met or the configured `wait_timeout` expires (default: 5 seconds). This eliminates flaky tests caused by page navigations, redirects, and async rendering.
+
+```ruby
+click_button "Submit"
+# No need for sleep or manual waiting — the matcher will poll until
+# the page transitions and the expected content appears
+expect(page).to have_current_path("/success")
+expect(page).to have_content("Your order has been placed")
+```
+
+For custom waiting logic, use `E2E.wait_until`:
+
+```ruby
+E2E.wait_until(timeout: 10) do
+  page.current_url.include?("/ready")
+end
+```
+
 ### 🔓 Native Access (The Escape Hatch)
 
 We believe you shouldn't be limited by the wrapper. You can access the underlying `Playwright::Page` object at any time using `.native`.
@@ -265,6 +294,7 @@ E2E.configure do |config|
   config.browser_type = :chromium # Options: :chromium (default), :firefox, :webkit
   config.headless = ENV.fetch("HEADLESS", "true") == "true"
   config.app = Rails.application # Automatic Rack booting
+  config.wait_timeout = 5 # Seconds to wait in auto-waiting matchers (default: 5)
 end
 ```
 

gemfiles/rails_7.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.2)
+    e2e (0.4.0)
       playwright-ruby-client (>= 1.40.0)
       rack
       rackup
@@ -335,7 +335,7 @@ CHECKSUMS
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
-  e2e (0.3.2)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

gemfiles/rails_7.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.2)
+    e2e (0.4.0)
       playwright-ruby-client (>= 1.40.0)
       rack
       rackup
@@ -349,7 +349,7 @@ CHECKSUMS
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
-  e2e (0.3.2)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

gemfiles/rails_7.2.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.2)
+    e2e (0.4.0)
       playwright-ruby-client (>= 1.40.0)
       rack
       rackup
@@ -343,7 +343,7 @@ CHECKSUMS
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
-  e2e (0.3.2)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.2)
+    e2e (0.4.0)
       playwright-ruby-client (>= 1.40.0)
       rack
       rackup
@@ -339,7 +339,7 @@ CHECKSUMS
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
-  e2e (0.3.2)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

lib/e2e.rb

@@ -39,14 +39,30 @@ def server
     end
   end
 
+  # Retry a block until it returns truthy or timeout is reached
+  def self.wait_until(timeout: config.wait_timeout, interval: 0.05)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+    loop do
+      result = yield
+      return result if result
+
+      if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        return false
+      end
+
+      sleep interval
+    end
+  end
+
   class Config
-    attr_accessor :driver, :headless, :app, :browser_type
+    attr_accessor :driver, :headless, :app, :browser_type, :wait_timeout
 
     def initialize
       @driver = :playwright
       @browser_type = :chromium
       @headless = ENV.fetch("HEADLESS", "true") == "true"
       @app = nil
+      @wait_timeout = 5
     end
   end
 end

lib/e2e/drivers/playwright.rb

@@ -59,7 +59,21 @@ def click_link(value, **options)
       end
 
       def fill_in(selector, with:)
-        @page.fill(selector, with)
+        # Try to match Capybara's behavior: Label, Placeholder, ID, Name
+        chain = @page.get_by_label(selector).or(@page.get_by_placeholder(selector))
+
+        # Only add ID/Name matching if the selector doesn't contain spaces (valid CSS ID/Name assumption-ish)
+        if selector.match?(/^[a-zA-Z0-9_-]+$/)
+          chain = chain.or(@page.locator("##{selector}"))
+            .or(@page.locator("[name='#{selector}']"))
+        end
+
+        begin
+          chain.first.fill(with)
+        rescue
+          # Fallback to treating it as a direct CSS selector if the above failed
+          @page.fill(selector, with)
+        end
       end
 
       def check(selector)
@@ -78,6 +92,11 @@ def body
         @page.content
       end
 
+      # Required for have_content matcher on page object
+      def text
+        @page.inner_text("body")
+      end
+
       def evaluate(script)
         @page.evaluate(script)
       end

lib/e2e/matchers.rb

@@ -16,25 +16,75 @@
   end
 
   RSpec::Matchers.define :have_text do |expected_text|
-    match do |element|
-      if expected_text.is_a?(Regexp)
-        element.text.match?(expected_text)
-      else
-        element.text.include?(expected_text)
+    match do |actual|
+      @actual_text = nil
+
+      E2E.wait_until do
+        @actual_text = actual.text
+        if expected_text.is_a?(Regexp)
+          @actual_text.match?(expected_text)
+        else
+          @actual_text.include?(expected_text)
+        end
       end
     end
 
-    failure_message do |element|
-      "expected element to have text '#{expected_text}', but it had '#{element.text}'"
+    match_when_negated do |actual|
+      E2E.wait_until do
+        @actual_text = actual.text
+        if expected_text.is_a?(Regexp)
+          !@actual_text.match?(expected_text)
+        else
+          !@actual_text.include?(expected_text)
+        end
+      end
     end
 
-    failure_message_when_negated do |element|
-      "expected element not to have text '#{expected_text}', but it did"
+    failure_message do
+      "expected to find text #{expected_text.inspect} in #{@actual_text.inspect}"
+    end
+
+    failure_message_when_negated do
+      "expected not to find text #{expected_text.inspect} in #{@actual_text.inspect}"
     end
   end
 
   RSpec::Matchers.alias_matcher :have_content, :have_text
 
+  RSpec::Matchers.define :have_current_path do |expected_path|
+    match do |session|
+      @actual_path = nil
+
+      E2E.wait_until do
+        @actual_path = URI.parse(session.current_url).path
+        if expected_path.is_a?(Regexp)
+          @actual_path.match?(expected_path)
+        else
+          @actual_path == expected_path
+        end
+      end
+    end
+
+    match_when_negated do |session|
+      E2E.wait_until do
+        @actual_path = URI.parse(session.current_url).path
+        if expected_path.is_a?(Regexp)
+          !@actual_path.match?(expected_path)
+        else
+          @actual_path != expected_path
+        end
+      end
+    end
+
+    failure_message do
+      "expected current path to be #{expected_path.inspect}, but was #{@actual_path.inspect}"
+    end
+
+    failure_message_when_negated do
+      "expected current path not to be #{expected_path.inspect}, but it was"
+    end
+  end
+
   RSpec::Matchers.define :have_value do |expected_value|
     match do |element|
       element.value == expected_value