---
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: 1375fa62d5875962138c8c43f27d7e1235a504a5
updated_at: '2026-04-29T19:28:48.012Z'
---
# readFile

Read a file and yield its contents.

## Syntax

```javascript
cy.readFile(filePath)
cy.readFile(filePath, encoding)
cy.readFile(filePath, options)
cy.readFile(filePath, encoding, options)
```

### Usage

 **Correct Usage**

```javascript
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.

```text
// path/to/message.txt

Hello World
```

```javascript
cy.readFile('path/to/message.txt').should('eq', 'Hello World') // true
```

### JSON

For JSON, the contents yielded are parsed into JavaScript and returned.

```javascript
// data.json

{
  "name": "Eliza",
  "email": "eliza@example.com"
}
```

```javascript
cy.readFile('path/to/data.json').its('name').should('eq', 'Eliza') // true
```

### YAML

#### Get translation data from a YAML file

```javascript
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

```javascript
cy.readFile('path/to/logo.png', 'base64').then((logo) => {
  // logo will be encoded as base64
  // and should look something like this:
  // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...
})
```

#### Read

```javascript
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

```javascript
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.

```javascript
// will fail after the defaultCommandTimeout is reached
cy.readFile('does-not-exist.yaml')
```

#### Asserting file non-existence

You can assert that a file does not exist like so:

```javascript
// will pass if the file does not exist
cy.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.

```javascript
// 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.

```javascript
// will retry until the json file has a `users[123].name` field, and
// the assertion passes
cy.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***

```javascript
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)