Skip to main content
Cypress App

fixture

Load a fixed set of data located in a file.

Tests are easiest to trust when every run starts from the same data. cy.fixture() loads known test data, such as JSON records, images, and CSV files, from your fixturesFolder. Loading data from fixtures keeps the data out of your spec code, lets many tests share it, and means a test fails because your app changed, not because the data did.

Reach for cy.fixture() when you need to:

  • Stub network responses with cy.intercept(), so your tests don't depend on a live backend or on data that changes between runs
  • Fill in forms or check the page against the same known records every time
  • Upload a sample file through a file input with .selectFile()

To read a file that changes while your tests run, or a file your app produces, use cy.readFile() instead. See How cy.fixture() differs from cy.readFile().

Syntax​

cy.fixture(filePath)
cy.fixture(filePath, encoding)
cy.fixture(filePath, options)
cy.fixture(filePath, encoding, options)

Usage​

Correct Usage

cy.fixture('users').as('users') // load data from users.json
cy.fixture('logo.png').then((logo) => {
// load data from logo.png
})

Incorrect Usage

// users is a chainable, not the fixture contents
const users = cy.fixture('users')

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

The path has to resolve to a file inside the fixturesFolder. A path that leaves it, such as '../cypress.config.js', fails.

encoding (String)

The encoding Cypress reads the file with. Cypress supports:

  • 'ascii'
  • 'base64'
  • 'binary'
  • 'hex'
  • 'latin1'
  • 'utf8'
  • 'utf-8'
  • 'ucs2'
  • 'ucs-2'
  • 'utf16le'
  • 'utf-16le'
  • null

Passing an encoding yields the raw file contents without parsing them, whatever the file extension. For example, cy.fixture('users.json', 'utf8') yields the JSON as a string rather than an object. Passing null yields the contents as a Cypress.Buffer instance.

options (Object)

Pass in an options object to change the default behavior of cy.fixture().

OptionDefaultDescription
timeoutresponseTimeoutTime to wait for cy.fixture() to resolve before timing out

Yields ​

  • cy.fixture() yields the contents of the file. Unless you pass an encoding, Cypress formats them based on the file extension. See How Cypress chooses a fixture's encoding.
  • cy.fixture() yields a copy of the cached contents, so changing the yielded object does not affect later cy.fixture() calls for the same file.
  • Cypress doesn't update the yielded subject when the file changes on disk. See How Cypress caches fixture data for when Cypress reads the file again.

Examples​

JSON​

Load a users.json fixture​

cy.fixture('users.json').as('users')

Omit the fixture file's extension​

When you pass a path without an extension, Cypress first looks for a file with exactly that name. If there isn't one, Cypress searches the fixturesFolder for files with that name and a supported extension, and resolves the first one.

cy.fixture('admin').as('admin')

Cypress checks these paths in order:

  1. cypress/fixtures/admin.json
  2. cypress/fixtures/admin.js
  3. cypress/fixtures/admin.html
  4. cypress/fixtures/admin.txt
  5. cypress/fixtures/admin.csv
  6. cypress/fixtures/admin.png
  7. cypress/fixtures/admin.jpg
  8. cypress/fixtures/admin.jpeg
  9. cypress/fixtures/admin.gif
  10. cypress/fixtures/admin.tif
  11. cypress/fixtures/admin.tiff
  12. cypress/fixtures/admin.zip

Import a JSON fixture into your spec​

If you are loading a JSON fixture, you can use the import statement and let the bundler load it:

cypress/e2e/spec.cy.js
import user from '../fixtures/user.json'
it('loads the same object', () => {
cy.fixture('user').then((userFixture) => {
expect(user, 'the same data').to.deep.equal(userFixture)
})
})

Generate a test for each record in a fixture​

To create one test per fixture record, import the fixture. cy.fixture() supplies data inside a test, but a loop inside its callback can't add new it() blocks.

cypress/e2e/users.cy.js
import users from '../fixtures/users.json'

describe('User profiles', () => {
users.forEach((user) => {
it(`shows the profile for ${user.name}`, () => {
cy.visit(`/users/${user.id}`)
cy.contains('h1', user.name)
})
})
})

Type fixture data in TypeScript​

cy.fixture() accepts a type argument that describes the yielded contents. Cypress doesn't check the file against the type, so keep the two in sync.

type User = {
id: number
name: string
email: string
}

