Asynchronous operations

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

Asynchronous operations

Most methods in the browser module return JavaScript promises, and k6 scripts must be written to handle this properly. This usually means using the await keyword to wait for the async operation to complete.

For example:

const page = await browser.newPage();

await page.goto('https://quickpizza.grafana.com/');

const locator = page.locator('button[name="pizza-please"]');

await locator.click();

In addition to using await, another important part of writing k6 browser tests is handling page navigations. There are two recommended methods for doing that: using Promise.all or using the waitFor method.

Promise.all

To avoid timing errors or other race conditions in your script, if you have actions that load up a different page, you need to make sure that you wait for that action to finish before continuing.

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

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
  thresholds: {
    checks: ['rate==1.0'],
  },
};

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

  try {
    await page.goto('https://test.k6.io/my_messages.php');

    await page.locator('input[name="login"]').type('admin');
    await page.locator('input[name="password"]').type('123');

    const submitButton = page.locator('input[type="submit"]');

    await Promise.all([page.waitForNavigation(), submitButton.click()]);

    await check(page.locator('h2'), {
      header: async (lo) => (await lo.textContent()) == 'Welcome, admin!',
    });
  } finally {
    await page.close();
  }
}

The preceding code uses Promise.all([]) to wait for the two promises to be resolved before continuing. Since clicking the submit button causes page navigation, page.waitForNavigation() is needed because the page won’t be ready until the navigation completes. This is required because there can be a race condition if these two actions don’t happen simultaneously.

Then, you can use check from the k6 API to assert the text content of a specific element. Finally, you close the page and the browser.

Wait for specific elements

We also encourage the use of locator.waitFor where possible. When you navigate to a website, there are usually one or more elements that are important for your test. Once those elements load, you can safely proceed to the next step. For example, in a search scenario:

Navigate to the search site
Wait for the search bar and submit button to appear
Fill in the search bar with the query
Click the submit button
Wait for the search results

We should be able to do these actions like so:

await page.goto('https://my-search-engine.com');

const searchBar = page.locator('.search-bar');
const submitButton = page.locator('.submit-button');

await searchBar.waitFor();
await submitButton.waitFor();

await searchBar.fill('k6');
await submitButton.click();

const searchResults = page.locator('.search-results-table');

await searchResults.waitFor();

This avoids the use of Promise.all which can be confusing to work with, and instead makes the script easier to follow.

Why the browser module uses asynchronous APIs

The browser module uses asynchronous APIs that require await for several reasons:

JavaScript is single-threaded with a single event loop. Asynchronous APIs prevent blocking the thread and event loop with long-running or I/O-based tasks.
Consistency with Playwright and other frontend testing frameworks.
Alignment with how developers expect to work with modern JavaScript APIs.

For example:

const page = await browser.newPage();

await page.goto('https://quickpizza.grafana.com/');

const locator = page.locator('button[name="pizza-please"]');

await locator.click();

API calls that interact with Chromium are asynchronous and require await to ensure completion before proceeding. Synchronous APIs, such as page.locator, do not require await, but using it does not cause issues since the JavaScript runtime will simply return the value immediately.

If you don’t add await on asynchronous APIs, it can cause the script to finish before the test completes, resulting in errors like "Uncaught (in promise) TypeError: Object has no member 'goto'". That can happen because the page object from browser.newPage() without an await is actually a JavaScript promise. You can try and see the error using the following code snippet:

const page = browser.newPage();

page.goto('https://quickpizza.grafana.com/'); // An error should occur since we're not using await in the line above.

const locator = page.locator('button[name="pizza-please"]');

locator.click();

Interact with elements on your webpage

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

Interact with elements on your webpage

You can use page.locator() and pass in the element’s selector you want to find on the page. page.locator() will create and return a Locator object, which you can later use to interact with the element.

To find out which selectors the browser module supports, check out Selecting Elements.

Note
You can also use page.$() instead of page.locator(). You can find the differences between page.locator() and page.$ in the Locator API documentation.

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
  thresholds: {
    checks: ['rate==1.0'],
  },
};

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

  try {
    await page.goto('https://test.k6.io/my_messages.php');

    // Enter login credentials
    await page.locator('input[name="login"]').type('admin');
    await page.locator('input[name="password"]').type('123');

    await page.screenshot({ path: 'screenshots/screenshot.png' });
  } finally {
    await page.close();
  }
}

The preceding code creates and returns a Locator object with the selectors for both login and password passed as arguments.

Within the Locator API, various methods such as type() can be used to interact with the elements. The type() method types a text to an input field.

How to write browser tests on Grafana Labs

Asynchronous operations

Asynchronous operations

Promise.all

Wait for specific elements

Why the browser module uses asynchronous APIs

Interact with elements on your webpage

Interact with elements on your webpage