### Install Capybara Gem

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Add this line to your Gemfile to install Capybara. Run `bundle install` afterwards.

```ruby
gem 'capybara'
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Install project dependencies using Bundler and run the test suite. Use `spec_chrome` for Chrome tests, which requires `chromedriver`.

```bash
bundle install
```

```bash
bundle exec rake  # run the test suite with Firefox - requires `geckodriver` to be installed
```

```bash
bundle exec rake spec_chrome # run the test suite with Chrome - require `chromedriver` to be installed
```

--------------------------------

### Selector Name Argument Examples

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Demonstrates how the name argument in selectors can be explicit or inferred by helper methods.

```ruby
page.html # => '<a href="/">Home</a>'

page.find(:link) == page.find_link

page.html # => '<input>'

page.find(:field) == page.find_field
```

--------------------------------

### Selector Locator Argument Examples

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Shows how to use CSS and XPath locators to find elements. The default selector can be configured.

```ruby
page.html # => '<div id="greeting">Hello world</div>'

page.find(:css, 'div').text     # => 'Hello world'
page.find(:xpath, './/div').text # => 'Hello world'
```

```ruby
page.html # => '<div id="greeting">Hello world</div>'

Capybara.default_selector = :css

page.find('div').text     # => 'Hello world'

Capybara.default_selector = :xpath

page.find('.//div').text # => 'Hello world'
```

--------------------------------

### Navigating with visit

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

The `visit` method navigates the browser to a specified URL. The request method is always GET.

```APIDOC
## visit

### Description
Navigates the browser to a specified URL.

### Method
GET

### Endpoint
[URL]

### Parameters
#### Path Parameters
- **url** (string) - Required - The URL to navigate to.

### Request Example
```ruby
visit('/projects')
visit(post_comments_path(post))
```
```

--------------------------------

### Selector Filter Argument Examples

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Demonstrates using filter arguments like 'href', 'text', and 'id' to refine element selection.

```ruby
page.html # => '<a href="/">Home</a>'

# find by the [href] attribute
page.find_link(href: '/') == page.find_link(text: 'Home') # => true

page.html # => '<div id="element" data-attribute="value">Content</div>'

# find by the [id] attribute
page.find(id: 'element') == page.find(text: 'Content') # => true

# find by the [data-attribute] attribute
page.find(:element, 'data-attribute': /value/) == page.find(text: 'Content') # => true

page.html # => '<input type="checkbox">'
```

--------------------------------

### Configure RackTest Driver Headers

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Register a custom RackTest driver with specific headers. This example sets the 'HTTP_USER_AGENT' header.

```ruby
Capybara.register_driver :rack_test do |app|
  Capybara::RackTest::Driver.new(app, headers: { 'HTTP_USER_AGENT' => 'Capybara' })
end
```

--------------------------------

### Manually Create and Use a Capybara Session

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Instantiate a `Capybara::Session` manually for full control. Requires Capybara and a Rack app. This example demonstrates filling form fields and clicking a button.

```ruby
require 'capybara'

session = Capybara::Session.new(:webkit, my_rack_app)
session.within("form#session") do
  session.fill_in 'Email', with: 'user@example.com'
  session.fill_in 'Password', with: 'password'
end
session.click_button 'Sign in'
```

--------------------------------

### Configure Capybara Session Options

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

In threadsafe mode, options can be set per session. This example shows how to configure `automatic_label_click` and `default_max_wait_time` for a specific session.

```ruby
my_session = Capybara::Session.new(:driver, some_app) do |config|
  config.automatic_label_click = true # only set for my_session
end
my_session.config.default_max_wait_time = 10 # only set for my_session
Capybara.default_max_wait_time = 2 # will not change the default_max_wait in my_session
```

--------------------------------

### Basic Asynchronous Operation (Likely to Fail)

Source: https://github.com/teamcapybara/capybara/wiki/Asynchronous-Javascript-drivers

This example demonstrates a common pitfall where assertions are made before the server has finished processing the request, often leading to test failures.

```ruby
visit "/posts/new"
fill_in :title, :with => "Hello"
click_button "Create Post"
Post.last.title.should == "Hello"
```

--------------------------------

### Retrieve Page HTML

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Get the current state of the DOM as a string. Primarily for debugging, avoid testing against this directly.

```ruby
print page.html
```

--------------------------------

### Navigate to a URL with Capybara

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Use the `visit` method to navigate to a specific path or URL. The request method is always GET.

```ruby
visit('/projects')
visit(post_comments_path(post))
```

--------------------------------

### Minitest::Spec Assertion Example

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

An example of using Capybara's `must_have_content` assertion within Minitest::Spec. Ensure `capybara/minitest/spec` is required.

```ruby
page.must_have_content('Important!')
```

--------------------------------

### Find Multiple Elements with `all` and `first`

Source: https://context7.com/teamcapybara/capybara/llms.txt

Use `all` to get a collection of matching elements, optionally with count constraints. `first` returns the first match or nil if none found (with `minimum: 0`). Waits for count constraints if specified.

```ruby
# All matching links
links = all('a')
links.each { |a| puts a[:href] }

