Recommended practices on Grafana Labs

Handle stale or dynamic elements after navigation

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

Modern websites often update the DOM asynchronously after navigation or user interactions. Waiting for navigation to complete isn’t sufficient, as test scripts may still fail or attempt to interact with elements that aren’t yet available.

To avoid these issues, wait for specific elements to appear before you continue your test. Use locator APIs such as waitFor to ensure elements are ready for interaction.

This approach is especially important when you test single-page applications (SPAs) or any pages with dynamic content, where elements may be added, removed, or updated asynchronously.

Example

import { browser } from 'k6/browser';

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

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

  await page.goto('https://test.k6.io/browser.php');
  const text = page.locator('#input-text-hidden');
  await text.waitFor({
    state: 'hidden',
  });
}

Hybrid approach to performance

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

Hybrid performance with k6 browser

An alternative approach to browser-based load testing that’s much less resource-intensive is combining a small number of virtual users for a browser test with a large number of virtual users for a protocol-level test.

You can achieve hybrid performance in multiple ways, often by using different tools. To simplify the developer experience, you can combine k6 browser with core k6 features to write hybrid tests in a single script.

Some of the advantages of running a hybrid performance test are:

Testing real user flows on the frontend while generating a higher load in the backend.
Measuring backend and frontend performance in the same test execution
Increased collaboration between backend and frontend teams since the same tool can be used.

Note
Keep in mind that there is an additional performance overhead when it comes to spinning up a browser VU and that the resource usage will depend on the system under test.

Browser and HTTP test

To run a browser-level and protocol-level test concurrently in k6, you can use scenarios.

The code below shows an example of combining a browser and HTTP test in a single script. While the script exposes the backend to the typical load, it also checks the frontend for any unexpected issues. It also defines thresholds to check both HTTP and browser metrics against pre-defined SLOs.

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

const BASE_URL = __ENV.BASE_URL || 'https://quickpizza.grafana.com';

export const options = {
  scenarios: {
    load: {
      exec: 'getPizza',
      executor: 'ramping-vus',
      stages: [
        { duration: '5s', target: 5 },
        { duration: '10s', target: 5 },
        { duration: '5s', target: 0 },
      ],
      startTime: '10s',
    },
    browser: {
      exec: 'checkFrontend',
      executor: 'constant-vus',
      vus: 1,
      duration: '30s',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
  thresholds: {
    http_req_failed: ['rate<0.01'],
    http_req_duration: ['p(95)<500', 'p(99)<1000'],
    browser_web_vital_fcp: ['p(95) < 1000'],
    browser_web_vital_lcp: ['p(95) < 2000'],
  },
};

export function getPizza() {
  const restrictions = {
    maxCaloriesPerSlice: 500,
    mustBeVegetarian: false,
    excludedIngredients: ['pepperoni'],
    excludedTools: ['knife'],
    maxNumberOfToppings: 6,
    minNumberOfToppings: 2,
  };

  const res = http.post(`${BASE_URL}/api/pizza`, JSON.stringify(restrictions), {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'token abcdef0123456789',
    },
  });

  check(res, {
    'status is 200': (res) => res.status === 200,
  });
}

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

  try {
    await page.goto(BASE_URL);

    await check(page.locator('h1'), {
      header: async (lo) =>
        (await lo.textContent()) == 'Looking to break out of your pizza routine?',
    });

    await Promise.all([
      page.locator('//button[. = "Pizza, Please!"]').click(),
      page.waitForTimeout(500),
    ]);
    await page.screenshot({ path: `screenshots/${__ITER}.png` });

    await check(page.locator('div#recommendations'), {
      recommendation: async (lo) => (await lo.textContent()) != '',
    });
  } finally {
    await page.close();
  }
}

If you save that script to a local file named test.js, you can run it with:

k6 run test.js

To work on one part of the hybrid test, select its scenario without editing the script:

k6 run --scenario load test.js
k6 run --scenario browser test.js

The load selection keeps its ramping stages and delayed start. The browser selection keeps its browser settings and runs with one VU for 30 seconds. The example’s thresholds have no scenario filter, so all remain active when you select either scenario; selection does not remove thresholds merely because their metrics come from the excluded workload.

The script also includes a common best practice by defining a BASE_URL variable, and using the environment variable value __ENV.BASE_URL if it exists. That’s useful if you want to use the same script for multiple environments, such as staging and production, and you could pass that value to your script with the command:

