e2e 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 803c14bd6d5868f7ae89a2af6e67da28be4fa3a8fc48249a0a60672fad495c3c
-  data.tar.gz: 5e51d72904f0ccb1d316f753e4fbd766957de8538ce804a8a8bf2a8ae26f911c
+  metadata.gz: d1381ff492123e32a28b99424261800a7a7b2af8fe6ad9e062ac15decf621718
+  data.tar.gz: e80efe7eabc1c5ffd43802138cbce63cbb824558d22439b4e2702f62c4bb8ef3
 SHA512:
-  metadata.gz: 98cd206b7dc00293712b48a93d5ff732d01cf39630ebfbe2d0a105bb7f9d34a0efe59c8d16d93149774ed76709450d925e58eb376669f11cd3257723a82852e3
-  data.tar.gz: febfd9530d491c8c2ec6b272040833a5fc2d5c4f3fc49cd8eb3c4920294f11ef44451216222aa4d4646b388f66b2e32c9d424d921e335fbe852c99437dd46111
+  metadata.gz: 1e849aacf7b8ccac13c94c3724a407ca7f0f3f563a2aa0ef6d12bee3c9383db32a1a73460d02af96c38960d7a68997ca3dcf0d167b42bafeb142b12ab2afb675
+  data.tar.gz: 8f235e5164cf96c3a93d3fde923ed9666482cc13765b566a8cf713900d611165ebb9a8d84aee387fc8478271013deb1276fe0dc9bd888cfa4819c8425d4f15d8

data/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

data/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
 ```
 

data/gemfiles/rails_7.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.1)
+    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.1)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

data/gemfiles/rails_7.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.1)
+    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.1)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

data/gemfiles/rails_7.2.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.1)
+    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.1)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    e2e (0.3.1)
+    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.1)
+  e2e (0.4.0)
   erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
   globalid (1.3.0) sha256=05c639ad6eb4594522a0b07983022f04aa7254626ab69445a0e493aa3786ff11

data/lib/e2e/drivers/playwright.rb

@@ -59,7 +59,21 @@ module E2E
       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 @@ module E2E
         @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

data/lib/e2e/matchers.rb

@@ -16,25 +16,75 @@ if defined?(RSpec::Matchers)
   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

data/lib/e2e/session.rb

@@ -8,7 +8,7 @@ module E2E
 
     attr_reader :driver
 
-    def_delegators :@driver, :current_url, :click, :click_button, :click_link, :fill_in, :check, :uncheck, :attach_file, :body, :evaluate, :save_screenshot, :native, :pause, :reset!, :quit
+    def_delegators :@driver, :current_url, :click, :click_button, :click_link, :fill_in, :check, :uncheck, :attach_file, :body, :text, :evaluate, :save_screenshot, :native, :pause, :reset!, :quit
 
     def initialize(driver_name = E2E.config.driver)
       @driver = initialize_driver(driver_name)

data/lib/e2e/version.rb

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

data/lib/e2e.rb

@@ -39,14 +39,30 @@ module E2E
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: e2e
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -238,7 +238,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.5
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Unified E2E testing framework for Ruby.
 test_files: []