cy.fixture<User[]>('users').then((users) => {
// users is typed as User[]
cy.get('[data-cy="user-email"]').first().should('have.text', users[0].email)
})

Read a JSON fixture as raw text​

Pass an encoding to yield the file's contents as a string instead of the parsed object. The raw string helps when you want the exact text of the file, such as to compare it with a raw request body.

cy.fixture('users.json', 'utf8').then((raw) => {
expect(raw).to.be.a('string')
expect(raw).to.include('"email"')
})

JavaScript​

Generate values in a .js fixture​

A .js fixture holds a single JavaScript expression, so it can compute values that a JSON file can't, such as a date relative to now. Cypress evaluates the file the first time you load it and caches the result, so later calls yield the same values rather than evaluating the file again.

cypress/fixtures/session.js
{
token: 'test-token',
expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
}
cypress/e2e/session.cy.js
cy.fixture('session').then((session) => {
expect(Date.parse(session.expiresAt)).to.be.greaterThan(Date.now())
})

CSV​

Parse a CSV fixture into rows​

A .csv fixture yields the whole file as one utf8 string. Split it into lines and fields to work with each row.

cypress/fixtures/users.csv
name,email
Jane,jane@cypress.io
Lee,lee@cypress.io
cypress/e2e/users.cy.js
cy.fixture('users.csv').then((csv) => {
const [header, ...rows] = csv.trim().split(/\r?\n/)
const users = rows.map((row) => {
const [name, email] = row.split(',')
return { name, email }
})

expect(header).to.eq('name,email')
expect(users[0]).to.deep.eq({ name: 'Jane', email: 'jane@cypress.io' })
})

Splitting on commas works for simple files. For fields that contain quoted commas or line breaks, parse the string with a CSV library instead.

Images​

Image fixtures yield base64 strings by default​

cy.fixture('images/logo.png').then((logo) => {
// logo is a base64 string, like:
// aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...
})

Read an image fixture as a Cypress.Buffer​

cy.fixture('images/logo.png', null).then((logo) => {
// logo is a buffer, like:
// Buffer([0, 0, ...])
expect(Cypress.Buffer.isBuffer(logo)).to.be.true
})

File uploads​

Upload a fixture with .selectFile()​

Load the fixture with a null encoding so it yields a Cypress.Buffer, alias it, and pass the alias to .selectFile(). Cypress keeps the fixture's file name, so the upload arrives as avatar.png.

cy.fixture('images/avatar.png', null).as('avatar')
cy.get('input[type="file"]').selectFile('@avatar')

Stub network responses with fixtures​

Stub a network response with fixture data​

cy.fixture('users').then((json) => {
cy.intercept('GET', '/users/**', json)
})

Stub an error response with a fixture​

Pair the fixture property with statusCode to test how your app handles a failed request. Cypress sends the fixture as the response body with the status you set.

cy.intercept('GET', '/api/users', {
statusCode: 500,
fixture: 'errors/server-error.json',
}).as('getUsers')

cy.visit('/users')
cy.wait('@getUsers').its('response.statusCode').should('eq', 500)
cy.get('[data-cy="error-banner"]').should('be.visible')

Change fixture data before stubbing a response​

You can modify fixture data directly before visiting a URL or mounting a component that makes a network request to that URL.

cy.fixture('user').then((user) => {
user.firstName = 'Jane'
cy.intercept('GET', '/users/1', user).as('getUser')
})

cy.visit('/users')
cy.wait('@getUser').then(({ response }) => {
expect(response.body.firstName).to.eq('Jane')
})

Share fixture data across tests​

Load a fixture in beforeEach() and read it with cy.get()​

Cypress clears aliases between tests, so load the fixture in a beforeEach() hook and read the alias back with cy.get(). Reading the alias this way works with arrow functions, unlike the this context.

describe('User list', () => {
beforeEach(() => {
cy.fixture('users').as('users')
})

it('shows a row for every user', () => {
cy.visit('/users')
cy.get('@users').then((users) => {
cy.get('[data-cy="user-row"]').should('have.length', users.length)
})
})
})

Load several fixtures for one test​

Alias each fixture in beforeEach(), then read the aliases together inside the test.

describe('Order history', () => {
beforeEach(() => {
cy.fixture('users/admin').as('admin')
cy.fixture('orders').as('orders')
})

it('lists every order for the signed-in user', () => {
cy.visit('/orders')
cy.get('@admin').then((admin) => {
cy.get('@orders').then((orders) => {
cy.contains('h1', admin.name)
cy.get('[data-cy="order-row"]').should('have.length', orders.length)
})
})
})
})