# With count constraints (raises if not satisfied after waiting)
rows = all('tr', minimum: 3)
cells = all('td.price', count: 5)
items = all('li', between: 2..8)

# Filter by text / visibility
labels = all('label', text: /required/i, visible: true)

# XPath
all(:xpath, './/input[@type="checkbox"]').each(&:check)

# First match (returns nil if minimum: 0 and nothing found)
first_error = first('.error-msg', minimum: 0)
puts first_error&.text

# Custom filter block
all(:field, 'Qty') { |el| el.value.to_i > 0 }
```

--------------------------------

### Set Default Capybara Driver

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Configure Capybara to use a specific driver by default. This example sets the default driver to `:selenium`.

```ruby
Capybara.default_driver = :selenium # :selenium_chrome and :selenium_chrome_headless are also registered
```

--------------------------------

### Registering Custom Capybara Drivers

Source: https://context7.com/teamcapybara/capybara/llms.txt

Register custom driver configurations with `Capybara.register_driver` for specialized browser setups, such as mobile emulation or custom profiles.

```ruby
# Custom Selenium Chrome driver with options
Capybara.register_driver :chrome_mobile do |app|
  options = Selenium::WebDriver::Chrome::Options.new
  options.add_emulation(device_name: 'iPhone X')
  options.add_argument('--headless')
  Capybara::Selenium::Driver.new(app, browser: :chrome, options: options)
end

# Selenium with custom profile
Capybara.register_driver :firefox_custom do |app|
  profile = Selenium::WebDriver::Firefox::Profile.new
  profile['browser.download.folderList'] = 2
  profile['browser.download.dir'] = '/tmp/downloads'
  options = Selenium::WebDriver::Firefox::Options.new(profile: profile)
  Capybara::Selenium::Driver.new(app, browser: :firefox, options: options)
end

# Use in specs
Capybara.current_driver = :chrome_mobile
visit '/mobile-landing'
expect(page).to have_css('.mobile-nav')

# Temporarily switch driver
Capybara.using_driver(:chrome_mobile) do
  visit '/checkout'
end
```

--------------------------------

### Temporarily Switch Capybara Driver

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Switch the Capybara driver temporarily within test setup and teardown blocks. Remember to switch back to the default driver afterwards.

```ruby
Capybara.current_driver = :selenium # temporarily select different driver
# tests here
Capybara.use_default_driver       # switch back to default driver
```

--------------------------------

### Working with Browser Windows

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Use `window_opened_by` to capture a new window opened by an action and `within_window` to scope interactions to that specific window.

```ruby
facebook_window = window_opened_by do
  click_button 'Like'
end
within_window facebook_window do
  find('#login_email').set('a@example.com')
  find('#login_password').set('qwerty')
  click_button 'Submit'
end
```

--------------------------------

### Navigation - visit, refresh, go_back, go_forward

Source: https://context7.com/teamcapybara/capybara/llms.txt

Navigate the browser to a URL. `visit` accepts both relative paths and absolute URLs; relative paths are resolved against `app_host` or the running server.

```APIDOC
## Navigation - `visit`, `refresh`, `go_back`, `go_forward`

### Description
Navigate the browser to a URL. `visit` accepts both relative paths and absolute URLs; relative paths are resolved against `app_host` or the running server.

### Code Example
```ruby
# With Capybara::DSL included (RSpec feature spec, Cucumber step, etc.)
visit '/products'
visit 'http://external-site.com/page'

puts current_url    # => "http://127.0.0.1:4567/products"
puts current_path   # => "/products"
puts current_host   # => "http://127.0.0.1:4567"
puts html           # => current DOM as string
puts status_code    # => 200  (rack_test only)
puts response_headers['Content-Type']  # rack_test only

refresh             # reload current page
go_back             # browser back
go_forward          # browser forward
```
```

--------------------------------

### Save and Open Current Page

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Use this to take a snapshot of the current page for debugging purposes.

```ruby
save_and_open_page
```

--------------------------------

### Configuration - Capybara.configure

Source: https://context7.com/teamcapybara/capybara/llms.txt

Global configuration block for setting driver selection, wait times, selector strategy, server settings, and more. Options can also be set on a per-session basis when `threadsafe` mode is enabled.

```APIDOC
## Configuration - `Capybara.configure`