k6 run -e BASE_URL=https://quickpizza.grafana.com test.js

Browser and failure injection test

You can also run a browser test together with a failure injection test by using the xk6-disruptor extension. This approach lets you find issues in your frontend if any services it depends on are suddenly injected with failures, such as delays or server errors.

The following code shows an example of how you could use the xk6-disruptor extension to introduce faults to a Kubernetes service. At the same time, the browser scenario runs to ensure the frontend application is free of any unexpected errors that may not have been handled properly.

To find out more information about injecting faults to your service, check out the Get started with xk6-disruptor guide.

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

const BASE_URL = __ENV.BASE_URL;

export const options = {
  scenarios: {
    disrupt: {
      executor: 'shared-iterations',
      iterations: 1,
      vus: 1,
      exec: 'disrupt',
    },
    browser: {
      executor: 'constant-vus',
      vus: 1,
      duration: '10s',
      startTime: '10s',
      exec: 'browser',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
  thresholds: {
    browser_web_vital_fcp: ['p(95) < 1000'],
    browser_web_vital_lcp: ['p(95) < 2000'],
  },
};

// Add faults to the service by introducing a delay of 1s and 503 errors to 10% of the requests.
const fault = {
  averageDelay: '1000ms',
  errorRate: 0.1,
  errorCode: 503,
};

export function disrupt() {
  const disruptor = new ServiceDisruptor('pizza-info', 'pizza-ns');
  const targets = disruptor.targets();
  if (targets.length == 0) {
    throw new Error('expected list to have one target');
  }

  disruptor.injectHTTPFaults(fault, '20s');
}

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

  try {
    await page.goto(BASE_URL);
    await check(page.locator('h1'), {
      header: async (lo) =>
        (await lo.textContent()) == 'Looking to break out of your pizza routine?',
    });

    await Promise.all([
      page.locator('//button[. = "Pizza, Please!"]').click(),
      page.waitForTimeout(500),
    ]);
    await page.screenshot({ path: `screenshots/${__ITER}.png` });

    await check(page.locator('div#recommendations'), {
      recommendation: async (lo) => (await lo.textContent()) != '',
    });
  } finally {
    await page.close();
  }
}

Recommended practices

Start small. Start with a small number of browser-based virtual users. A good starting point is to have 10% virtual users or less to monitor the user experience for your end-users, while the script emulates around 90% of traffic from the protocol level.
Combine browser test with different load testing types. To fully understand the impact of different traffic patterns on your end-user experience, experiment with running your browser test with different load testing types.
Focus on high-risk user journeys as a start. Identify the high-risk user journeys first so you can start monitoring the web performance metrics for them while your backend applications are being exposed to high traffic or service faults.

Page object model

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

Page object model

When working with large test suites, a popular design pattern to improve your code’s maintainability and readability is the page object model.

A page object commonly represents an HTML page or significant elements/components within a page, such as a header or a footer. It’s a form of encapsulation that hides the details of the UI structure from other places, such as your test files. Through page object models, any changes you need to make on a specific page or element within a page are constrained into a single place, resulting in ease of maintenance and avoiding code duplication.

Since k6 browser is inspired by Playwright, you can leverage any existing page objects you have and re-use them with your k6 browser tests.

Implementation

Let’s take an example of a website with a booking form added to the homepage. Imagine you want to write a test that checks that a user can fill out the booking form successfully.

To model a page object for the homepage, we’ve created a page object class called homepage.js. Different locators are created inside the constructor so that when the homepage class is instantiated, the page locator elements are ready to be used.

The homepage.js class also contains different methods for:

Navigating to the homepage
Submitting the form
Getting the verification message

When locators need to be updated or other specific changes related to the homepage are made, you only need to update the homepage.js class.

import { bookingData } from '../data/booking-data.js';

export class Homepage {
  constructor(page) {
    this.page = page;
    this.nameField = page.locator('[data-testid="ContactName"]');
    this.emailField = page.locator('[data-testid="ContactEmail"]');
    this.phoneField = page.locator('[data-testid="ContactPhone"]');
    this.subjectField = page.locator('[data-testid="ContactSubject"]');
    this.descField = page.locator('[data-testid="ContactDescription"]');
    this.submitButton = page.locator('#submitContact');
    this.verificationMessage = page.locator('.row.contact h2');
  }

  async goto() {
    await this.page.goto('https://myexamplewebsite/');
  }

  async submitForm() {
    const { name, email, phone, subject, description } = bookingData;

    this.nameField.type(name);
    this.emailField.type(email);
    this.phoneField.type(phone);
    this.subjectField.type(subject);
    this.descField.type(description);
    await this.submitButton.click();
  }

  async getVerificationMessage() {
    return this.verificationMessage.innerText();
  }
}

You can import the Homepage class within your test class and invoke the methods you need. This makes the code easier to understand and enforces the separation between your test and business logic.

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.0/index.js';

import { Homepage } from '../pages/homepage.js';
import { bookingData } from '../data/booking-data.js';

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

  const { name } = bookingData;

  const homepage = new Homepage(page);
  await homepage.goto();
  await homepage.submitForm();

  expect(await homepage.getVerificationMessage()).to.contain(name);

  await page.close();
}