Set up test state with fixtures​

Fill in a form with fixture data​

Keep test account details in a fixture so every test signs in with the same known user. { log: false } keeps the password out of the Command Log.

cy.fixture('users/admin').then((admin) => {
cy.visit('/login')
cy.get('[data-cy="email"]').type(admin.email)
cy.get('[data-cy="password"]').type(admin.password, { log: false })
cy.get('form').submit()
})
cy.location('pathname').should('eq', '/dashboard')

You commit fixtures with your tests, so keep real secrets out of them and read those with cy.env() instead.

Seed your backend with fixture data​

Send a fixture to a test-only endpoint in your app with cy.request() so your real backend starts every test from the same records.

beforeEach(() => {
cy.fixture('users').then((users) => {
cy.request('POST', '/api/test/seed', { users })
})
cy.visit('/users')
})

For a full app example, see the server communication recipes.

Pass fixture data to a component as props​

In a component test, hand the fixture straight to the component you mount.

src/Profile.cy.jsx
import Profile from './Profile'

it('shows the user name', () => {
cy.fixture('user').then((user) => {
cy.mount(<Profile user={user} />)
cy.contains('h2', user.firstName)
})
})

Notes​

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

Both commands read a file from disk, but they answer different questions. cy.fixture() answers "what data should this test start with?" while cy.readFile() answers "what's in this file right now?" Use cy.fixture() for known data that stays the same during the run, and cy.readFile() for files that change or that your app creates. 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 tofixturesFolderThe project root
File extensionOptionalRequired
Reads from diskOnce per path and encoding, then yields the cached copyOn every call
Retries until assertions passNoYes, reading the file again on each retry
Images by defaultA base64 stringA utf8 string
Default timeoutresponseTimeoutdefaultCommandTimeout
Command LogNot loggedLogged
Missing fileAlways failsCan be asserted with .should('not.exist')

Serve a fixture directly from cy.intercept()​

cy.intercept() serves a fixture without a cy.fixture() call. Pass its path as the fixture property of a StaticResponse.

cy.intercept('GET', '/users/**', { fixture: 'users' })

The Command Log's Routes panel lists the route as stubbed, and each request it answers appears in the test body without a live server behind it:

