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 default cypress.json configuration file).
encoding (String)
The encoding to be used when reading the file. The following encodings are supported:
asciibase64binaryhexlatin1utf8utf-8ucs2ucs-2utf16leutf-16le
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.
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==...
})
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 usingcy.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...')
Rules
Requirements
cy.readFile()requires being chained off ofcy.cy.readFile()requires the file must exist.cy.readFile()requires the file be successfully read from disk. Anything preventing this such as OS permission issues will cause it to fail.
Assertions
cy.readFile()will automatically retry until assertions you've chained all pass.
Timeouts
cy.readFile()can time out waiting for assertions you've added to pass.
Command Log
List the contents of the default cypress.json configuration file
cy.readFile('cypress.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:
