BrowserContext on Grafana Labs

addCookies()

Mon, 21 Sep 2026 15:16:28 +0000

addCookies()

Adds a list of cookies into the browser context. All pages within this browser context will have these cookies set.

Note
If a cookie’s url property is not provided, both domain and path properties must be specified.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the cookies have been added to the browser context.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  const page = await context.newPage();

  try {
    const unixTimeSinceEpoch = Math.round(new Date() / 1000);
    const day = 60 * 60 * 24;
    const dayAfter = unixTimeSinceEpoch + day;
    const dayBefore = unixTimeSinceEpoch - day;

    await context.addCookies([
      // this cookie expires at the end of the session
      {
        name: 'testcookie',
        value: '1',
        sameSite: 'Strict',
        domain: 'httpbin.org',
        path: '/',
        httpOnly: true,
        secure: true,
      },
      // this cookie expires in a day
      {
        name: 'testcookie2',
        value: '2',
        sameSite: 'Lax',
        domain: 'httpbin.org',
        path: '/',
        expires: dayAfter,
      },
      // this cookie expires in the past, so it will be removed.
      {
        name: 'testcookie3',
        value: '3',
        sameSite: 'Lax',
        domain: 'httpbin.org',
        path: '/',
        expires: dayBefore,
      },
    ]);

    const response = await page.goto('https://httpbin.org/cookies', {
      waitUntil: 'networkidle',
    });
    console.log(response.json());
    // prints:
    // {"cookies":{"testcookie":"1","testcookie2":"2"}}
  } finally {
    await page.close();
  }
}

addInitScript()

Mon, 21 Sep 2026 15:16:28 +0000

addInitScript()

Adds a script which will be evaluated in one of the following scenarios:

Whenever a page is created in the browser context or is navigated.
Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame.

The script is evaluated after the document is created but before any of its scripts are run. This is useful to amend the JavaScript environment, for example, to override Math.random.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the script has been added to the browser context.

Example

import { browser } from 'k6/browser';
import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const browserContext = await browser.newContext();

  // This will execute and override the existing implementation of Math.random.
  await browserContext.addInitScript('Math.random = function(){return 0}');

  const page = await browserContext.newPage();

  // In this example we are going to set the content manually, so we first
  // navigate to about:blank which will execute the init script, before setting
  // the content on the page.
  await page.goto('about:blank');

  await page.setContent(`
  <html>
    <head></head>
    <body>
      <div id="random">waiting...</div>
    </body>
    <script>
        document.getElementById('random').textContent = Math.random();
    </script>
  </html>`);

  await check(page.locator('#random'), {
    'is zero': async random => await random.textContent() == '0'
  });

  await page.close();
}

clearCookies()

Mon, 21 Sep 2026 15:16:28 +0000

clearCookies()

Clears the browser context’s cookies.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the cookies have been cleared from the browser context.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto('https://httpbin.org/cookies/set?testcookie=testcookievalue');
  let cookies = await context.cookies();
  console.log(cookies.length); // prints: 1

  await context.clearCookies();
  cookies = await context.cookies();
  console.log(cookies.length); // prints: 0
}

clearPermissions()

Mon, 21 Sep 2026 15:16:28 +0000

clearPermissions()

Clears all permission overrides for the browser context.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the permissions have been cleared from the browser context.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  await context.grantPermissions(['clipboard-read']);
  // do stuff ...
  await context.clearPermissions();
}

close()

Mon, 21 Sep 2026 15:16:28 +0000

close()

Close the browser context and all its pages. The browser context is unusable after this call and a new one must be created. This is typically called to cleanup before ending the test.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the browser context and all its pages have been closed.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  await context.newPage();

  await context.close();
}

Cookie

Mon, 21 Sep 2026 15:16:28 +0000

Cookie class represents a cookie in the BrowserContext.

See the HTTP Cookies documentation on the Mozilla website for more details about cookies.