Prevent cookie banners from blocking interactions

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

Cookie banners often appear shortly after a page loads or remain hidden until you interact with the page. Leaving a banner open can block page elements and cause interaction failures. For example, a button might not be clickable because the banner overlaps it. If you find yourself using force click frequently, the element is likely hidden or overlapped by a cookie banner.

To avoid these failures, trigger and dismiss the cookie banner early in the test flow.

Trigger the banner: simulate a small user action, such as clicking or scrolling, immediately after navigation to reveal banners that appear only after interaction.
Dismiss the banner: once the banner is visible, close or accept it before continuing with the rest of the test.

Example

The example below navigates to a page and clicks a button. Replace the placeholder steps with a click to an element on your website, or scrolling a page, that reveals and dismisses your site’s cookie banner.

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/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://quickpizza.grafana.com/');

    // Click an element to trigger a cookie banner.
    // Clicking an element also scrolls the page if the
    // element is outside the frame.
    const button = page.locator('button[name="pizza-please"]')
    await expect(button).toBeEnabled();
    await button.click();

    // Dismiss the cookie banner
    const cookieBannerButton = page.locator('button[name="dismiss-cookie"]')
    await expect(button).toBeEnabled();
    await button.click();
  } finally {
    await page.close();
  }
}

Prevent too many time series error

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

Prevent too many time series error

Modern websites are complex and make a large number of requests to function as intended by their developers. These requests no longer serve only content for display to the end user but also retrieve insights, analytics, advertisements, and cache-busting purposes. Such requests are usually generated dynamically and may contain frequently changing IDs, posing challenges when correlating and analyzing your k6 test results.

When load testing a website using the k6 browser module, these dynamic requests can result in a high number of similar-looking requests, making it difficult to correlate them and extract valuable insights. This can also lead to test errors, such as a too-many-metrics error, due to high cardinality from metrics tagged with similar but dynamically changing URLs.

This issue also affects synthetic tests. While you may not encounter the too-many-metrics error, you may end up with a large amount of uncorrelated metric data that cannot be tracked effectively over time.

To address this, the browser module has a page.on(‘metric’) method, which allows you to define URL patterns using regex for matching. When a match is found, the URL and name tags for the metric are replaced with the new name.

Example usage

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();

  // Here, we set up an event listener using page.on('metric').
  // You can call page.on('metric') multiple times, and each callback function
  // will be executed in the order that page.on was called.
  page.on('metric', (metric) => {
    // Currently, metric.tag is the only available method on the metric object.
    // It enables matching on the URL tag using a specified regex pattern.
    // You can call metric.tag multiple times within the callback function.
    metric.tag({
      // This is the new name assigned to any metric that matches the defined
      // URL pattern below.
      name: 'test',
      // Provide one or more match patterns here. Any metrics that match a pattern
      // will use the new name specified above.
      matches: [
        // Each match pattern can include a URL and an optional method.
        // When a method is specified, the metric must match both the URL pattern
        // and the method. If no method is provided, the pattern will match all
        // HTTP methods.
        { url: /^https:\/\/test\.k6\.io\/\?q=[0-9a-z]+$/, method: 'GET' },
      ],
    });
  });

  try {
    // The following lines are for demonstration purposes.
    // Visiting URLs with different query parameters (q) to illustrate matching.
    await page.goto('https://test.k6.io/?q=abc123');
    await page.goto('https://test.k6.io/?q=def456');
  } finally {
    // Ensure the page is closed after testing.
    await page.close();
  }
}