### Description
Global configuration block that sets driver selection, wait times, selector strategy, server settings, and more. All options are also settable on a per-session basis when `threadsafe` mode is enabled.

### Code Example
```ruby
require 'capybara/rspec'

Capybara.configure do |config|
  config.default_driver      = :rack_test           # fastest, no JS
  config.javascript_driver   = :selenium_chrome_headless
  config.default_max_wait_time = 5                  # seconds to retry async queries
  config.default_selector    = :css                 # :css (default) or :xpath
  config.match               = :smart               # :one, :first, :smart, :prefer_exact
  config.exact               = false                # allow partial text matches
  config.exact_text          = false
  config.ignore_hidden_elements = true              # visible elements only by default
  config.automatic_label_click  = false             # auto-click labels for checkboxes
  config.enable_aria_label      = false             # use aria-label as locator fallback
  config.enable_aria_role       = false
  config.save_path           = 'tmp/capybara'       # for save_page / save_screenshot
  config.asset_host          = 'http://localhost:3000'
  config.app_host            = nil
  config.server              = :puma                # or :webrick, or custom proc
  config.server              = :puma, { Silent: true }
  config.raise_server_errors = true
  config.threadsafe          = false                # must be set before any session is created
  config.test_id             = 'data-testid'        # custom attribute checked alongside id
  config.default_normalize_ws = false
  config.w3c_click_offset    = false
  config.predicates_wait     = true
  config.disable_animation   = false
end
```
```

--------------------------------

### Revert to WEBRick Server

Source: https://github.com/teamcapybara/capybara/blob/master/UPGRADING.md

If your project does not use Puma, you can revert to the previous default WEBRick server by specifying it.

```ruby
Capybara.server = :webrick
```

--------------------------------

### Visit a Specific URL Directly

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Visit any URL directly, useful when working with drivers that support remote connections.

```ruby
visit('http://www.google.com')
```

--------------------------------

### Set Capybara Driver in Rails Test

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Temporarily set the Capybara driver for a specific test class in Rails. This example sets the driver to the JavaScript-capable Selenium driver.

```ruby
class BlogTest < ActionDispatch::IntegrationTest
  setup do
    Capybara.current_driver = Capybara.javascript_driver # :selenium by default
  end

  test 'shows blog posts' do
    # ... this test is run with Selenium ...
  end
end
```

--------------------------------

### Capybara Configuration

Source: https://context7.com/teamcapybara/capybara/llms.txt

Configure global settings for Capybara, including drivers, wait times, and selector strategies. Ensure `threadsafe` is set before creating any sessions.

```ruby
require 'capybara/rspec'

Capybara.configure do |config|
  config.default_driver      = :rack_test           # fastest, no JS
  config.javascript_driver   = :selenium_chrome_headless
  config.default_max_wait_time = 5                  # seconds to retry async queries
  config.default_selector    = :css                 # :css (default) or :xpath
  config.match               = :smart               # :one, :first, :smart, :prefer_exact
  config.exact               = false                # allow partial text matches
  config.exact_text          = false
  config.ignore_hidden_elements = true              # visible elements only by default
  config.automatic_label_click  = false             # auto-click labels for checkboxes
  config.enable_aria_label      = false             # use aria-label as locator fallback
  config.enable_aria_role       = false
  config.save_path           = 'tmp/capybara'       # for save_page / save_screenshot
  config.asset_host          = 'http://localhost:3000'
  config.app_host            = nil
  config.server              = :puma                # or :webrick, or custom proc
  config.server              = :puma, { Silent: true }
  config.raise_server_errors = true
  config.threadsafe          = false                # must be set before any session is created
  config.test_id             = 'data-testid'        # custom attribute checked alongside id
  config.default_normalize_ws = false
  config.w3c_click_offset    = false
  config.predicates_wait     = true
  config.disable_animation   = false
