Principle:Teamcapybara Capybara File Uploads

Knowledge Sources	Capybara README
Domains	Testing, Form_Interaction
Last Updated	2026-02-12 00:00 GMT

Overview

A form interaction pattern for attaching files to file input elements, including handling hidden inputs and custom file chooser triggers.

Description

File Uploads handles the complexity of file input elements which are often hidden for styling reasons. The pattern supports three modes:

1. Direct locator — Find a file input by label/name/id and set its value to a file path
2. Make visible — Temporarily change CSS properties to make a hidden file input visible, attach the file, then revert CSS
3. Block mode — Execute a block that triggers the file chooser (e.g., clicking a styled button), then attach to whatever file input was activated

The method validates that file paths exist on disk and raises Capybara::FileNotFound for missing files.

Usage

Use for file upload fields. The make_visible option is particularly useful for modern web apps that style file inputs behind custom buttons.

Theoretical Basis

# Abstract file upload flow (not actual code)
attach_file(locator, paths, make_visible:):
  validate paths exist on disk

  if block_given:
    inject JS to capture file input click
    yield (user action triggers file chooser)
    file_field = captured file input
  else:
    file_field = find(:file_field, locator)

  if make_visible:
    temporarily_change_css(file_field, visible_styles)
    file_field.set(paths)
    revert_css
  else:
    file_field.set(paths)

Related Pages

Implemented By

• Implementation:Teamcapybara_Capybara_Node_Actions_Attach_File