Select elements

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

Select elements

Selectors are strings that represents a specific DOM element on the page. When writing browser-level tests, it’s recommended to use selectors that are robust to avoid test flakiness when the DOM structure changes.

Currently, the browser module supports the standard CSS and XPath selectors.

Note
Text-based selectors are currently not supported. This will be supported in future releases.

Recommended practices

The selectors that you choose should not be tightly coupled to any behaviour or styling changes. If your application is prone to changes frequently, it’s recommended to use user-facing attributes or custom data attributes as these are not tightly coupled to the element.

Selector	Notes
✅ `page.locator('[aria-label="Login"]')`	User-facing attributes such as ARIA labels are rarely changed so these are great candidates.
✅ `page.locator('[data-test="login"]')`	Custom data attributes are not tightly coupled to the element.
✅ `page.locator('//button[text()="Submit"]')`	Text selectors are also great as text content rarely changes. While we don’t support text-based selectors as of yet, xpath can be used as a workaround.
⚠️ `page.locator('#login-btn')`	Selecting an element via its ID is also recommended if the ID doesn’t change.
⚠️ `page.locator('.login-btn')`	Selecting an element via its class name should be kept to a minimum as class names can be duplicated.
❌ `page.locator('button')`	Generic elements are not recommended because this has no context.
❌ `page.locator('/html[1]/body[1]/main[1]`	Absolute paths are not recommended as these are tightly coupled to the DOM structure.

Simulate user input delay

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

Simulate user input delay

On this page, you’ll learn how to best work with sleep in k6 and the various wait* prepended methods available in k6/browser to simulate user input delay, wait for navigations, and wait for element state changes. By the end of this page, you should be able to successfully use the correct API where necessary.

Note
While using the sleep or page.waitForTimeout functions to wait for element state changes may seem helpful, it’s best to avoid them to prevent flakey tests. Instead, it’s better to use the other wait* prepended methods listed on this page.

What is `sleep`?

sleep is a first class function built into k6. It’s main use is to “suspend VU execution for the specified duration” which is most useful when you want to simulate user input delay, such as:

Navigating to a page.
Sleeping for one second to simulate a user looking for a specific element on the page.
Clicking on the element.

Warning
sleep is a synchronous function that blocks the JavaScript event loop, which means that all asynchronous work will also be suspended until sleep completes.

The browser module predominantly provides asynchronous APIs, so it’s best to avoid working with sleep. Instead, use the page.waitForTimeout function. Refer to When to use sleep() and page.waitForTimeout() for more details.

What is `wait*`?

In the browser modules there are various asynchronous APIs that can be used to wait for certain states:

Method	Description
browserContext.waitForEvent	Waits for the selected event to fire and returns its value.
page.waitForFunction	Waits for the given function to return a truthy value.
page.waitForLoadState	Waits for the specified page life cycle event.
page.waitForNavigation	Waits for the navigation to complete after one starts.
page.waitForResponse	Wait for an HTTP response that matches the specified URL pattern.
page.waitForRequest	Wait for an HTTP request that matches the specified URL pattern.
page.waitForTimeout	Waits the given time. Use this instead of `sleep` in your frontend tests.
page.waitForURL	Wait for the page to navigate to the specified URL.
locator.waitFor	Wait for the element to be in a particular state.

browserContext.waitForEvent

browserContext.waitForEvent is used when waiting for specific events to fire, which then returns the element associated to that event. At the moment the only event that is available to use is page. It can be useful when you want to track and retrieve a new tab opening. When working with a predicate function, it can be used to wait for a specific page to open before returning true.

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'),
    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();
}

page.waitForFunction

page.waitForFunction is useful when you want more control over when a test progresses with a javascript function that returns true when a condition (or many conditions) is met. It can be used to poll for changes in the DOM or non-DOM elements and variables.

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 page = await browser.newPage();

  try {
    // Setting up the example that will mutate the h1 element by setting the
    // h1 elements text value to "Hello".
    await page.evaluate(() => {
      setTimeout(() => {
        const el = document.createElement('h1');
        el.innerHTML = 'Hello';
        document.body.appendChild(el);
      }, 1000);
    });

    // Waiting until the h1 element has mutated.
    const ok = await page.waitForFunction("document.querySelector('h1')", {
      polling: 'mutation',
      timeout: 2000,
    });

    await check(ok, {
      'waitForFunction successfully resolved': async (ok) => (await ok.innerHTML()) == 'Hello',
    });
  } finally {
    await page.close();
  }
}