end
```

--------------------------------

### Perform Drag-and-Drop Operations

Source: https://context7.com/teamcapybara/capybara/llms.txt

Simulate dragging an element to a target element or dropping files onto a drop zone. Options like delay, HTML5 mode, and modifier keys are available.

```ruby
source = find('#item-1')
target = find('#trash-bin')
source.drag_to(target)
```

```ruby
source.drag_to(target, delay: 0.1, html5: true, drop_modifiers: :shift)
```

```ruby
dropzone = find('#dropzone')
dropzone.drop('/path/to/upload.csv')
```

```ruby
dropzone.drop({ 'text/plain' => 'pasted text content' })
```

--------------------------------

### Restricting Scope within Elements

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Use `find` to get a specific element and then chain Capybara DSL methods to interact with elements only within that found element's scope.

```ruby
find('#navigation').click_link('Home')
expect(find('#navigation')).to have_button('Sign out')
```

--------------------------------

### Access Shadow DOM Elements

Source: https://context7.com/teamcapybara/capybara/llms.txt

Interact with elements inside a web component's shadow root. Find the host element, get its shadow root, and then query elements within it.

```ruby
host = find('my-custom-element')
shadow = host.shadow_root

within shadow do
  fill_in 'Internal Input', with: 'hello'
  click_button 'Submit'
end
```

```ruby
shadow.find('button.close').click
expect(shadow).to have_css('.result', text: 'Done')
```

--------------------------------

### Handle Browser Alerts

Source: https://context7.com/teamcapybara/capybara/llms.txt

Accept a browser alert dialog. The action that triggers the alert must be wrapped in a block. The alert's message is returned.

```ruby
message = accept_alert do
  click_button 'Show Alert'
end
puts message   # => "Are you sure?"
```

```ruby
accept_alert 'Warning: data will be lost' do
  click_link 'Delete Account'
end
```

--------------------------------

### Define Custom Capybara Selectors

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Add custom selectors using `Capybara.add_selector`. The block must return an XPath or CSS expression. Examples show attribute, row number, and flash type selectors.

```ruby
Capybara.add_selector(:my_attribute) do
  xpath { |id| XPath.descendant[XPath.attr(:my_attribute) == id.to_s] }
end

Capybara.add_selector(:row) do
  xpath { |num| ".//tbody/tr[#{num}]" }
end

Capybara.add_selector(:flash_type) do
  css { |type| "#flash.#{type}" }
end
```

--------------------------------

### Execute JavaScript with Arguments

Source: https://context7.com/teamcapybara/capybara/llms.txt

Evaluate a JavaScript expression within the page context, passing arguments. The first argument is the script, followed by any arguments to be passed to the script.

```ruby
result = evaluate_script(<<~JS, 3, find('#counter'))
  (function(n, el) {
    return parseInt(el.textContent, 10) + n;
  })(arguments[0], arguments[1])
JS
```

--------------------------------

### Manage Multiple Browser Windows

Source: https://context7.com/teamcapybara/capybara/llms.txt

Open new windows/tabs, switch between them, and wait for them to open or close. This functionality is Selenium-specific.

```ruby
new_win = open_new_window
within_window new_win do
  visit '/help'
  expect(page).to have_text 'Help Center'
end
```

```ruby
popup = window_opened_by do
  click_link 'Open in new window'
end
within_window popup do
  expect(page).to have_current_path '/preview'
  popup.close
end
```

```ruby
switch_to_window { title == 'Payment Gateway' }
```

```ruby
windows.each do |win|
  within_window(win) { puts current_url }
end
```

```ruby
popup = window_opened_by { click_button 'Popup' }
within_window popup do
  click_button 'Close'
end
expect(popup).to become_closed(wait: 2)
```

--------------------------------

### Selector Locator with Different Argument Types

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Illustrates finding elements using various locator argument types like String, Array, and Hash.

```ruby
page.html # => '<label for="greeting">Greeting</label>
          #     <input id="greeting" name="content">'

# find by the <input> element's [id] attribute
page.find(:id, 'greeting') == page.find_by_id('greeting') # => true

# find by the <input> element's [id] attribute
page.find(:field, 'greeting') == page.find_field('greeting') # => true

# find by the <input> element's [name] attribute
page.find(:field, 'content') == page.find_field('content') # => true

# find by the <label> element's text
page.find(:field, 'Greeting') == page.find_field('Greeting') # => true

page.html # => '<table>
          #       <tr>
          #         <th>A</th>
          #         <th>B</th>
          #       </tr>
          #       <tr>
          #         <td>1</td>
          #         <td>2</td>
          #       </tr>
          #     </table>'

