Workflow:Teamcapybara Capybara Element Finding And Interaction
| Knowledge Sources | |
|---|---|
| Domains | Testing, Web_Automation, DOM_Querying |
| Last Updated | 2026-02-12 06:00 GMT |
Overview
End-to-end process for locating DOM elements on a page and performing interactions with them using Capybara's finder, action, and matcher APIs.
Description
This workflow covers the core usage pattern of Capybara: finding elements on a web page and interacting with them. It traces the flow from the DSL layer through the Session, into the Node hierarchy (Finders, Actions, Matchers), through the query resolution engine (SelectorQuery), and down to the driver layer. The workflow includes Capybara's automatic waiting/retry mechanism (synchronize) that handles asynchronous JavaScript by retrying element lookups until they succeed or a timeout expires.
Usage
Execute this workflow whenever you need to locate specific elements on a page and interact with them in a test. This is the most common Capybara usage pattern — virtually every test uses some combination of finding elements, performing actions, and asserting element state.
Execution Steps
Use visit to navigate the session to the target URL. The session delegates to the driver, which loads the page. If the driver requires a server (e.g., Selenium), the embedded Rack server is automatically booted to serve the application.
Key considerations:
- visit only supports GET requests
- The URL can be a path (relative to the app) or an absolute URL
- For non-Rack apps, set Capybara.app_host to the remote server URL
- The page is fully loaded when visit returns (for synchronous drivers)
Step 2: Locate_Element
Use finder methods (find, all, find_field, find_button, find_link, find_by_id, first) to locate elements. The finder constructs a SelectorQuery which resolves the selector name to a built-in or custom selector definition, generates a CSS or XPath expression, and delegates to the driver to search the DOM.
Key considerations:
- find returns a single element and raises ElementNotFound if not found
- all returns a lazy Result collection of matching elements
- first returns the first matching element (or nil)
- Finders accept a selector name (:css, :xpath, :button, :field, etc.) and a locator
- Filters (text, visible, id, class, style) further constrain results
- The default selector is :css (configurable via Capybara.default_selector)
Step 3: Auto_Wait_And_Retry
When a finder or matcher fails, Capybara's synchronize mechanism catches the exception and retries the operation. It continues retrying until the element is found or default_max_wait_time expires. This is the core defense against asynchronous JavaScript timing issues.
What happens:
- The synchronize block wraps the finder/matcher call
- On ElementNotFound (or driver-specific stale element errors), the block is retried
- The retry interval is controlled by default_retry_interval
- If automatic_reload is enabled, stale node references are refreshed before retrying
- For non-waiting drivers (RackTest), errors bubble up immediately without retrying
Step 4: Interact_With_Element
Once an element is found, perform actions on it using the Actions module methods. Actions include clicking (click, double_click, right_click), typing (set, send_keys), selecting (select_option, unselect_option), file attachment, and drag-and-drop. Each action delegates to the driver's node implementation.
Key considerations:
- click supports modifier keys (:alt, :ctrl, :meta, :shift)
- set handles input fields, textareas, and content-editable elements
- send_keys dispatches keyboard events including special keys (:enter, :tab, etc.)
- drag_to performs drag-and-drop between elements
- Actions trigger the same auto-wait behavior for element resolution
Step 5: Assert_Element_State
Use matcher methods to verify element state. Matchers include has_selector?, has_text?, has_css?, has_xpath?, and their assertion forms (assert_selector, assert_text). In RSpec, use expect(page).to have_selector(...) which integrates with Capybara's waiting behavior.
Key considerations:
- Matchers use synchronize internally, so they auto-wait for async changes
- has_no_selector? is different from !has_selector? — the former waits for absence, the latter does not
- Count options (count, minimum, maximum, between) control expected match counts
- RSpec matchers (have_selector, have_text, have_css) handle both positive and negative expectations correctly
Step 6: Scope_And_Chain
Restrict operations to a subtree of the DOM using within blocks or by chaining finders. within sets a temporary scope so that all finders and actions operate only within the matching container element. Elements returned by find also serve as scoping roots for further queries.
Key considerations:
- within accepts the same selector arguments as find
- within_fieldset and within_table are specialized scoping methods
- Scoping is implemented via the query_scope chain on Node::Base
- Nested within blocks create nested scopes
- XPath expressions inside within should use ./ prefix, not //