Implementation:Teamcapybara Capybara Node Actions Attach File

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

Overview

Concrete tool for attaching files to file input elements provided by Capybara::Node::Actions#attach_file.

Description

Node::Actions#attach_file validates file existence, then locates the file input via :file_field selector. When make_visible is provided, it uses while_visible to temporarily apply CSS overrides (opacity: 1, display: 'block', visibility: 'visible' by default). Block mode injects JavaScript (CAPTURE_FILE_ELEMENT_SCRIPT) to intercept the file input that gets clicked.

Usage

Call with a locator and file path(s). Use make_visible: true for hidden inputs, or a block for custom file chooser triggers.

Code Reference

Source Location

• Repository: capybara
• File: lib/capybara/node/actions.rb
• Lines: L279-306

Signature

def attach_file(locator = nil, paths, make_visible: nil, **options)
  # @param locator [String, nil] Name, id, test_id, or label of file field
  # @param paths [String, Array<String>] File path(s) to attach
  # @param make_visible [Boolean, Hash] CSS overrides to make hidden input visible
  # @param options [Hash] Standard find options
  # @yield Block that triggers the file chooser (beta)
  # @return [Capybara::Node::Element] The file field element
  # @raise [Capybara::FileNotFound] If file path doesn't exist
end

Import

require 'capybara'

I/O Contract

Inputs

Name	Type	Required	Description
locator	String/nil	No	File field identifier
paths	String/Array<String>	Yes	File path(s) to attach
make_visible	Boolean/Hash	No	CSS overrides for hidden inputs
multiple	Boolean	No	Match multi-file inputs

Outputs

Name	Type	Description
element	Capybara::Node::Element	The file field element with file attached

Usage Examples

Direct Attachment

attach_file 'Avatar', '/path/to/avatar.png'
attach_file 'Documents', ['/path/to/doc1.pdf', '/path/to/doc2.pdf']

Hidden File Input

attach_file 'Photo', '/path/to/photo.jpg', make_visible: true

# With custom CSS overrides
attach_file 'Upload', '/path/to/file.txt',
  make_visible: { opacity: 1, display: 'block', position: 'static' }

Block Mode

attach_file('/path/to/file.pdf') do
  click_button 'Choose File'  # triggers the file chooser
end

Related Pages

Implements Principle

• Principle:Teamcapybara_Capybara_File_Uploads