# find by <td> content
page.find(:table_row, ['1', '2']) == page.find(:css, 'tr:last-of-type') # => true

# find by <th> content paired with corresponding <td> content
page.find(:table_row, 'A' => '1') == page.find(:table_row, 'B' => '2') # => true
```

--------------------------------

### Clicking Links and Buttons

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Methods for interacting with links and buttons on the page. `click_on` can be used for both.

```APIDOC
## Clicking Links and Buttons

### Description
Interacts with the web application by following links and clicking buttons. Automatically handles redirects and form submissions associated with buttons.

### Methods
- `click_link(locator)`
- `click_button(locator)`
- `click_on(locator)`

### Parameters
#### Path Parameters
- **locator** (string) - Required - The text or ID of the link or button to click.

### Request Example
```ruby
click_link('id-of-link')
click_link('Link Text')
click_button('Save')
click_on('Link Text')
click_on('Button Value')
```
```

--------------------------------

### Capybara Session Creation and Usage

Source: https://context7.com/teamcapybara/capybara/llms.txt

Create and manage user sessions for testing. Supports explicit session creation, multiple simultaneous sessions, and per-session configuration. Use `reset!` to clear state between tests.

```ruby
require 'capybara'

# Explicit session creation
session = Capybara::Session.new(:rack_test, MyRackApp)
session.visit('/login')
session.fill_in('Email', with: 'alice@example.com')
session.fill_in('Password', with: 'secret')
session.click_button('Sign in')
puts session.current_path          # => "/dashboard"
puts session.current_url           # => "http://127.0.0.1:PORT/dashboard"
puts session.html                  # full DOM snapshot

# Multiple simultaneous sessions (e.g. testing chat)
admin_session = Capybara::Session.new(:selenium_chrome_headless, App)
user_session  = Capybara::Session.new(:selenium_chrome_headless, App)

admin_session.visit('/admin')
user_session.visit('/chat')

# Threadsafe per-session config
Capybara.threadsafe = true
special_session = Capybara::Session.new(:selenium_chrome, MyApp) do |config|
  config.default_max_wait_time = 10
  config.app_host = 'http://staging.example.com'
end

# Reset between tests
session.reset!         # clears cookies, navigates to blank page
session.quit           # disconnect driver entirely
```

--------------------------------

### Handle Browser Prompts

Source: https://context7.com/teamcapybara/capybara/llms.txt

Accept a browser prompt dialog with a given response, or dismiss it. The action triggering the prompt must be within a block.

```ruby
accept_prompt with: 'My Name' do
  click_button 'Enter Name'
end
```

```ruby
message = dismiss_prompt do
  click_link 'Ask for Name'
end
puts message  # => "What is your name?"
```

--------------------------------

### XPath Contextual Selection with `within`

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Demonstrates correct usage of `.//` within a `within` block for XPath queries. This ensures selections are relative to the specified context.

```ruby
within(:xpath, '//body') do
  page.find(:xpath, './/script')
  within(:xpath, './/table/tbody') do
  ...
  end
end
```

--------------------------------

### all / first

Source: https://context7.com/teamcapybara/capybara/llms.txt

Retrieves all elements matching a selector, returning a Capybara::Result collection. The `first` method returns the first matching element or nil.

```APIDOC
## `all` / `first` — Find multiple elements

Returns a `Capybara::Result` collection of matching elements. Waits up to `default_max_wait_time` if count constraints are given; returns an empty result (not raising) when no count constraint is specified and no elements are found.

```ruby
# All matching links
links = all('a')
links.each { |a| puts a[:href] }

# With count constraints (raises if not satisfied after waiting)
rows = all('tr', minimum: 3)
cells = all('td.price', count: 5)
items = all('li', between: 2..8)

# Filter by text / visibility
labels = all('label', text: /required/i, visible: true)

# XPath
all(:xpath, './/input[@type="checkbox"]').each(&:check)

# First match (returns nil if minimum: 0 and nothing found)
first_error = first('.error-msg', minimum: 0)
puts first_error&.text

# Custom filter block
all(:field, 'Qty') { |el| el.value.to_i > 0 }
```
```

--------------------------------

### Form Actions: `fill_in`, `choose`, `check`, `uncheck`, `select`, `unselect`, `attach_file`

Source: https://context7.com/teamcapybara/capybara/llms.txt

Interact with form elements using semantic actions. Locators match by label text, name, id, placeholder, or `test_id`. `fill_in` supports multi-line text and conditional updates. `attach_file` handles file uploads, including hidden inputs.