page.waitForLoadState

page.waitForLoadState is useful when there’s no explicit navigation, but you need to wait for the page or network to settle. This is mainly used when working with single-page applications or when no full page reloads happen.

import { browser } from 'k6/browser';

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

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

  try {
    // Goto a SPA
    await page.goto('<url>');

    // ... perform some actions that reload part of the page.

    // waits for the default `load` event.
    await page.waitForLoadState();
  } finally {
    await page.close();
  }
}

page.waitForNavigation

page.waitForNavigation is a very useful API when performing other actions that could start a page navigation, and they don’t automatically wait for the navigation to end. Usually, you’ll find it in our examples with a click API call. Note that goto is an example of an API that doesn’t require waitForNavigation since it will automatically wait for the navigation to complete before returning.

It’s important to call this in a Promise.all along with the API that will cause the navigation to start.

import { browser } from 'k6/browser';

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

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"]');

    // The click action will start a navigation, and the waitForNavigation
    // will help the test wait until the navigation completes.
    await Promise.all([page.waitForNavigation(), submitButton.click()]);
  } finally {
    await page.close();
  }
}

page.waitForResponse

page.waitForResponse waits for an HTTP response that matches the specified URL pattern. This method is particularly useful for waiting for responses from AJAX/fetch requests, API calls, or specific resources to be loaded before proceeding with the test.

import { browser } from 'k6/browser';
import { check } from 'k6';

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

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

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

    // Test waitForResponse with user interaction
    const pizzaResponsePromise = page.waitForResponse('https://quickpizza.grafana.com/api/pizza');

    await page.getByRole('button', { name: /pizza/i }).click();

    const pizzaResponse = await pizzaResponsePromise;

    // Check that the pizza API call was successful
    check(pizzaResponse, {
      'pizza API status is 200': (r) => r.status() === 200,
      'pizza API URL is correct': (r) => r.url() === 'https://quickpizza.grafana.com/api/pizza',
    });
  } finally {
    await page.close();
  }
}

page.waitForRequest

page.waitForRequest waits for an HTTP request that matches the specified URL pattern. This method is particularly useful for waiting for requests to be initiated before proceeding with the test, such as verifying that form submissions or API calls are triggered.

import { browser } from 'k6/browser';
import { check } from 'k6';

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

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

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

    // Test waitForRequest with user interaction
    const pizzaRequestPromise = page.waitForRequest('https://quickpizza.grafana.com/api/pizza');

    await page.getByRole('button', { name: /pizza/i }).click();

    const pizzaRequest = await pizzaRequestPromise;

    // Check that the pizza API request was initiated
    check(pizzaRequest, {
      'pizza API URL is correct': (r) => r.url() === 'https://quickpizza.grafana.com/api/pizza',
      'pizza API method is POST': (r) => r.method() === 'POST',
    });
  } finally {
    await page.close();
  }
}

page.waitForTimeout

page.waitForTimeout will wait the given amount of time. It’s functionally the same as k6’s sleep, but it’s asynchronous, which means it will not block the event loop and allows the background tasks to continue to be worked on.

import { browser } from 'k6/browser';

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

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

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

    // Slow the test down to mimic a user looking for the element on the page.
    await page.waitForTimeout(1000);

    // ... perform the next action
  } finally {
    await page.close();
  }
}

page.waitForURL

page.waitForURL waits for the page to navigate to the specified URL. This method is useful for ensuring that navigation to a particular URL has completed before proceeding with the test. This is especially useful if there are multiple redirects before hitting the end destination.

import { browser } from 'k6/browser';

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

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

  try {
    await page.goto('https://quickpizza.grafana.com/test.k6.io/');

    // Wait for navigation to a specific URL
    await Promise.all([
      page.click('a[href="/my_messages.php"]'),
      page.waitForURL('https://quickpizza.grafana.com/my_messages.php'),
    ]);

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

    // Wait for navigation using URL pattern with RegExp
    await Promise.all([page.click('a[href="/browser.php"]'), page.waitForURL(/\/browser\.php$/)]);
  } finally {
    await page.close();
  }
}

