Cypress App

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).

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 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
timeout	defaultCommandTimeout	Time to wait for cy.readFile() to resolve before timing out

Yields

• 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.txt

Hello 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": "[email protected]"
}

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 reached
cy.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 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.

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 passes
cy.readFile('users.json').its('users.123.name').should('eq', 'John Doe')

How cy.readFile() differs from cy.fixture()

cy.readFile() reads the file on every call and retries until your assertions pass, so it suits files that change during a test or that your app creates. For known test data that stays the same, cy.fixture() reads the file once and caches it. For when to reach for a static import or cy.task() instead, see Choosing how to load test data in Cypress.

	cy.fixture()	cy.readFile()
Path is relative to	fixturesFolder	The project root
File extension	Optional	Required
Reads from disk	Once per path and encoding, then yields the cached copy	On every call
Retries until assertions pass	No	Yes, reading the file again on each retry
Images by default	A base64 string	A utf8 string
Default timeout	responseTimeout	defaultCommandTimeout
Command Log	Not logged	Logged
Missing file	Always fails	Can be asserted with .should('not.exist')

Rules

Requirements

• 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

• cy.readFile() will automatically retry until all chained assertions have passed.

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	cy.readFile() became a query
9.0.0	Changed null encoding to read as Buffer
0.17.2	Improved error messaging
0.17.1	cy.readFile() command added

See also

• cy.fixture() for a similar command with caching that does not retry
• cy.task()
• cy.writeFile()