```ruby
# Text inputs and textareas
fill_in 'First Name', with: 'Alice'
fill_in 'Bio',        with: "Multi\nline text"
fill_in 'Amount',     with: '99.99', currently_with: '0.00'  # only if current value matches

# Radio buttons
choose 'Female'
choose 'gender', option: 'female'  # by name + value

# Checkboxes
check 'I agree to the terms'
uncheck 'Send marketing emails'
check 'Remember me', allow_label_click: true  # click label if checkbox non-visible

# Select boxes (single and multiple)
select 'March', from: 'Month'
select 'English', from: 'language'
select 'German',  from: 'language'   # multiple select: call again for each
unselect 'English', from: 'language'

# File upload
attach_file 'Avatar', '/path/to/photo.png'
attach_file 'Documents', ['/path/a.pdf', '/path/b.pdf'], multiple: true
attach_file 'Resume', Rails.root.join('spec/fixtures/cv.pdf').to_s,
            make_visible: true   # temporarily show hidden file input

# Block form: trigger hidden file chooser via button click
attach_file('/path/to/file.pdf') do
  find('#upload-btn').click
end
```

--------------------------------

### Configure Capybara Server

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

When using Rails 5.0+ and not using system tests, it's recommended to set the server to Puma. Use the second option to silence test output.

```ruby
Capybara.server = :puma # Until your setup is working
```

```ruby
Capybara.server = :puma, { Silent: true } # To clean up your test output
```

--------------------------------

### Handle Browser Confirmations

Source: https://context7.com/teamcapybara/capybara/llms.txt

Accept or dismiss a browser confirmation dialog. The action triggering the confirmation must be within a block. Specify the expected confirmation text to match.

```ruby
accept_confirm do
  click_button 'Delete'
end
expect(page).to have_text 'Record deleted'
```

```ruby
dismiss_confirm 'Delete this item?' do
  click_button 'Delete'
end
expect(page).to have_text 'Deletion cancelled'
```

--------------------------------

### Minitest Integration with Capybara Assertions

Source: https://context7.com/teamcapybara/capybara/llms.txt

Provides Capybara's matchers as Minitest-compatible `assert_*` and `refute_*` methods. Include `capybara/minitest` and `Capybara::DSL`.

```ruby
require 'capybara/minitest'

class SignInTest < ActionDispatch::IntegrationTest
  include Capybara::DSL
  include Capybara::Minitest::Assertions

  teardown do
    Capybara.reset_sessions!
    Capybara.use_default_driver
  end

  def test_sign_in_with_valid_credentials
    visit '/sessions/new'
    fill_in 'Email',    with: 'alice@example.com'
    fill_in 'Password', with: 'secret'
    click_button 'Sign in'

    assert_current_path '/dashboard'
    assert_text 'Welcome, Alice'
    assert_selector 'nav.main'
    assert_title 'Dashboard'
    assert_no_text 'Sign in'
    assert_field 'Email', with: 'alice@example.com'   # still visible in form
    refute_selector '.error-banner'
    assert_css 'h1'
    assert_link 'Sign out'
    assert_button 'Profile'
    assert_checked_field 'Remember me'
  end
end
```

--------------------------------

### Semantic Shortcut Finders

Source: https://context7.com/teamcapybara/capybara/llms.txt

Use `find_field`, `find_link`, `find_button`, and `find_by_id` for more specific element searches. These methods accept various locators and options for precise matching.

```ruby
# find_field: by label text, name, id, placeholder, or test_id attribute
email_field = find_field('Email address')
email_field = find_field('user_email', type: 'email')
qty_field   = find_field('Quantity', with: '5')   # match current value
disabled_btn = find_field('Terms', disabled: true)
checked_box  = find_field('Newsletter', checked: true)

puts email_field.value    # => "alice@example.com"
email_field.set('bob@example.com')

# find_link: by text, title, id, alt (image links), or href
home_link = find_link('Home')
faq_link  = find_link('FAQ', href: '/faq')
img_link  = find_link(alt: 'Logo')
placeholder_link = find_link(href: nil)  # <a> without href

# find_button: by value, text, id, name, title, or alt (image inputs)
submit = find_button('Create Account')
cancel = find_button('Cancel', disabled: false)

# find_by_id: strict id match
main = find_by_id('main-content')
```

--------------------------------

### Modal Dialogs

