Name: <%= @name %>
Email: <%= @email %>
Back to Home ``` Add an about page: ```erb [label views/about.erb]This is a demonstration application for Capybara testing.
Home ``` Now configure RSpec and Capybara by creating a `spec/spec_helper.rb` file: ```command mkdir spec ``` ```ruby [label spec/spec_helper.rb] require 'capybara/rspec' require_relative '../app' Capybara.app = Sinatra::Application # Allow requests to localhost and 127.0.0.1 Capybara.server_host = '127.0.0.1' Capybara.app_host = "http://#{Capybara.server_host}" RSpec.configure do |config| config.include Capybara::DSL end ``` This configuration tells Capybara which application to test and integrates it with RSpec. The `Capybara.app` assignment points to your Sinatra application, while `config.include Capybara::DSL` makes Capybara's methods available in your tests. Create your first test file: ```ruby [label spec/features/homepage_spec.rb] require 'spec_helper' RSpec.describe 'Homepage', type: :feature do it 'displays the welcome message' do visit '/' expect(page).to have_content('Welcome to Capybara Testing') end end ``` Run the test suite: ```command bundle exec rspec ``` You should see output confirming your test passed: ```text [output] . Finished in 0.01252 seconds (files took 0.37013 seconds to load) 1 example, 0 failures ``` The test you just wrote demonstrates Capybara's fundamental workflow: visit a page, interact with it, and verify the expected outcome. The `visit` method loads the specified URL, while `have_content` checks if the page contains specific text. ## Understanding Capybara's driver architecture Capybara's flexibility comes from its driver system, which allows you to switch between different browser automation backends without rewriting your tests. Each driver offers different capabilities and trade-offs in terms of speed, JavaScript support, and debugging features. The default driver is `:rack_test`, which provides extremely fast test execution by bypassing actual browser rendering. This driver directly tests your Rack application without JavaScript support, making it ideal for testing server-rendered pages and basic interactions: ```ruby [label spec/features/navigation_spec.rb] require 'spec_helper' RSpec.describe 'Navigation', type: :feature do it 'navigates to the about page' do visit '/' click_link 'About Page' expect(page).to have_content('About This Application') expect(current_path).to eq('/about') end end ``` This test runs in milliseconds because `:rack_test` doesn't start an actual browser. However, if your application relies heavily on JavaScript, you'll need a driver that supports it. ### Configuring Selenium WebDriver For testing JavaScript functionality, Capybara integrates seamlessly with Selenium WebDriver. You need to register a custom Selenium driver in your spec helper file. Open your `spec/spec_helper.rb` file and add the Selenium configuration below the existing Capybara setup: ```ruby [label spec/spec_helper.rb] require 'capybara/rspec' require_relative '../app' Capybara.app = Sinatra::Application # Allow requests to localhost and 127.0.0.1 Capybara.server_host = '127.0.0.1' Capybara.app_host = "http://#{Capybara.server_host}" [highlight] Capybara.register_driver :selenium_chrome_headless do |app| options = Selenium::WebDriver::Chrome::Options.new options.add_argument('--headless') options.add_argument('--disable-gpu') options.add_argument('--no-sandbox') Capybara::Selenium::Driver.new(app, browser: :chrome, options: options) end Capybara.javascript_driver = :selenium_chrome_headless [/highlight] RSpec.configure do |config| config.include Capybara::DSL end ``` This configuration creates a custom Selenium driver that runs Chrome in headless mode. The headless option means the browser runs without a graphical interface, significantly speeding up test execution while still providing full JavaScript support. You can mark individual tests to use the JavaScript driver by adding `js: true` metadata: ```ruby it 'handles dynamic content', js: true do visit '/dynamic-page' # This test will use Selenium instead of rack_test end ``` ### Choosing the right driver Different scenarios call for different drivers. Use `:rack_test` for: - Testing server-rendered HTML pages - Form submissions without JavaScript - Basic navigation and link clicking - Scenarios where maximum speed is critical Switch to Selenium (or similar JavaScript-capable drivers) when: - Testing single-page applications - Verifying JavaScript-driven interactions - Testing AJAX requests and responses - Debugging complex browser behavior The ability to mix drivers within the same test suite gives you the best of both worlds: fast execution for simple tests and comprehensive JavaScript support when needed. ## Finding and interacting with page elements Capybara provides multiple strategies for locating elements on your pages, each with specific use cases and advantages. Understanding when to use each finder helps you write more reliable and maintainable tests. ### Using semantic finders The most robust approach involves using Capybara's semantic finders, which locate elements based on their purpose rather than implementation details. Create a new test file to demonstrate form interactions: ```command touch spec/features/form_interaction_spec.rb ``` Add the following test code: ```ruby [label spec/features/form_interaction_spec.rb] require 'spec_helper' RSpec.describe 'Form Interaction', type: :feature do it 'submits the contact form successfully' do visit '/' fill_in 'Name', with: 'Jane Smith' fill_in 'Email', with: 'jane@example.com' click_button 'Submit Form' expect(page).to have_content('Thank You!') expect(page).to have_content('Jane Smith') expect(page).to have_content('jane@example.com') end end ``` Run your tests to verify everything works: ```command bundle exec rspec ``` You should see three passing tests: ```text [output] ... Finished in 0.02507 seconds (files took 0.37043 seconds to load) 3 examples, 0 failures ``` This approach uses the visible labels on your form rather than IDs or CSS classes. The `fill_in` method can locate inputs by their label text, placeholder, or name attribute, making your tests resilient to implementation changes. ### Alternative element selectors When semantic finders aren't sufficient, Capybara offers several other locator strategies. Open your existing `spec/features/form_interaction_spec.rb` file and add a new test to demonstrate these different approaches: ```ruby [label spec/features/form_interaction_spec.rb] require 'spec_helper' RSpec.describe 'Form Interaction', type: :feature do it 'submits the contact form successfully' do visit '/' fill_in 'Name', with: 'Jane Smith' fill_in 'Email', with: 'jane@example.com' click_button 'Submit Form' expect(page).to have_content('Thank You!') expect(page).to have_content('Jane Smith') expect(page).to have_content('jane@example.com') end [highlight] it 'demonstrates different selector types' do visit '/' # Find by ID find('#name').set('John Doe') # Find by CSS selector find('input[type="email"]').set('john@example.com') # Find by XPath find(:xpath, '//button[@type="submit"]').click expect(page).to have_content('Thank You!') expect(page).to have_content('John Doe') end [/highlight] end ``` Run the tests again: ```command bundle exec rspec ``` You should now see four passing tests: ```text [output] .... Finished in 0.03164 seconds (files took 0.41572 seconds to load) 4 examples, 0 failures ``` Using `data-` attributes specifically for testing is often recommended because they make your selectors immune to styling changes while clearly documenting which elements are used in tests. For example, you could add `data-test-id="submit-button"` to your button and find it with `find('[data-test-id="submit"]')`. ### Scoping interactions You can scope your interactions to specific sections of the page using `within` blocks, which is particularly useful for complex pages with repeating elements. The `within` block ensures that Capybara only searches for elements inside the specified container, preventing accidental interactions with similarly-named elements elsewhere on the page. Here's an example that demonstrates scoping (this is just an illustration—you don't need to add this to your test suite right now): ```ruby it 'interacts with elements within a specific section' do visit '/dashboard' within('.user-profile') do expect(page).to have_content('Profile Information') click_link 'Edit Profile' end within('#edit-form') do fill_in 'Username', with: 'newusername' click_button 'Save Changes' end end ``` ## Handling asynchronous behavior and waiting One of Capybara's most valuable features is its automatic waiting mechanism, which dramatically reduces flaky tests caused by timing issues. Understanding how this works helps you write more reliable tests. ### Automatic waiting behavior By default, Capybara waits up to 2 seconds for elements to appear before failing. This happens transparently whenever you use finder methods. Let's see this in action by creating a page with delayed content. First, update your `Gemfile` to add the `puma` gem: ```ruby [label Gemfile] source 'https://rubygems.org' gem 'sinatra', '~> 4.0' gem 'capybara', '~> 3.40' gem 'rspec', '~> 3.13' gem 'selenium-webdriver', '~> 4.25' [highlight] gem 'puma', '~> 6.4' [/highlight] ``` Install the gem: ```command bundle install ``` Now update your `spec/spec_helper.rb` to require selenium-webdriver: ```ruby [label spec/spec_helper.rb] require 'capybara/rspec' [highlight] require 'selenium-webdriver' [/highlight] require_relative '../app' Capybara.app = Sinatra::Application # Allow requests to localhost and 127.0.0.1 Capybara.server_host = '127.0.0.1' [highlight] # Remove this line: Capybara.app_host = "http://#{Capybara.server_host}" [/highlight] Capybara.register_driver :selenium_chrome_headless do |app| options = Selenium::WebDriver::Chrome::Options.new options.add_argument('--headless') options.add_argument('--disable-gpu') options.add_argument('--no-sandbox') Capybara::Selenium::Driver.new(app, browser: :chrome, options: options) end Capybara.javascript_driver = :selenium_chrome_headless [highlight] Capybara.default_max_wait_time = 5 [/highlight] RSpec.configure do |config| config.include Capybara::DSL end ``` Update your `app.rb` file to add a new route: ```ruby [label app.rb] require 'sinatra' get '/' do erb :index end post '/submit' do @name = params[:name] @email = params[:email] erb :result end get '/about' do erb :about end [highlight] get '/delayed' do erb :delayed end [/highlight] ``` Create a new view that simulates delayed content: ```erb [label views/delayed.erb]