Load a fixed set of data located in a file.
Syntax
cy.fixture(filePath) cy.fixture(filePath, encoding) cy.fixture(filePath, options) cy.fixture(filePath, encoding, options)
Usage
Correct Usage
cy.fixture('users').as('usersJson') // load data from users.json cy.fixture('logo.png').then((logo) => { // load data from logo.png })
Arguments
filePath (String)
A path to a file within the fixturesFolder
, which defaults to cypress/fixtures
.
You can nest fixtures within folders and reference them by defining the path from the fixturesFolder:
cy.fixture('users/admin.json') // Get data from {fixturesFolder}/users/admin.json
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
options (Object)
Pass in an options object to change the default behavior of cy.fixture()
.
Option | Default | Description |
---|---|---|
timeout | responseTimeout | Time to wait for cy.fixture() to resolve before timing out
|
Yields
cy.fixture()
yields the contents of the file. Formatting is determined by its file extension.
Examples
JSON
Load a users.json
fixture
cy.fixture('users.json').as('usersData')
Omit the fixture file’s extension
When no extension is passed to cy.fixture()
, Cypress will search for files with the specified name within the fixturesFolder
(which defaults to cypress/fixtures
) and resolve the first one.
cy.fixture('admin').as('adminJSON')
The example above would resolve in the following order:
cypress/fixtures/admin.json
cypress/fixtures/admin.js
cypress/fixtures/admin.coffee
cypress/fixtures/admin.html
cypress/fixtures/admin.txt
cypress/fixtures/admin.csv
cypress/fixtures/admin.png
cypress/fixtures/admin.jpg
cypress/fixtures/admin.jpeg
cypress/fixtures/admin.gif
cypress/fixtures/admin.tif
cypress/fixtures/admin.tiff
cypress/fixtures/admin.zip
Images
Image fixtures are sent as base64
cy.fixture('images/logo.png').then((logo) => { // logo will be encoded as base64 // and should look something like this: // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==... })
Change encoding of Image fixture
cy.fixture('images/logo.png', 'binary').then((logo) => { // logo will be encoded as binary // and should look something like this: // 000000000000000000000000000000000000000000... })
Playing MP3 file
cy.fixture('audio/sound.mp3', 'base64').then((mp3) => { const uri = 'data:audio/mp3;base64,' + mp3 const audio = new Audio(uri) audio.play() })
Accessing Fixture Data
Using .then()
to access fixture data
cy.fixture('users').then((json) => { cy.route('GET', '/users/**', json) })
Using fixtures to bootstrap data
Check out our example recipe using
cy.fixture()
to bootstrap data for our application.
Using an alias to access a fixture
You can make use of aliasing, .as()
, instead of working directly with the yielded data.
Using an alias provides the benefit of terseness and readability. It also makes it easier to access the data later in your tests.
cy.fixture('users').as('usersJSON') cy.route('GET', '/users/**', '@usersJSON') // ...later on... cy.get('#email').then(() => { // we have access to this.usersJSON since it was aliased this.usersJSON })
Modifying fixture data before using it
You can modify fixture data directly before passing it along to a route.
cy.fixture('user').then((user) => { user.firstName = 'Jane' cy.route('GET', '/users/1', user).as('getUser') }) cy.visit('/users') cy.wait('@getUser').then((xhr) => { expect(xhr.requestBody.firstName).to.eq('Jane') })
Notes
Shortcuts
Using fixture
or fx
shortcuts
Fixtures can also be referenced directly without using the .fixture()
command by using the special keywords: fixture:
or fx:
within cy.route()
.
cy.route('GET', '/users/**', 'fixture:users') // this works cy.route('GET', '/users/**', 'fx:users') // this also works
Validation
Automated File Validation
Cypress automatically validates your fixtures. If your .json
, .js
, or .coffee
files contain syntax errors, they will be shown in the Command Log.
Encoding
Default Encoding
Cypress automatically determines the encoding for the following file types:
.json
.js
.coffee
.html
.txt
.csv
.png
.jpg
.jpeg
.gif
.tif
.tiff
.zip
For other types of files, they will be read as utf8
by default, unless specified in the second argument of cy.fixture()
.
this
context
If you store and access the fixture data using this
test context object, make sure to use function () { ... }
callbacks. Otherwise the test engine will NOT have this
pointing at the test context.
describe('User page', () => { beforeEach(function () { // "this" points at the test context object cy.fixture('user') .then((user) => { // "this" is still the test context object this.user = user }) }) // the test callback is in "function () { ... }" form it('has user', function () { // this.user exists expect(this.user.firstName).to.equal('Jane') }) })
Rules
Requirements
cy.fixture()
requires being chained off ofcy
.
Assertions
cy.fixture()
will only run assertions you've chained once, and will not retry.
Timeouts
cy.fixture()
should never time out.
Because
cy.fixture()
is asynchronous it is technically possible for there to be a timeout while talking to the internal Cypress automation APIs. But for practical purposes it should never happen.
Command Log
-
cy.fixture()
does not log in the Command Log
See also
cy.route()
.then()
- Recipe: Bootstrapping App Test Data
- Fixtures section of the Cypress Testing Workshop