Source: https://context7.com/teamcapybara/capybara/llms.txt

Handle browser alert, confirm, and prompt dialogs. These methods must wrap the action that triggers the dialog in a block.

```APIDOC
## Modal Dialogs — `accept_alert`, `accept_confirm`, `dismiss_confirm`, `accept_prompt`, `dismiss_prompt`

Handle browser alert, confirm, and prompt dialogs. Must wrap the action that triggers the dialog in a block.

```ruby
# Alert — accept only
message = accept_alert do
  click_button 'Show Alert'
end
puts message   # => "Are you sure?"

# Match alert text
accept_alert 'Warning: data will be lost' do
  click_link 'Delete Account'
end

# Confirm — accept or dismiss
accept_confirm do
  click_button 'Delete'
end
expect(page).to have_text 'Record deleted'

dismiss_confirm 'Delete this item?' do
  click_button 'Delete'
end
expect(page).to have_text 'Deletion cancelled'

# Prompt — provide a response
accept_prompt with: 'My Name' do
  click_button 'Enter Name'
end

message = dismiss_prompt do
  click_link 'Ask for Name'
end
puts message  # => "What is your name?"
```
```

--------------------------------

### Click Actions: click_link, click_button, click_on

Source: https://context7.com/teamcapybara/capybara/llms.txt

Use these methods to click links, buttons, or any element. They automatically wait for the target element to be interactable. You can disambiguate links by href or include disabled buttons in searches.

```ruby
click_link 'Sign in'
click_link 'Sign in', href: '/sessions/new'   # disambiguate by href

click_button 'Save'
click_button 'Save', disabled: :all           # include disabled buttons in search

click_on 'Delete'       # matches either a link or button
```

```ruby
# Element-level clicks with modifier keys and offsets
el = find('#map')
el.click
el.click(:shift)                  # shift-click
el.click(:control, :shift)        # multi-modifier
el.double_click
el.right_click
el.click(x: 10, y: 20)           # offset from center (w3c_click_offset: true) or top-left
el.hover
```

--------------------------------

### Window Management

Source: https://context7.com/teamcapybara/capybara/llms.txt

Manage multiple browser windows or tabs. This feature is only available with the Selenium driver.

```APIDOC
## Window Management — `windows`, `open_new_window`, `within_window`, `window_opened_by`

Manage multiple browser windows or tabs (Selenium only).

```ruby
# Open and switch to a new tab
new_win = open_new_window
within_window new_win do
  visit '/help'
  expect(page).to have_text 'Help Center'
end

# Capture a window opened by an action
popup = window_opened_by do
  click_link 'Open in new window'
end
within_window popup do
  expect(page).to have_current_path '/preview'
  popup.close
end

# Switch by window title
switch_to_window { title == 'Payment Gateway' }

# Enumerate all windows
windows.each do |win|
  within_window(win) { puts current_url }
end

# Wait for a window to close
popup = window_opened_by { click_button 'Popup' }
within_window popup do
  click_button 'Close'
end
expect(popup).to become_closed(wait: 2)
```
```

--------------------------------

### Capybara Navigation

Source: https://context7.com/teamcapybara/capybara/llms.txt

Navigate the browser using `visit`, `refresh`, `go_back`, and `go_forward`. `visit` handles both relative paths and absolute URLs, resolving relative paths against `app_host`.

```ruby
# With Capybara::DSL included (RSpec feature spec, Cucumber step, etc.)
visit '/products'
visit 'http://external-site.com/page'

puts current_url    # => "http://127.0.0.1:4567/products"
puts current_path   # => "/products"
puts current_host   # => "http://127.0.0.1:4567"
puts html           # => current DOM as string
puts status_code    # => 200  (rack_test only)
puts response_headers['Content-Type']  # rack_test only

refresh             # reload current page
go_back             # browser back
go_forward          # browser forward
```

--------------------------------

### Session - Capybara::Session.new

Source: https://context7.com/teamcapybara/capybara/llms.txt

Represents a single user's interaction with the application. Created automatically when using `Capybara::DSL`; can also be instantiated directly for multi-session testing.

```APIDOC
## Session - `Capybara::Session.new`

### Description
Represents a single user's interaction with the application. Created automatically when using `Capybara::DSL`; can also be instantiated directly for multi-session testing.

### Code Example
```ruby
require 'capybara'

