e2e 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 803c14bd6d5868f7ae89a2af6e67da28be4fa3a8fc48249a0a60672fad495c3c
+  data.tar.gz: 5e51d72904f0ccb1d316f753e4fbd766957de8538ce804a8a8bf2a8ae26f911c
+SHA512:
+  metadata.gz: 98cd206b7dc00293712b48a93d5ff732d01cf39630ebfbe2d0a105bb7f9d34a0efe59c8d16d93149774ed76709450d925e58eb376669f11cd3257723a82852e3
+  data.tar.gz: febfd9530d491c8c2ec6b272040833a5fc2d5c4f3fc49cd8eb3c4920294f11ef44451216222aa4d4646b388f66b2e32c9d424d921e335fbe852c99437dd46111

data/Appraisals

@@ -0,0 +1,15 @@
+appraise "rails-7.0" do
+  gem "rails", "~> 7.0.0"
+end
+
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+appraise "rails-8.0" do
+  gem "rails", "~> 8.0.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.2] - 2026-02-05
+
+### Fixed
+
+- `Playwright::TargetClosedError` on CI environments without X-server by only enabling debug console in headed mode
+- `pause` now raises a clear error when called in headless mode instead of failing silently
+
+## [0.3.1] - 2026-02-05
+
+### Fixed
+
+- `uninitialized constant RSpec::Matchers` error when loading the gem in environments where RSpec is only partially initialized (e.g., via `Bundler.require`)
+- Matchers are now only defined if `RSpec::Matchers` is actually present
+- Matchers are no longer automatically loaded by `require "e2e"`; they are now explicitly loaded via `require "e2e/rspec"`
+
+## [0.3.0] - 2026-02-05
+
+### Added
+
+- Custom RSpec matchers: `have_class`, `have_text`/`have_content`, `have_value`, `have_attribute`, `be_visible`, `be_checked`, `be_disabled`/`be_enabled`
+- Element API methods: `classes`, `has_class?`, `visible?`, `[]`, `value`, `checked?`, `disabled?`, `enabled?`
+- Improved debugging documentation and fixed `pause` helper
+
+## [0.2.0] - 2026-02-05
+
+### Added
+
+- Browser switching support for Chromium, Firefox, and WebKit via `E2E.config.browser_type`
+- `E2E.reset_session!` for dynamic session management
+- `rails g e2e:install` generator with test framework detection (RSpec/Minitest) and RuboCop config injection
+- `rails g e2e:test` generator for scaffolding test files
+- Minitest support via `E2E::Minitest::TestCase`
+- RuboCop integration with automatic `inherit_gem` injection
+- `pause` helper for Playwright Inspector
+
+## [0.1.0] - 2026-02-05
+
+### Added
+
+- Initial release of `e2e` gem, a unified testing framework wrapper around Playwright
+- Playwright driver implementation using `playwright-ruby-client` (IPC/Pipes)
+- Capybara-like DSL: `visit`, `click_button`, `click_link`, `fill_in`, `check`, `uncheck`, `attach_file`, `find`, `all`
+- `E2E.enable_shared_connection!` for fast transactional tests in Rails
+- Rack application booting via `E2E.config.app`
+- Basic RSpec integration (`type: :e2e`)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexey Poimtsev
+
+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,327 @@
+# E2E
+
+**Unified, high-performance E2E testing framework for Ruby.**
+
+`e2e` is a modern wrapper around **Playwright**, designed to bring the elegance of Capybara and the speed of raw browser automation together.
+
+[![Gem Version](https://badge.fury.io/rb/e2e.svg)](https://badge.fury.io/rb/e2e)
+[![Build Status](https://github.com/alec-c4/e2e/actions/workflows/main.yml/badge.svg)](https://github.com/alec-c4/e2e/actions)
+
+## Why E2E?
+
+- **⚡️ Blazing Fast:** Uses direct IPC (Pipes) to communicate with the browser, avoiding HTTP overhead.
+- **🧩 Plug & Play:** Zero configuration for most Rails apps. Includes a generator.
+- **💎 Clean DSL:** Idiomatic Ruby API (`click_button`, `find`, `visit`) that feels like home.
+- **🚀 Modern Engine:** Powered by Microsoft Playwright (WebKit, Firefox, Chromium).
+- **🛠 Escape Hatch:** Direct access to the `native` Playwright object for **any** complex scenario.
+- **🔄 Shared Connection:** Built-in support for sharing DB connections between test and app threads (transactional tests support).
+- **👮‍♀️ Lint Friendly:** Includes auto-configuration for RuboCop to respect E2E testing patterns.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+group :test do
+  gem "e2e"
+end
+```
+
+And then execute:
+
+```bash
+bundle install
+npx playwright install # Install browser binaries
+```
+
+### Rails Setup
+
+Run the generator to create the helper file:
+
+```bash
+rails g e2e:install
+```
+
+This will create `spec/e2e_helper.rb` (for RSpec) or `test/e2e_helper.rb` (for Minitest) and configure your `.rubocop.yml`.
+
+## RuboCop Integration
+
+`e2e` comes with a built-in RuboCop configuration that relaxes strict RSpec rules (like `DescribeClass` or `ExampleLength`) which are often not suitable for high-level E2E tests.
+
+The generator adds this to your `.rubocop.yml` automatically:
+
+```yaml
+inherit_gem:
+  e2e: config/rubocop.yml
+```
+
+This will apply the following changes to all files in `spec/e2e/` and `test/e2e/`:
+
+- Disable `RSpec/DescribeClass` and `RSpec/DescribeMethod`.
+- Disable `RSpec/ExampleLength` and `RSpec/MultipleExpectations`.
+- Increase `RSpec/NestedGroups` allowance.
+
+## Usage
+
+You can generate a new test using:
+
+```bash
+rails g e2e:test UserLogin
+```
+
+### RSpec Example
+
+Write your tests in `spec/e2e/`.
+
+```ruby
+# spec/e2e/login_spec.rb
+require "e2e_helper"
+
+RSpec.describe "User Login", type: :e2e do
+  it "signs in successfully" do
+    visit "/login"
+
+    fill_in "Email", with: "user@example.com"
+    fill_in "Password", with: "password"
+    click_button "Sign In"
+
+    expect(page.body).to include("Welcome, User!")
+  end
+end
+```
+
+### Minitest Example
+
+Write your tests in `test/e2e/`.
+
+```ruby
+# test/e2e/login_test.rb
+require "e2e_helper"
+
+class UserLoginTest < E2E::Minitest::TestCase
+  def test_sign_in
+    visit "/login"
+
+    fill_in "Email", with: "user@example.com"
+    fill_in "Password", with: "password"
+    click_button "Sign In"
+
+    assert_includes page.body, "Welcome, User!"
+  end
+end
+```
+
+## Debugging & UI Mode
+
+By default, tests run in **headless** mode (no browser window). For debugging, you can run tests in **headful** mode to see what's happening.
+
+### Running with a visible browser
+
+Set the `HEADLESS` environment variable to `false`:
+
+```bash
+HEADLESS=false bundle exec rspec spec/e2e
+```
+
+### Pausing for Debugging
+
+If the browser closes too fast, you can pause the execution to inspect the page or step through the test. This will open the **Playwright Inspector**.
+
+Add this to your test:
+
+```ruby
+it "debugs something" do
+  visit "/path"
+  pause # The test will stop here, and a debugger UI will open
+  click_button "Submit"
+end
+```
+
+Alternatively, you can just use `sleep(10)` if you want the browser to stay open for a few seconds without opening the inspector.
+
+### Automatic Screenshots
+
+If a test fails in RSpec, a screenshot is automatically saved to `tmp/screenshots/` for quick investigation.
+
+### API Reference
+
+#### Navigation
+
+```ruby
+visit("/path")
+current_url
+```
+
+#### Interaction
+
+```ruby
+click_button "Submit"
+click_link "Read more"
+click "#nav-menu" # CSS selector
+
+fill_in "Email", with: "test@example.com"
+check "I agree"
+uncheck "Subscribe"
+attach_file "#upload", "path/to/file.png"
+```
+
+#### Finding Elements
+
+```ruby
+find(".btn")          # Returns E2E::Element
+all("li")             # Returns Array<E2E::Element>
+find("button", text: "Save") # Filter by text
+```
+
+#### Assertions & Matchers
+
+```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 classes
+expect(find(".alert")).to have_class("success")
+expect(find(".alert")).not_to have_class("error")
+
+# Check visibility
+expect(find("#modal")).to be_visible
+
+# Check attributes & value
+expect(find("input")).to have_value("test")
+expect(find("div")).to have_attribute("data-id", "123")
+
+# Check states
+expect(find("#checkbox")).to be_checked
+expect(find("button")).to be_disabled
+expect(find("input")).to be_enabled
+```
+
+#### Assertions & Data
+
+```ruby
+page.body             # Full HTML
+evaluate("document.title") # Execute JS
+save_screenshot("tmp/screen.png")
+```
+
+### 🔓 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`.
+
+**This means you have access to 100% of Playwright's features.**
+
+#### 1. Keyboard Shortcuts
+
+```ruby
+find("input").click
+page.native.keyboard.press("Enter")
+page.native.keyboard.press("Control+C")
+```
+
+#### 2. Network Interception (Mocking)
+
+```ruby
+page.native.route("**/api/users") do |route|
+  route.fulfill(status: 200, body: '{"users": []}')
+end
+```
+
+#### 3. Handling Dialogs (Alerts/Confirms)
+
+```ruby
+page.native.on("dialog") do |dialog|
+  dialog.accept
+end
+click_button "Delete Account"
+```
+
+#### 4. Emulation (Mobile/Dark Mode)
+
+```ruby
+page.native.viewport_size = { width: 375, height: 667 }
+page.native.emulate_media(color_scheme: 'dark')
+```
+
+## Performance: Transactional Tests
+
+By default, Rails system tests run in a separate thread, meaning they can't see data created in a database transaction.
+`e2e` solves this with **Shared Connection**.
+
+Enable it in your `spec/e2e_helper.rb`:
+
+```ruby
+E2E.enable_shared_connection!
+```
+
+Now you can use fast transactional tests (standard RSpec behavior) instead of slow `DatabaseCleaner` truncation strategies.
+
+## Configuration
+
+```ruby
+E2E.configure do |config|
+  config.driver = :playwright
+  config.browser_type = :chromium # Options: :chromium (default), :firefox, :webkit
+  config.headless = ENV.fetch("HEADLESS", "true") == "true"
+  config.app = Rails.application # Automatic Rack booting
+end
+```
+
+### Multiple Browsers
+
+One of the key advantages of Playwright is true cross-browser testing. You can easily switch engines:
+
+- **Chromium:** Google Chrome, Microsoft Edge, etc.
+- **Firefox:** Mozilla Firefox.
+- **WebKit:** Safari, iOS browsers.
+
+To test in Safari (WebKit):
+
+```ruby
+E2E.configure { |config| config.browser_type = :webkit }
+```
+
+Don't forget to install all browser binaries:
+
+```bash
+npx playwright install
+```
+
+### Switching Browsers per Test (RSpec)
+
+You can run specific tests in different browsers using metadata (requires simple setup in your helper).
+
+First, update your `spec/e2e_helper.rb` to respect metadata:
+
+```ruby
+RSpec.configure do |config|
+  config.before(:each) do |example|
+    browser = example.metadata[:browser]
+    if browser
+      E2E.config.browser_type = browser
+      E2E.reset_session! # Force new browser launch
+    end
+  end
+
+  config.after(:each) do
+    if E2E.config.browser_type != :chromium
+      E2E.config.browser_type = :chromium
+      E2E.reset_session!
+    end
+  end
+end
+```
+
+Then use it in your specs:
+
+```ruby
+it "works in Safari", browser: :webkit do
+  visit "/"
+  expect(page.body).to include("Safari specific feature")
+end
+```
+
+## 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,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/config/rubocop.yml

@@ -0,0 +1,31 @@
+# Configuration for E2E tests
+# This configuration relaxes strict RSpec rules for E2E scenarios.
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/e2e/**/*'
+    - 'test/e2e/**/*'
+
+RSpec/DescribeMethod:
+  Exclude:
+    - 'spec/e2e/**/*'
+    - 'test/e2e/**/*'
+
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/e2e/**/*'
+    - 'test/e2e/**/*'
+
+# E2E tests often involve multiple steps and checks
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/e2e/**/*'
+    - 'test/e2e/**/*'
+
+RSpec/MultipleExpectations:
+  Exclude:
+    - 'spec/e2e/**/*'
+    - 'test/e2e/**/*'
+
+RSpec/NestedGroups:
+  Max: 4

data/gemfiles/rails_7.0.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "appraisal"
+gem "lefthook"
+gem "standard"
+gem "rubocop-rspec"
+gem "rubocop-performance"
+gem "rails", "~> 7.0.0"
+
+gemspec path: "../"