Free tools Windows power users keep installed
One-click scans. No signup required.
Use Cypress’s built-in selectFile() command to attach a file to an HTML file input or simulate dropping one onto a drop zone. For a file already in your project, the basic form is cy.get('input[type="file"]').selectFile('cypress/fixtures/example.pdf'); the path is relative to the project root.
Upload a file through a standard input
For the common browser upload flow, query the file input and pass the path to a fixture or other project file:
As an Amazon Associate I earn from qualifying purchases.
cy.get('input[type="file"]').selectFile('cypress/fixtures/file.json')Cypress reads the file from disk and attaches it to the input. A path is generally the simplest choice for an existing fixture and avoids loading file bytes into the test first. Paths are relative to the project root—the directory containing the Cypress configuration file. See the selectFile() API for the supported forms and options.
selectFile() was added in Cypress 9.3.0. Check the version installed in your project if an option or input form is unavailable; TypedArray and mimeType support were added in 9.4.0.
Handle hidden file inputs
Upload interfaces often hide the actual input[type="file"] and expose a styled button. If you intend to set the input directly, bypass Cypress actionability checks with { force: true }:
cy.get('input[type="file"]').selectFile('cypress/fixtures/file.json', { force: true })This sets the selected file on the hidden input; it does not test clicking the visible button. If the visible control itself is part of the behavior you need to verify, test that interaction separately and assert the resulting upload state.
Simulate drag-and-drop
For a drop zone, use action: 'drag-drop'. The subject can be any DOM element:
Recommended Free Tools
cy.get('[data-cy="drop-zone"]').selectFile('cypress/fixtures/file.json', {
action: 'drag-drop',
})This simulates dragging a file from the operating system into the browser and dropping it over the chosen element. If the application listens for drop events at the document level, target body; the events bubble to document listeners:
cy.get('body').selectFile('cypress/fixtures/file.json', {
action: 'drag-drop',
})Choose how to supply file contents
Use a project file path
When a representative file already exists in your project, pass its path directly. Cypress checks that the file exists and retries reading it until it appears or the command times out.
Use a fixture alias
You can load a fixture and pass its alias to selectFile(). For binary files, request a Buffer with a null encoding so text decoding does not alter the bytes:
cy.fixture('file.json', null).as('myFixture')
cy.get('input[type="file"]').selectFile('@myFixture')For large upload simulations, Cypress recommends using the fixture path rather than loading the contents first.
Read file bytes
cy.readFile(path, null) returns a Cypress.Buffer irrespective of the file extension. Use this when the test needs the bytes themselves:
cy.readFile('cypress/fixtures/image.png', null).then((bytes) => {
cy.get('input[type="file"]').selectFile(bytes)
})Build a file during the test
Pass an object with contents when you need dynamic bytes or specific file metadata. This example creates a text file with a controlled name, MIME type and modification time:
cy.get('input[type="file"]').selectFile({
contents: Cypress.Buffer.from('test file contents'),
fileName: 'sample.txt',
mimeType: 'text/plain',
lastModified: new Date('2024-01-01').valueOf(),
})lastModified is expressed in milliseconds since the Unix epoch and defaults to the current time. Cypress infers the MIME type from the file extension when possible; if it cannot infer one, the type defaults to an empty string unless you provide mimeType. A plain string in the supported path form means a disk path, not literal file text—use a structured object or Buffer when you mean contents.
Upload multiple files
Pass an array of paths, and make sure the input has the multiple property. Without it, selecting several files fails:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →cy.get('input[type="file"][multiple]').selectFile([
'cypress/fixtures/first.json',
'cypress/fixtures/second.json',
])Use object entries in the array when files need distinct names, MIME types or modification timestamps. That lets a test exercise file metadata validation as well as selection.
What Cypress waits for—and what to assert next
selectFile() follows Cypress actionability rules and automatically waits for its target to become actionable. It can time out while waiting for actionability, a disk path to appear, or an aliased value to become available; an alias must not resolve to null or undefined.
The command yields the subject it received, but Cypress warns that chaining commands that depend on that same subject after selection is unsafe. Start a fresh query for follow-up checks, such as the application’s filename display, validation message or upload status.
Choose between browser selection and a direct API upload
Use selectFile() when the test needs to cover the browser’s file input or drop-zone behavior. If the test only needs to send a multipart upload to the server endpoint, Cypress documents using cy.request() with a FormData object instead. That tests the endpoint without exercising browser file selection.
Troubleshoot common failures
- File path not found: Make the path relative to the project root and confirm the file exists there. Cypress retries reading it until the command times out.
- Element is hidden or not actionable: If the intended test is to set the hidden input, use
{ force: true }. Do not treat that as a test of clicking the visible upload control. - Several files are rejected: Confirm the input has the
multipleproperty before passing an array. - Binary upload contents are corrupted: Load the file with
nullencoding usingcy.fixture()orcy.readFile(), or use the disk-path form. - Drop-zone handler does not run: Confirm the selected element is the drop target. If the handler is attached at document level, use
bodyas the subject. - Alias-based selection fails: Ensure the alias exists and does not resolve to
nullorundefined. - Follow-up assertion behaves unexpectedly: Query the page again after
selectFile()instead of relying on the yielded subject.
Or skip the browser setup
If your goal is to capture a page screenshot rather than test an upload interaction, ScreenshotNeo provides a one-request screenshot API and an MCP server for AI agents. Its response identifies whether a request was billed and whether the page was clean, a bot check, blank, failed or served from cache.
For example, with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, popups and chat widgets are removed before capture; bot checks, blank pages and failed loads are never billed. An MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Can I use selectFile() with a Cypress fixture?
Yes. Pass a fixture path directly, or load the fixture as a Buffer with null encoding and pass its alias.
Does selectFile() upload to my server by itself?
It selects or drops the file in the browser UI. Your application must handle the resulting browser event and send the upload request.
Can selectFile() simulate dragging a file into a page?
Yes. Set action to ‘drag-drop’ and select the drop target, or use body for page-level drop listeners.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
