215 Browser automation with Capybara and Selenium WebDriver [2d]

We use Selenium WebDriver Show archive.org snapshot with Capybara for end-to-end tests that need a real browser.

Important

Work on this lesson in advisor mode.

Learning goals

• You can explain how Capybara drives a browser, how its drivers differ (e.g. rack_test vs. Selenium), and when a feature spec needs a real browser.
• You can run a feature spec in a real browser, headless or visible, and watch what it does.
• You can explain why browser tests are flaky by nature — asynchronous JavaScript, timing, and the app and the browser running in separate threads or processes — and how Capybara's waiting and retrying counters that.
• You can diagnose and fix a flaky feature spec with our standard toolbox, e.g. capybara-lockstep and waiting finders instead of sleep.
• You can handle browser dialogs, file downloads and screenshots in a feature spec.
• You can explain how the app and the browser share one test database and how it is reset between examples.
• You know what running tests in parallel and on a CI server requires from your test setup.

Resources

Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.

Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.

Capybara

• 📄 Capybara README Show archive.org snapshot — read The DSL, Matching, Asynchronous JavaScript (Ajax and friends) for the waiting/retry mechanism, Transactions and database setup, and Drivers (rack_test vs. Selenium)
• 📄 Feature specs in rspec-rails Show archive.org snapshot — how a feature spec is set up, and how js: true switches an example to the JavaScript driver
• 📄 Waiting for it with Capybara's synchronize method Show archive.org snapshot — matchers poll, actions run once; the three processes involved (test runner, app server, browser); synchronize for coupled interactions
• 📄 Capybara::Node::Finders Show archive.org snapshot and Capybara::Node::Matchers Show archive.org snapshot — the API reference
• 📄 The two drivers as gems: rack-test Show archive.org snapshot and selenium-webdriver Show archive.org snapshot

Flaky tests and our toolbox

• 📄 Fixing flaky E2E tests — our card on why browser tests flake and how to fix them
• ▶️ Fixing Flaky E2E Tests Show archive.org snapshot — the same content as a talk
• 📄 capybara-lockstep — our card, and the gem's README Show archive.org snapshot : what problem it solves and how it keeps requests from bleeding between steps
• 📄 Threads and processes in a Capybara/Selenium session
• 📄 Run Selenium tests in Chrome and running tests in headless Chrome
• 📄 parallel_tests Show archive.org snapshot — running the suite on several CPU cores; what it needs from your test setup

Dialogs, downloads, screenshots

• 📄 Configure Selenium to not automatically close alerts and accept or deny confirmation dialogs — Capybara cannot interact with the page while a blocking dialog is open
• 📄 Testing file downloads
• 📄 Taking screenshots in Capybara
• 📄 evaluate_script might freeze your browser, use execute_script
• 📄 Specify the size of the Selenium browser window
• 📄 Mock the browser time or time zone

Exercises

Watch it run

Your counter spec from Working with the DOM runs in a real browser: its js: true metadata switches Capybara from Rack::Test to the Selenium driver, which remote-controls Chrome. By default Chrome runs headless, so you never see it.

Run the counter spec with NO_HEADLESS=1 geordi rspec spec/features/... and watch Capybara visit the page and click the button. Get someone to help you if no browser opens.

Dialogs, downloads, screenshots

• Ask before a movie is deleted: show a confirm() dialog with your own JavaScript. Write a js: true spec for both outcomes, using accept_confirm and dismiss_confirm.
• Click "Export as CSV" from Basic file uploads and image versions in a js: true spec, and check the content of the downloaded file. Your MovieDB tells Chrome to save downloads to /tmp (see spec/support/capybara.rb).
• Break a js: true spec on purpose. Find the screenshot and the HTML page that capybara-screenshot saved to tmp/capybara, and open both.

Learn from real flaky fixes

Our colleagues have fixed many flaky specs in the makandra cards app, which you cloned in an earlier lesson. Find these fixes with git log -i --grep=flak. Most of them change only a few lines.

Pick three commits with different causes. For each, explain:

• What made the spec flaky?
• Why did it pass most of the time?
• Why does the fix work?

Then find out how the app sets up capybara-lockstep, and explain what it makes Capybara wait for.