t.setCookies Method

Adds or updates page cookies. Chainable.

If the method finds an existing cookie with the specified name and URL, it updates the cookie according to the specified value and metadata.

The method sets the cookie for the specified domain/URL and nested test pages.

The following example uses a t.setCookies overload to add a new cookie with the specified name, value and URL.

fixture`[API] Set Cookies`
    .page('https://devexpress.github.io/testcafe/example/');

test('Should set cookies by name and value', async t => {
    await t.setCookies({ apiCookie1: 'value1' }, 'http://localhost');

    const cookies = await t.getCookies();

    const { name, value, domain, path } = cookies[0];

    await t
        .expect(name).eql('apiCookie1')
        .expect(value).eql('value1')
        .expect(domain).eql('localhost')
        .expect(path).eql('/');
});

The following example uses a t.setCookies overload to add a new cookie with advanced options (httpOnly).

fixture`[API] Set Cookies`
    .page('https://devexpress.github.io/testcafe/example/');

test('Should set cookies with special properties', async t => {
    const cookieObject = { name: 'apiCookie1', value: 'value1', domain: 'localhost', httpOnly: true };

    await t.setCookies(cookieObject);

    const cookies = await t.getCookies();

    await t
        .expect(cookies.length).eql(1)
        .expect(cookies[0]).contains(cookieObject);
});

The following example uses a t.setCookies overload to set cookies for different pages.

fixture`[API] Set Cookies`
    .page('https://devexpress.github.io/testcafe/example/');

test('Should assign cookies to the specified url', async t => {
    //set a cookie for the Example page
    await t.setCookies({ name: 'apiCookie1', value: 'value1' }, 'https://devexpress.github.io/testcafe/example/');

    //set a cookie for localhost
    await t.setCookies({ name: 'apiCookie2', value: 'value2' }, 'http://localhost');

    //retrieve all the cookies
    const cookies = await t.getCookies();

    await t
        .expect(cookies.length).eql(2)
        .expect(cookies[0]).contains({ name: 'apiCookie1', value: 'value1', domain: 'devexpress.github.io' })
        .expect(cookies[1]).contains({ name: 'apiCookie2', value: 'value2', domain: 'localhost' });
});

t.setCookies(nameValueObjects, url)

setCookies(nameValueObjects: Record<string, string> | Record<string, string>[], url: string) → this | Promise<any>

Parameter	Type	Description
nameValueObjects	Record<string, string> | Record<string, string>[]	Cookie name-value pair or an array of such records
url	string	Test page URL

This overload can only set cookie values. Use a different overload to specify metadata properties (such as expires, httpOnly, secure, and others).

t.setCookies(cookies)

setCookies(cookies: CookieOptions | CookieOptions[]) → this | Promise<any>

Adds or updates cookies as specified by the parameter. Use this overload if you need to set cookie values and/or metadata properties (such as expires, httpOnly, secure, and others).

Parameter	Type	Description
cookies	CookieOptions | CookieOptions[]	Cookie object(s)

If the cookie object doesn’t specify domain and path, the method sets the cookie for the current page.

Cookie Object

A cookie object contains all properties that can be associated with a web cookie. The CookieOptions interface declares the cookie object structure.

export interface CookieOptions {
    name?: string;
    value?: string;
    domain?: string;
    path?: string;
    expires?: Date;
    maxAge?: number | 'Infinity' | '-Infinity';
    secure?: boolean;
    httpOnly?: boolean;
    sameSite?: string;
}

Field	Type	Description
name (optional)	string	Specifies the name of the cookie.
value (optional)	string	Specifies the value of the cookie.
domain (optional)	string	Specifies the domain associated with the cookie.
path (optional)	string	Specifies the path associated with the cookie.
expires (optional)	Date	Specifies the cookie expiration date (the time when the cookie is automatically erased).
maxAge (optional)	number \| 'Infinity' \| '-Infinity'	Specifies the cookie’s expiration in seconds from the current moment.
secure (optional)	boolean	Specifies that the cookie should be transferred only over HTTPS.
httpOnly (optional)	boolean	Specifies that JavaScript code should not have access to the cookie.
sameSite (optional)	string	Doesn’t allow the browser to send the cookie with requests that come from a different site. This option helps prevent XSRF attacks.