Skip to main content
Cypress App

setCookie

Set a browser cookie.

Syntax​

cy.setCookie(name, value)
cy.setCookie(name, value, options)

Usage​

Correct Usage

cy.setCookie('auth_key', '123key') // Set the 'auth_key' cookie to '123key'

Arguments​

name (String)

The name of the cookie to set.

value (String)

The value of the cookie to set.

options (Object)

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

OptionDefaultDescription
logtrueDisplays the command in the Command log
domainHostname of the application under testThe domain the cookie is visible to. By default the resulting cookie is not host-only; it is matched for this host and all of its subdomains. To restrict the cookie to a single exact host, pass hostOnly: true. See Cookie scope.
expiry20 years into the futureWhen the cookie expires, specified in seconds since Unix Epoch.
hostOnlyfalseWhether the cookie is a host-only cookie. When true, the cookie is scoped to one exact host (the request's host must exactly match the cookie's domain) and is not attached to requests for sibling or parent hosts. See Cookie scope.
httpOnlyfalseWhether the cookie is an HTTP only cookie
path/The cookie path
securefalseWhether the cookie is a secure cookie
timeoutresponseTimeoutTime to wait for cy.setCookie() to resolve before timing out
sameSiteundefinedCookie's SameSite value. If set, should be one of lax, strict, or no_restriction. Pass undefined to use the browser's default. Note: no_restriction can only be used if the secure flag is set to true.

Yields ​

cy.setCookie() yields a cookie object with the following properties:

  • domain
  • expiry (if specified)
  • hostOnly (if specified)
  • httpOnly
  • name
  • path
  • sameSite (if specified)
  • secure
  • value

Examples​

Name Value​

cy.getCookies().should('be.empty')
cy.setCookie('session_id', '189jd09sufh33aaiidhf99d09')
cy.getCookie('session_id').should(
  'have.property',
  'value',
  '189jd09sufh33aaiidhf99d09'
)

When you call cy.setCookie() without hostOnly, the domain defaults to the hostname of the current URL, but the cookie is stored as a domain cookie, not a host-only cookie. Internally Cypress rewrites the domain to its leading-dot form (e.g. .app.example.com), mirroring how real browsers store a cookie that omits the Domain attribute's host-only flag. As a result the cookie matches that host and all of its subdomains.

This matters for cy.request(), which pulls matching cookies from the cookie jar by domain match before sending a request. Because the default cookie is a domain cookie, it can be attached to a cy.request() aimed at a different host that domain-matches it, for example a sibling host on the same registrable domain. This is working as designed, but can be surprising when you set a convenience cookie for your app and see it appear on an unrelated request.

cy.visit('https://app.example.com')

// Default: domain cookie, matches app.example.com AND its subdomains
cy.setCookie('cookieconsent_status', 'dismiss')

// Host-only: matches ONLY the exact host it was set on
cy.setCookie('cookieconsent_status', 'dismiss', { hostOnly: true })

If a cookie is unexpectedly attached to a cy.request() for another host on the same registrable domain, set hostOnly: true to keep it scoped to a single exact host.

By default, Cypress clears all cookies before each test to keep tests independent. If you have a known cookie value that every test requires — such as a cookie-consent acceptance or a feature flag — re-set it in a beforeEach hook so it is present at the start of every test:

// cypress/support/e2e.js
beforeEach(() => {
  cy.setCookie('cookieConsent', 'accepted')
})

For cookies that are generated by the server after a login flow, use cy.session() instead, which caches and restores the full browser context (cookies, localStorage, and sessionStorage) across tests.

Notes​

Default cookie domain before visiting a page​

The domain option defaults to the hostname of the application under test. Before cy.visit() loads a page, the application under test is on about:blank, so Cypress uses the hostname it serves the spec from instead (usually localhost). Pass domain explicitly to work with cookies on another domain before visiting.

Rules​

Requirements ​

  • cy.setCookie() requires being chained off of cy.

Assertions ​

  • cy.setCookie() will only run assertions you have chained once, and will not retry.

Timeouts ​

  • cy.setCookie() can time out waiting for the browser to set the cookie. It waits up to the responseTimeout (or the timeout option, when passed) before failing.
  • If the application under test is on a different origin, cy.setCookie() retries for up to the defaultCommandTimeout (or the timeout option, when passed) and then fails with a cross-origin error. Run it inside cy.origin() to work with cookies on that origin.

Command Log​

Set a cookie on the browser for testing

cy.getCookies().should('be.empty')
cy.setCookie('fakeCookie1', '123ABC')
cy.getCookie('fakeCookie1').should('have.property', 'value', '123ABC')

The commands above display in the Command Log as:

Command Log setcookie

When clicking on setCookie within the command log, the console outputs the following:

Console Log setcookie

History​

VersionChanges
12.7.0Support hostOnly option for a given domain.
5.0.0Removed experimentalGetCookiesSameSite and made sameSite property always available.
4.3.0Added sameSite property when the experimentalGetCookiesSameSite configuration value is true.
0.16.0cy.setCookie() command added

See also​

Contents