locator.waitFor

locator.waitFor will wait until the element meets the waiting criteria. It’s useful when dealing with dynamic websites where elements may take time to appear or change state. For example, if elements load after some delay due to async calls, or because of slow JavaScript execution.

import { browser } from 'k6/browser';

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

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

  await page.goto('https://test.k6.io/browser.php');
  const text = page.locator('#input-text-hidden');
  await text.waitFor({
    state: 'hidden',
  });
}

Use Page.close to clean up test resources

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

Use Page.close to clean up test resources

When running k6 browser tests with event-based APIs, such as page.on, tests may not always properly flush metrics or clean up resources automatically, which can lead to incomplete metric reporting or leftover event handlers.

To prevent this, always call page.close() at the end of your browser tests. Doing so ensures accurate and complete metric collection, cleans up event listeners to prevent resource leaks, and simplifies test teardown for improved reliability.

Example

import { browser } from "k6/browser";
import { check } from "k6";

const BASE_URL = __ENV.BASE_URL || "https://quickpizza.grafana.com/";

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

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

    await page.goto(BASE_URL);
    checkData = await page.locator("h1").textContent();
    check(page, {
      header: checkData == "Looking to break out of your pizza routine?",
    });

    await page.locator('//button[. = "Pizza, Please!"]').click();
    await page.waitForTimeout(500);
    await page.screenshot({ path: "screenshot.png" });
    checkData = await page.locator("div#recommendations").textContent();
    check(page, {
      recommendation: checkData != "",
    });
  } finally {
    //Always close the page at the end
    await page.close();
  }
}

When to use sleep() and page.waitForTimeout()

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

When to use sleep() and page.waitForTimeout()

In Grafana k6, both sleep() and page.waitForTimeout() can be used to add pauses in your test scripts, but they work very differently. Understanding these differences is essential for accurate and reliable browser testing.

sleep() is synchronous, blocking the thread and halting all background activity.
page.waitForTimeout() is asynchronous, allowing background events to continue while pausing the script.

For most browser-based scenarios, you should use page.waitForTimeout() to simulate user delays without interrupting normal browser behavior or affecting performance measurements.

When to use `sleep()`

sleep() is a built-in k6 function designed to suspend Virtual User (VU) execution for a specified duration. It’s a synchronous function that blocks the JavaScript event loop, which means that all asynchronous work is also suspended until sleep completes.

It’s best used to simulate:

Navigating to a page
Sleeping for one second to simulate a user looking for a specific element on the page
Clicking on the element

When to use `page.waitForTimeout()`

page.waitForTimeout() is a function provided by the k6 browser module that pauses script execution for a specified amount of time without blocking the JavaScript event loop.

Unlike sleep(), it’s asynchronous, meaning other browser activities, such as rendering, network requests, and event handling, can continue while the delay is in effect. This makes it ideal for browser based testing, where multiple asynchronous operations happen in the background.

You can use page.waitForTimeout() to simulate real user pauses, like reading a page, waiting for a visual change, or mimicking natural interaction timing, all without interrupting the browser’s internal processes.

Recommended practices on Grafana Labs

Handle stale or dynamic elements after navigation

Handle stale or dynamic elements after navigation

Example

Hybrid approach to performance

Hybrid performance with k6 browser

Browser and HTTP test

Browser and failure injection test

Recommended practices

Page object model

Page object model

Implementation

Prevent cookie banners from blocking interactions

Prevent cookie banners from blocking interactions

Example

Prevent too many time series error

Prevent too many time series error

Example usage

Select elements

Select elements

Recommended practices

Simulate user input delay

Simulate user input delay

What is sleep?

What is wait*?

browserContext.waitForEvent

page.waitForFunction

page.waitForLoadState

page.waitForNavigation

page.waitForResponse

page.waitForRequest

page.waitForTimeout

page.waitForURL

locator.waitFor

Use Page.close to clean up test resources

Use Page.close to clean up test resources

Example

When to use sleep() and page.waitForTimeout()

When to use sleep() and page.waitForTimeout()

When to use sleep()

When to use page.waitForTimeout()

What is `sleep`?

What is `wait*`?

When to use `sleep()`

When to use `page.waitForTimeout()`