Overview

suggest edits

Experimental module
While we intend to keep experimental modules as stable as possible, we may need to introduce breaking changes. This could happen at future k6 releases until the module becomes fully stable and graduates as a k6 core module. For more information, refer to the extension graduation process.
Experimental modules maintain a high level of stability and follow regular maintenance and security measures. Feel free to open an issue if you have any feedback or suggestions.

The Browser module brings browser automation and end-to-end web testing to k6 while supporting core k6 features. It adds browser-level APIs to interact with browsers and collect frontend performance metrics as part of your k6 tests.

This module aims to provide rough compatibility with the Playwright API, so you don’t need to learn a completely new API.

note
To work with the browser module, make sure you are using the latest k6 version, and install a Chromium-based browser on your machine (such as Google Chrome).

Use case for browser testing

The main use case for the browser module is to test performance on the browser level. Browser-level testing provides a way to measure user experience and find issues that are difficult to catch on the protocol level. Browser-level testing can help you answer questions like:

When my application is receiving thousands of simultaneous requests from the protocol-level, what happens to the frontend?
How can I get metrics specific to browsers, like total page load time?
Are all my elements interactive on the frontend?
Are there any loading spinners that take a long time to disappear?

A simple browser test

1import { browser } from 'k6/experimental/browser';
2import { check } from 'k6';
3
4export const options = {
5  scenarios: {
6    ui: {
7      executor: 'shared-iterations',
8      options: {
9        browser: {
10          type: 'chromium',
11        },
12      },
13    },
14  },
15  thresholds: {
16    checks: ["rate==1.0"]
17  }
18}
19
20export default async function () {
21  const context = browser.newContext();
22  const page = context.newPage();
23
24  try {
25    await page.goto('https://test.k6.io/my_messages.php');
26
27    page.locator('input[name="login"]').type('admin');
28    page.locator('input[name="password"]').type('123');
29
30    const submitButton = page.locator('input[type="submit"]');
31
32    await Promise.all([page.waitForNavigation(), submitButton.click()]);
33
34    check(page, {
35      'header': p => p.locator('h2').textContent() == 'Welcome, admin!',
36    });
37  } finally {
38    page.close();
39  }
40}

The preceding code launches a Chromium-based browser, visits the application and mimics a user logging in to the application. Once submitted, it checks if the text of the header matches what is expected.

note
We're currently (February 2023) migrating most browser module APIs to be async and return a Promise. To make this simpler, our goal is to use the async/await keywords. For more information, check out Running browser tests.

After running the test, the following browser metrics will be reported.

          /\      |‾‾| /‾‾/   /‾‾/
     /\  /  \     |  |/  /   /  /
    /  \/    \    |     (   /   ‾‾\
   /          \   |  |\  \ |  (‾)  |
  / __________ \  |__| \__\ \_____/ .io

  execution: local
     script: test.js
     output: -

  scenarios: (100.00%) 1 scenario, 1 max VUs, 10m30s max duration (incl. graceful stop):
           * default: 1 iterations for each of 1 VUs (maxDuration: 10m0s, gracefulStop: 30s)


running (00m01.3s), 0/1 VUs, 1 complete and 0 interrupted iterations
ui   ✓ [======================================] 1 VUs  00m01.3s/10m0s  1/1 shared iters

     ✓ header

     browser_data_received.......: 2.6 kB  2.0 kB/s
     browser_data_sent...........: 1.9 kB  1.5 kB/s
     browser_http_req_duration...: avg=215.4ms  min=124.9ms med=126.65ms max=394.64ms p(90)=341.04ms p(95)=367.84ms
     browser_http_req_failed.....: 0.00%   ✓ 0        ✗ 3  
     browser_web_vital_cls.......: avg=0        min=0       med=0        max=0        p(90)=0        p(95)=0       
     browser_web_vital_fcp.......: avg=344.15ms min=269.2ms med=344.15ms max=419.1ms  p(90)=404.11ms p(95)=411.6ms 
     browser_web_vital_fid.......: avg=200µs    min=200µs   med=200µs    max=200µs    p(90)=200µs    p(95)=200µs   
     browser_web_vital_inp.......: avg=8ms      min=8ms     med=8ms      max=8ms      p(90)=8ms      p(95)=8ms     
     browser_web_vital_lcp.......: avg=419.1ms  min=419.1ms med=419.1ms  max=419.1ms  p(90)=419.1ms  p(95)=419.1ms 
     browser_web_vital_ttfb......: avg=322.4ms  min=251ms   med=322.4ms  max=393.8ms  p(90)=379.52ms p(95)=386.66ms
   ✓ checks......................: 100.00% ✓ 1        ✗ 0  
     data_received...............: 0 B     0 B/s
     data_sent...................: 0 B     0 B/s
     iteration_duration..........: avg=1.28s    min=1.28s   med=1.28s    max=1.28s    p(90)=1.28s    p(95)=1.28s   
     iterations..................: 1       0.777541/s
     vus.........................: 1       min=1      max=1
     vus_max.....................: 1       min=1      max=1

This gives you a representation of browser performance, via the web vitals, as well as the HTTP requests that came from the browser.

Get started

Using k6

Using k6 browser

Results output

Test authoring

Test types

Testing guides

Misc

Overview

Experimental module

Use case for browser testing

A simple browser test

Product

Resources

Community

About