Property	Type	Default	Description
name	string	`""`	The cookie’s name. Required.
value	string	`""`	The cookie’s value. Required.
domain	string	`""`	The cookie’s domain.
path	string	`'/'`	The cookie’s path.
url	string	`""`	The cookie’s URL.
expires	number	`-1`	The cookie’s expiration date as the number of seconds since the UNIX epoch. `-1` means a session cookie.
httpOnly	bool	`false`	A cookie is inaccessible to the JavaScript document.cookie API when this property is `true`.
secure	bool	`false`	The cookie’s secure flag.
sameSite	string	`'Lax'`	The cookie’s same site flag. It can be one of `'Strict'`, `'Lax'`, and `'None'`.

cookies([urls])

Mon, 21 Sep 2026 15:16:28 +0000

cookies([urls])

Returns a list of cookies from the browser context filtered by the provided urls. If no urls are provided, all cookies are returned.

Parameter	Type	Description
urls	array	A string array of URLs to filter the cookies in the browser context.

Returns

Type	Description
`Promise<Array<Cookie>>`	A Promise that fulfills with an array of cookies.

Note
Cookies can be added with BrowserContext.addCookies.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  const page = await context.newPage();

  try {
    // get cookies from the browser context
    let cookies = await context.cookies();
    console.log('initial cookies length:', cookies.length); // prints 0

    // let's add more cookies to filter by urls
    await context.addCookies([
      { name: 'foo', value: 'foovalue', sameSite: 'Strict', url: 'http://foo.com' },
      { name: 'bar', value: 'barvalue', sameSite: 'Lax', url: 'https://bar.com' },
      { name: 'baz', value: 'bazvalue', sameSite: 'Lax', url: 'https://baz.com' },
    ]);

    // get all cookies
    cookies = await context.cookies();
    console.log('filtered cookies length:', cookies.length); // prints 3

    // get cookies filtered by urls
    cookies = await context.cookies('http://foo.com', 'https://baz.com');
    console.log('filtered cookies length:', cookies.length); // prints 2

    // the first filtered cookie
    console.log("1st cookie's name :", cookies[0].name); // prints foo
    console.log("1st cookie's value:", cookies[0].value); // prints foovalue
    // the first filtered cookie
    console.log("2nd cookie's name :", cookies[1].name); // prints baz
    console.log("2nd cookie's value:", cookies[1].value); // prints bazvalue
  } finally {
    await page.close();
  }
}

grantPermissions(permissions[, options])

Mon, 21 Sep 2026 15:16:28 +0000

grantPermissions(permissions[, options])

Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified.

Parameter	Type	Description
permissions	array	A string array of permissions to grant. A permission can be one of the following values: `'geolocation'`, `'midi'`, `'midi-sysex'` (system-exclusive midi), `'notifications'`, `'camera'`, `'microphone'`, `'background-sync'`, `'ambient-light-sensor'`, `'accelerometer'`, `'gyroscope'`, `'magnetometer'`, `'accessibility-events'`, `'clipboard-read'`, `'clipboard-write'`, `'payment-handler'`.
options	object	Optional.
options.origin	string	The origin to grant permissions to, e.g. `'https://example.com'`.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the permissions have been granted.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  await context.grantPermissions(['clipboard-read', 'clipboard-write'], {
    origin: 'https://example.com/',
  });
}

newPage()

Mon, 21 Sep 2026 15:16:28 +0000

newPage()

Uses the browser context to create and return a new page.

Returns

Type	Description
`Promise<Page>`	A Promise that fulfills with a new page object.

Example

import { browser } from 'k6/browser';

export default async function () {
  const context = await browser.newContext();
  const page = await context.newPage();

  try {
    await page.goto('https://test.k6.io/browser.php');
  } finally {
    await page.close();
  }
}

pages()

Mon, 21 Sep 2026 15:16:28 +0000

pages()

Caution
This feature has known issues. For details, refer to #444.

Returns all open Pages in the BrowserContext.

Returns

Type	Description
`Array<Page>`	An array of page objects.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  await context.newPage();
  const pages = context.pages();
  console.log(pages.length); // 1
  await context.close();
}

setDefaultNavigationTimeout(timeout)

Mon, 21 Sep 2026 15:16:28 +0000

setDefaultNavigationTimeout(timeout)

Sets the default maximum navigation timeout for Page.goto().

