Skip to main content
Cypress App

getCookie

Get a browser cookie by its name.

Syntax​

cy.getCookie(name)
cy.getCookie(name, options)

Usage​

Correct Usage

cy.getCookie('auth_key') // Get cookie with name 'auth_key'

Arguments​

name (String)

The name of the cookie to get. Required.

options (Object)

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

OptionDefaultDescription
domainHostname of the current URLRetrieves the cookie from the specified domain
logtrueDisplays the command in the Command log
timeoutdefaultCommandTimeoutTime to wait for cy.getCookie() to resolve before timing out

Yields ​

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

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

cy.getCookie() is a query, and it is safe to chain further commands. It will automatically retry until all chained assertions have passed, or until it times out, re-reading the cookie on each retry so the yielded value stays up to date. Chained assertions are what drive those retries: with no assertions chained, cy.getCookie() yields whatever it reads on the first attempt, which is null if the cookie does not exist yet. Chain .should('exist') to wait for a cookie that is set asynchronously.

caution

Because cy.getCookie() is a query, it re-reads the cookie on every retry, and assertions you chain with .should() drive those retries until they pass or the command times out. A .then() callback, by contrast, runs only once after the command settles and is not retried — so prefer chaining .should() assertions over asserting inside .then() when you need Cypress to wait for the cookie to be set.

On each read, cy.getCookie() yields the cookie object, or null if no cookie with that name exists yet. The yielded value is the subject your chained assertions run against. If an assertion fails, either because the cookie is null, or because it exists but a property doesn't match yet, the query re-reads the cookie and re-runs the assertion, looping until it passes or the command times out.

Examples​

Session id​

In this example, on first login, our server sends us back a session cookie.

// assume we just logged in
cy.contains('Login').click()
cy.url().should('include', 'profile')
// retries until cookie with value=189jd09su
// is found or default command timeout ends
cy.getCookie('session_id')
  .should('have.property', 'value', '189jd09su')
  .then((cookie) => {
    // cookie is an object with "domain", "name" and other properties
  })

You can check the cookie existence without comparing any of its properties

cy.getCookie('my-session-cookie').should('exist')

If you need the cookie value, for example to use in a subsequent call

let cookie

cy.getCookie('session_id')
  .should('exist')
  .then((c) => {
    // save cookie until we need it
    cookie = c
  })

// some time later, force the "cy.request"
// to run ONLY after the cookie has been set
// by placing it inside ".then"
cy.get('#submit')
  .click()
  .then(() => {
    cy.request({
      url: '/api/admin',
      headers: {
        'my-token-x': cookie.value,
      },
    })
  })

Using cy.getCookie() to test logging in​

info

Check out our example recipes using cy.getCookie() to test logging in using HTML web forms, logging in using XHR web forms, and logging in with single sign on

Rules​

Requirements ​

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

Assertions ​

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

Timeouts ​

  • cy.getCookie() can time out waiting for assertions you've added to pass.

Command Log​

Get a browser cookie and make assertions about the object

cy.getCookie('fakeCookie1').should('have.property', 'value', '123ABC')

The commands above will display in the Command Log as:

Command Log getcookie

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

Console Log getcookie

History​

VersionChanges
16.0.0cy.getCookie() is now a query and retries assertions until they pass or time out.
5.0.0Removed experimentalGetCookiesSameSite and made sameSite property always available.
4.3.0Added sameSite property when the experimentalGetCookiesSameSite configuration value is true.

See also​

Contents