# Explicit session creation
session = Capybara::Session.new(:rack_test, MyRackApp)
session.visit('/login')
session.fill_in('Email', with: 'alice@example.com')
session.fill_in('Password', with: 'secret')
session.click_button('Sign in')
puts session.current_path          # => "/dashboard"
puts session.current_url           # => "http://127.0.0.1:PORT/dashboard"
puts session.html                  # full DOM snapshot

# Multiple simultaneous sessions (e.g. testing chat)
admin_session = Capybara::Session.new(:selenium_chrome_headless, App)
user_session  = Capybara::Session.new(:selenium_chrome_headless, App)

admin_session.visit('/admin')
user_session.visit('/chat')

# Threadsafe per-session config
Capybara.threadsafe = true
special_session = Capybara::Session.new(:selenium_chrome, MyApp) do |config|
  config.default_max_wait_time = 10
  config.app_host = 'http://staging.example.com'
end

# Reset between tests
session.reset!         # clears cookies, navigates to blank page
session.quit           # disconnect driver entirely
```
```

--------------------------------

### Focusing a Single Test in Development

Source: https://github.com/teamcapybara/capybara/blob/master/CONTRIBUTING.md

Use the `:focus_` metadata to run a specific test or scenario during development. This helps isolate and debug individual tests without running the entire suite.

```ruby
it 'should simulate multiple held down modifier keys', :focus_ do
```

--------------------------------

### Find Elements by Various Attributes

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Use `find_field`, `find_link`, `find_button`, and `find` with different selectors (ID, class, XPath, CSS) to locate elements. `all` finds all matching elements. Elements are found with waiting behavior.

```ruby
find_field('First Name').value
find_field(id: 'my_field').value
find_link('Hello', :visible => :all).visible?
find_link(class: ['some_class', 'some_other_class'], :visible => :all).visible?

find_button('Send').click
find_button(value: '1234').click

find(:xpath, ".//table/tr").click
find("#overlay").find("h1").click
all('a').each { |a| a[:href] }
```

--------------------------------

### Configure Capybara for Rack Apps

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

For non-Rails Rack applications, set `Capybara.app` to your Rack app instance.

```ruby
Capybara.app = MyRackApp
```

--------------------------------

### Executing JavaScript

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Use `page.execute_script` to run arbitrary JavaScript. For simple expressions, `page.evaluate_script` can return a value. More complex scripts can be passed as a single expression, potentially with arguments.

```ruby
page.execute_script("$('body').empty()")
```

```ruby
result = page.evaluate_script('4 + 4')
```

```ruby
result = page.evaluate_script(<<~JS, 3, element)
  (function(n, el){
    var val = parseInt(el.value, 10);
    return n+val;
  })(arguments[0], arguments[1])
JS
```

--------------------------------

### Save and Open Screenshot

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Saves a screenshot and automatically opens it. Useful for immediate visual debugging.

```ruby
save_and_open_screenshot
```

--------------------------------

### Switching Drivers in RSpec

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Use `js: true` to enable the JavaScript driver or specify a `:driver` option for a particular driver.

```ruby
describe 'some stuff which requires js', js: true do
  it 'will use the default js driver'
  it 'will switch to one specific driver', driver: :selenium
end
```

--------------------------------

### Configure Capybara to Use a Remote Server

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Set the application host to interact with a web server running remotely. The default `:rack_test` driver does not support this.

```ruby
Capybara.current_driver = :selenium
Capybara.app_host = 'http://www.google.com'
...
visit('/')
```

--------------------------------

### Interacting with Forms

Source: https://github.com/teamcapybara/capybara/blob/master/README.md

Provides methods to fill in form fields, select options, and manage checkboxes and radio buttons.

```APIDOC
## Interacting with Forms

### Description
Tools for interacting with form elements such as text fields, select boxes, checkboxes, and radio buttons.

### Methods
- `fill_in(locator, with: value)`
- `choose(locator)`
- `check(locator)`
- `uncheck(locator)`
- `attach_file(locator, path)`
- `select(option, from: locator)`

### Parameters
#### Path Parameters
- **locator** (string) - Required - The label or ID of the form element.
- **option** (string) - Required - The option to select from a dropdown.
- **path** (string) - Required - The file path for `attach_file`.

#### Request Body
- **with** (string) - Required - The value to fill into the form field.

### Request Example
```ruby
fill_in('First Name', with: 'John')
fill_in('Password', with: 'Seekrit')
choose('A Radio Button')
check('A Checkbox')
uncheck('A Checkbox')
attach_file('Image', '/path/to/image.jpg')
select('Option', from: 'Select Box')
```
```