Parameter	Type	Default	Description
timeout	number	Dependent on the action.	The timeout in milliseconds.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  const page = await context.newPage();
  context.setDefaultNavigationTimeout(1000); // 1s

  try {
    await page.goto('https://quickpizza.grafana.com/api/delay/5');
  } finally {
    await page.close();
  }
}

setDefaultTimeout(timeout)

Mon, 21 Sep 2026 15:16:28 +0000

setDefaultTimeout(timeout)

Sets the default maximum timeout for all methods accepting a timeout option in milliseconds.

Parameter	Type	Default	Description
timeout	number	Dependent on the action.	The timeout in milliseconds.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  context.setDefaultTimeout(1000); // 1s
  const page = await context.newPage();
  await page.click('h2'); // times out
}

setGeolocation(geolocation)

Mon, 21 Sep 2026 15:16:28 +0000

setGeolocation(geolocation)

Caution
This feature has known issues. For details, refer to #435.

Sets the browser context’s geolocation.

Parameter	Type	Default	Description
geolocation	object	`null`
geolocation.latitude	number	`0`	Latitude between -90 and 90.
geolocation.longitude	number	`0`	Latitude between -180 and 180.
geolocation.accuracy	number	`0`	Optional non-negative accuracy value.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the geolocation has been set.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();
  await context.setGeolocation({ latitude: 59.95, longitude: 30.31667 });
}

setOffline(offline)

Mon, 21 Sep 2026 15:16:28 +0000

setOffline(offline)

Toggles the browser context’s connectivity on/off.

Parameter	Type	Default	Description
offline	boolean	`false`	Whether to emulate the browser context being disconnected (`true`) or connected (`false`).

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the connectivity has been set.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();

  await context.setOffline(true);

  const page = await context.newPage();

  try {
    // Will not be able to load the page
    await page.goto('https://test.k6.io/browser.php');
  } finally {
    await page.close();
  }
}

waitForEvent(event[, optionsOrPredicate])

Mon, 21 Sep 2026 15:16:28 +0000

Waits for the event to fire and returns its value. If a predicate function has been set it will pass the value to the predicate function, which must return true for the promise to resolve.

Parameter	Type	Default	Description
event	string	`null`	Name of event to wait for. Currently the `'page'` event is the only one that is supported.
optionsOrPredicate	function\|object	`null`	Optional. If it’s a function, the `'page'` event data will be passed to it and it must return `true` to continue.
optionsOrPredicate.predicate	function	`null`	Optional. Function that will be called when the `'page'` event is emitted. The event data will be passed to it and it must return `true` to continue.
optionsOrPredicate.timeout	number	`30000`	Optional. Maximum time to wait in milliseconds.

Returns

Type	Description
`Promise<Page>`	A Promise that fulfills with a page object when the `page` event has been emitted.

Example

This API is useful when you want to wait for the new page to open after clicking on a link that opens in a new tab.

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const page = await browser.newPage();

  await page.goto('https://test.k6.io/');

  await page.keyboard.down('ControlOrMeta');

  // Open the link in a new tab with the help of the meta key.
  // Wait for the new page to be created.
  const browserContext = browser.context();
  const [newTab] = await Promise.all([
    browserContext.waitForEvent('page'),
    await page.locator('a[href="/my_messages.php"]').click(),
  ]);

  await page.keyboard.up('ControlOrMeta');

  // Wait for the new page (tab) to load.
  await newTab.waitForLoadState('load');

  // Take screenshots of each page.
  await page.screenshot({ path: `screenshot-page.png` });
  await newTab.screenshot({ path: `screenshot-newTab.png` });

  await newTab.close();
  await page.close();
}

Here’s an example working with the predicate:

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const context = await browser.newContext();

  // Call waitForEvent with a predicate which will return true once at least
  // one page has been created.
  let counter = 0;
  const promise = await context.waitForEvent('page', {
    predicate: (page) => {
      if (++counter >= 1) {
        return true;
      }
      return false;
    },
  });

  // Now we create a page.
  const page = await context.newPage();

  // Wait for the predicate to pass.
  await promise;
  console.log('predicate passed');

  await page.close();
}