Command Log with the Routes panel showing GET /users/** stubbed, and a fetch to /users/1 answered by it

cy.intercept() serves image and .zip fixtures as raw bytes. cy.intercept() reads other binary files, such as .mp4 or .pdf, as utf8 text by default, which corrupts them. To serve one of those byte for byte, add null as the encoding after a comma:

cy.intercept('GET', '/media/intro.mp4', { fixture: 'media/intro.mp4,null' })

You can pass any other supported encoding the same way. As with cy.fixture(), the path has to resolve to a file inside the fixturesFolder.

How Cypress validates JSON and JavaScript fixtures​

Cypress automatically validates your fixtures. If your .json or .js files contain syntax errors, the test fails with an error that names the fixture and describes the problem.

Cypress evaluates a .js fixture as a single JavaScript expression, such as an object literal ({ name: 'Jane' }), rather than loading it as a module.

How Cypress chooses a fixture's encoding​

When you don't pass an encoding, Cypress reads the file based on its extension:

ExtensionYields
.jsonThe parsed JSON
.jsThe evaluated JavaScript expression
.png, .jpg, .jpeg, .gif, .tif, .tiff, .zipA base64 string
.html, .txt, .csv, and every other extensionA utf8 string

To read a file differently, pass an encoding as the second argument.

These defaults describe what cy.fixture() yields. When you serve a fixture from cy.intercept(), Cypress sends image and .zip fixtures as raw bytes instead of base64.

Share fixture data through the this context​

To store and read fixture data on the this test context, use function () { ... } callbacks. Arrow functions don't bind this, so inside them this doesn't point 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')
})
})

Work with large fixture files​

Why large fixtures can crash or stall Cypress​

cy.fixture() reads the whole file into memory and sends its contents from the Cypress Node.js server process to the browser over an internal WebSocket connection. Cypress sets no file size limit, but large files (especially binary files like .zip archives) can make Cypress crash or stop responding because of:

  • Memory pressure: the whole file must fit in available RAM. Cypress keeps the contents in the fixture cache and yields a separate copy, so each loaded fixture takes up memory more than once. By default, Cypress also converts binary files such as images and .zip archives to a base64 string in the browser, which is about a third larger than the file itself.
  • Single-message transfer: Cypress sends the contents as one message over the internal socket, so it buffers the whole payload at once.

Keep fixtures under a few megabytes. Use a representative subset of production data rather than a full export.

Upload a large file with .selectFile() and a path​

To simulate a file upload through an <input type="file"> element, pass a path string to .selectFile() rather than loading the fixture first and setting the input yourself:

// ✅ Preferred for file upload simulation
cy.get('input[type="file"]').selectFile('cypress/fixtures/large.zip')

Check a large file in Node.js with cy.task()​

To check a large file without sending its contents to the browser, such as to read its metadata or run a server-side operation on it, use cy.task() to keep the work in Node.js:

const { defineConfig } = require('cypress')
const { statSync } = require('fs')

module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
on('task', {
getFileSize(filePath) {
const { size } = statSync(filePath)
return size
},
})
},
},
})
// in your test
cy.task('getFileSize', 'cypress/fixtures/large.zip').then((size) => {
expect(size).to.be.greaterThan(0)
})

How Cypress caches fixture data​

The first time you load a fixture, Cypress caches its contents, keyed on the path exactly as you wrote it and the encoding. Later cy.fixture() calls with the same path and encoding yield the cached contents, even if the file has changed on disk. Because the key is the path as written, Cypress caches cy.fixture('users') and cy.fixture('users.json') separately, so use one form consistently to read the file only once.

When you write to a file inside the fixturesFolder with cy.writeFile(), Cypress clears that file from the cache for every encoding, whether you loaded it with or without its extension, so the next cy.fixture() call reads the new contents:

cy.writeFile('cypress/fixtures/todo.json', { title: 'New data' })
cy.fixture('todo').its('title').should('eq', 'New data')

Cypress doesn't detect changes made any other way, such as from cy.task() or another process. To read a file that changes during your tests, use cy.readFile() instead.

Fixtures in cy.intercept() are read when the route is added​

The fixture property of a cy.intercept() StaticResponse reads the file when Cypress registers the route. Overwriting the file afterwards doesn't change what that route replies with, so the following doesn't work:

// 🚨 DOES NOT WORK
cy.intercept('GET', '/todos/1', { fixture: 'todo' }).as('todo')
// application requests the /todos/1 resource
// the intercept replies with the object from todo.json file

cy.wait('@todo').then(() => {
cy.writeFile('cypress/fixtures/todo.json', { title: 'New data' })
})
// application requests the /todos/1 resource again
// the intercept replies with the object read from todo.json
// when the route was added and NOT { "title": "New data" }

In this situation, respond to the network request with the object and add a new intercept when the data changes:

// ✅ RESPOND WITH OBJECT
cy.fixture('todo.json').then((todo) => {
cy.intercept('GET', '/todos/1', { body: todo }).as('todo')
// application requests the /todos/1 resource
// the intercept replies with the initial object

cy.wait('@todo').then(() => {
// modify the response object
todo.title = 'New data'
// and override the intercept
cy.intercept('GET', '/todos/1', { body: todo })
})
})

Rules​

Requirements ​

  • cy.fixture() requires being chained off of cy.
  • cy.fixture() requires fixturesFolder to be set. cy.fixture() fails if fixturesFolder is false.
  • cy.fixture() requires filePath to resolve to a file inside the fixturesFolder.
  • cy.fixture() requires the file to exist. If no file matches filePath, or filePath with one of the supported extensions, the command fails with an error listing the paths and extensions Cypress tried.

Assertions ​

  • cy.fixture() only runs assertions you have chained once, and does not retry.

Timeouts ​

  • cy.fixture() can time out waiting for the Cypress server to send the fixture. The command waits for the timeout option, which defaults to responseTimeout.
  • cy.fixture() yields cached contents without waiting on the server, so a cached fixture never times out.

Command Log​

  • cy.fixture() does not log in the Command Log.

History​

VersionChanges
16.2.1Fails when filePath resolves outside the fixturesFolder.
16.0.0No longer resolves .coffee files when filePath omits the extension.
15.18.0An aliased fixture keeps its file name for .selectFile() when a later test loads the same fixture.
15.0.0cy.writeFile() clears the cache for a fixture it writes. An explicit encoding always yields raw file contents.

See also​