--- id: api/commands/readfile title: readFile | Cypress Documentation description: Read a file and yield its contents in Cypress. section: api source_path: docs/api/commands/readfile.mdx version: 24a73f8a97175663aaffd3b016289fb2a523a4ea updated_at: '2026-05-14T20:17:33.301Z' --- # readFile Read a file and yield its contents. ## Syntax ``` cy.readFile(filePath)cy.readFile(filePath, encoding)cy.readFile(filePath, options)cy.readFile(filePath, encoding, options) ``` ### Usage **Correct Usage** ``` cy.readFile('menu.json') ``` ### Arguments **filePath _(String)_** A path to a file within the project root (the directory that contains the [Cypress configuration file](/llm/markdown/app/references/configuration.md)). **encoding _(String)_** The encoding to be used when reading the file. The following encodings are supported: * `'ascii'` * `'base64'` * `'binary'` * `'hex'` * `'latin1'` * `'utf8'` * `'utf-8'` * `'ucs2'` * `'ucs-2'` * `'utf16le'` * `'utf-16le'` * `null` Using `null` explicitly will return the file as a [`Cypress.Buffer`](/llm/markdown/api/utilities/buffer.md) instance, regardless of file extension. **options _(Object)_** Pass in an options object to change the default behavior of `cy.readFile()`. | Option | Default | Description | | --- | --- | --- | | `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) | | `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.readFile()` to resolve before [timing out](#Timeouts) | ### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management) * `cy.readFile()` yields the contents of the file. * The file will be read from disk again if any upcoming command (such as an assertion) in the chain fails. ## Examples ### Text #### Read a `.txt` file For any file other than JSON, the contents of the file are returned. ``` // path/to/message.txtHello World ``` ``` cy.readFile('path/to/message.txt').should('eq', 'Hello World') // true ``` ### JSON For JSON, the contents yielded are parsed into JavaScript and returned. ``` // data.json{ "name": "Eliza", "email": "eliza@example.com"} ``` ``` cy.readFile('path/to/data.json').its('name').should('eq', 'Eliza') // true ``` ### YAML #### Get translation data from a YAML file ``` const YAML = require('yamljs')cy.readFile('languages/en.yml').then((str) => { // parse the string into object literal const english = YAML.parse(str) cy.get('#sidebar') .find('.sidebar-title') .each(($el, i) => { englishTitle = english.sidebar[i] expect($el.text()).to.eq(englishTitle) })}) ``` ### Encoding #### Specify the encoding with the second argument ``` cy.readFile('path/to/logo.png', 'base64').then((logo) => { // logo will be encoded as base64 // and should look something like this: // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...}) ``` #### Read ``` cy.fixture('path/to/logo.png', null).then((logo) => { // logo will be read as a buffer // and should look something like this: // Buffer([0, 0, ...])}) ``` ### Playing MP3 file ``` cy.readFile('audio/sound.mp3', 'base64').then((mp3) => { const uri = 'data:audio/mp3;base64,' + mp3 const audio = new Audio(uri) audio.play()}) ``` ## Notes ### Existence #### Default file existence assertion By default, `cy.readFile()` asserts that the file exists and will fail if it does not exist. It will retry reading the file if it does not initially exist until the file exists or the command times out. ``` // will fail after the defaultCommandTimeout is reachedcy.readFile('does-not-exist.yaml') ``` #### Asserting file non-existence You can assert that a file does not exist like so: ``` // will pass if the file does not existcy.readFile('does-not-exist.yaml').should('not.exist') ``` #### Read a file that might not exist [See our example on using `cy.task()` to read a file that _may_ not exist.](/llm/markdown/api/commands/task.md#Read-a-file-that-might-not-exist) ### Retries #### Automatic retries `cy.readFile()` will continue to read the file until it passes all of its assertions. ``` // if this assertion fails cy.readFile will poll the file// until it eventually passes its assertions (or times out)cy.readFile('some/nested/path/story.txt').should('eq', 'Once upon a time...') ``` Starting in Cypress `v13`, `cy.readFile()` is a query, and will continue to read the file until all chained commands of any type pass, not just assertions. ``` // will retry until the json file has a `users[123].name` field, and// the assertion passescy.readFile('users.json').its('users.123.name').should('eq', 'John Doe') ``` ## Rules ### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands) * `cy.readFile()` requires being chained off of `cy`. * `cy.readFile()` requires the file must exist. * `cy.readFile()` requires the file be successfully read from disk. ### Assertions [Learn about assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions) * `cy.readFile()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until all chained assertions have passed. ### Timeouts [Learn about timeouts](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts) * `cy.readFile()` can time out waiting for assertions you've added to pass. * `cy.readFile()` can time out when the content being read takes a significant amount of time to encode. ## Command Log **_List the contents of your package.json file_** ``` cy.readFile('package.json') ``` The command above will display in the Command Log as: When clicking on the `readFile` command within the command log, the console outputs the following: ## History | Version | Changes | | --- | --- | | [13.0.0](/llm/markdown/app/references/changelog.md#13-0-0) | `cy.readFile()` became a query | | [9.0.0](/llm/markdown/app/references/changelog.md#9-0-0) | Changed `null` encoding to read as Buffer | | [0.17.2](/llm/markdown/app/references/changelog.md#0-17-2) | Improved error messaging | | [0.17.1](/llm/markdown/app/references/changelog.md#0-17-1) | `cy.readFile()` command added | ## See also * [`cy.exec()`](/llm/markdown/api/commands/exec.md) * [`cy.fixture()`](/llm/markdown/api/commands/fixture.md) for a similar command with caching that does not retry * [`cy.task()`](/llm/markdown/api/commands/task.md) * [`cy.writeFile()`](/llm/markdown/api/commands/writefile.md)