Workflow:Teamcapybara Capybara Form Testing
| Knowledge Sources | |
|---|---|
| Domains | Testing, Web_Automation, Form_Interaction |
| Last Updated | 2026-02-12 06:00 GMT |
Overview
End-to-end process for testing HTML form interactions including text input, selection controls, checkboxes, radio buttons, file uploads, and form submission using Capybara's Actions API.
Description
This workflow covers the complete pattern for testing web forms with Capybara. It walks through navigating to a form, filling in text fields, interacting with selection controls, handling file uploads, submitting the form, and verifying the result. Each form interaction method in Capybara locates the target field using built-in selectors (:fillable_field, :checkbox, :radio_button, :select, :file_field) that match by label text, id, name, or placeholder, then delegates to the driver node to perform the actual interaction.
Usage
Execute this workflow when you need to test any form-based user interaction in your web application — user registration, login, search, data entry, file upload, or any page that involves filling in and submitting an HTML form.
Execution Steps
Use visit to navigate to the page containing the target form. Optionally use within to scope subsequent operations to a specific form element if the page contains multiple forms.
Key considerations:
- Navigate to the URL that renders the form
- Use within("form#my_form") or within_fieldset("Section Name") to scope to a specific form
- This prevents ambiguity when multiple forms exist on the same page
Step 2: Fill_In_Text_Fields
Use fill_in to populate text inputs and textareas. The method locates fields by label text, name attribute, id attribute, or placeholder text, then sets the value via the driver. For fields that need clearing first, fill_in handles this automatically.
Key considerations:
- fill_in 'Label Text', with: 'value' finds by associated label
- The currently_with option can filter by current value before filling
- fill_options can specify additional driver-specific behavior (e.g., clear method for Selenium)
- For content-editable elements, use find + set instead
Step 3: Interact_With_Selection_Controls
Use select and unselect for dropdown menus, check and uncheck for checkboxes, and choose for radio buttons. Each method locates the control using its specific built-in selector and triggers the appropriate state change via the driver.
Key considerations:
- select 'Option Text', from: 'Select Label' selects an option in a dropdown
- check 'Checkbox Label' and uncheck 'Checkbox Label' toggle checkboxes
- choose 'Radio Label' selects a radio button
- allow_label_click: true (default) clicks the associated label if the element itself is not interactable
- For multi-select fields, call select multiple times
Step 4: Handle_File_Uploads
Use attach_file to set files on file input fields. The method locates the file input and sets its value to the specified file path(s). For hidden file inputs or drag-and-drop upload zones, make_visible option can temporarily reveal the input.
Key considerations:
- attach_file 'Field Label', '/path/to/file.jpg' attaches a single file
- Pass an array of paths for multi-file inputs
- make_visible: true temporarily overrides CSS to make hidden file inputs interactable
- The file path must be absolute or relative to the working directory
Step 5: Submit_Form
Use click_button to find and click the form's submit button, triggering form submission. The button is found by its value, text, id, name, or title. Capybara automatically follows any resulting redirects.
Key considerations:
- click_button 'Submit' finds by button text or value
- click_on can be used to click either a link or a button
- For forms submitted via JavaScript, the auto-wait mechanism handles the async response
- The RackTest driver simulates form serialization and submission via Rack
Step 6: Verify_Submission_Result
After form submission, use matchers to verify the expected outcome. Check for success messages, redirects to expected paths, or the presence/absence of specific content. Use have_current_path for URL assertions and have_text/have_content for page content.
Key considerations:
- expect(page).to have_current_path('/success') verifies the redirect destination
- expect(page).to have_content('Successfully created') checks for success message
- expect(page).to have_no_content('Error') verifies no error messages appear
- All matchers auto-wait, handling async redirects and page updates