DocumentationGrafana CloudTesting and syntheticsPerformance testingGet startedRun your first browser tests

Run your first browser tests

With k6, you can run performance tests that target the browser to measure user experience and find issues that are difficult to catch at the protocol level. These tests leverage the k6 browser-testing APIs and allow you to interact with your sites and inspect their performance.

In this tutorial, learn how to:

• Create a browser test script.
• Run a browser script in Grafana Cloud k6.
• Explore test results.

Before you begin

To run a browser test, you’ll need:

• A Grafana Cloud account.

Create a browser test script

Before running your first browser test, you need to create your test script. The Script Editor in Grafana Cloud k6 provides a quick way to prototype tests directly from the app. It includes a library of examples that you can leverage as a starting point or reference while developing your tests.

To create a browser test:

1. Log in to your Grafana Cloud instance.
2. Open the menu and select Performance testing.
3. Select Start testing if you haven’t created any projects.
   1. Select Default project if you have already initialized Performance testing in your Grafana Cloud instance.
4. Select Create new test, and then select Start scripting.
5. Click the Script examples drop-down, and pick the Browser testing example.

Now, you’ll be able to see a test in the editor similar to this one:

JavaScript Copy

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

export const options = {
  scenarios: {
    ui: {
      executor: 'constant-vus',
      vus: 1,
      duration: '10s',
      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 = await page.locator('input[type="submit"]');

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

    const headerText = await page.locator('h2').textContent();
    check(headerText, {
      header: headerText === 'Welcome, admin!',
    });
  } finally {
    await page.close();
  }
  sleep(1);
}

The k6 browser APIs are designed to be roughly compatible with the Playwright API. The example script shows you how to:

• Import the browser module.
• Set up the required browser option in the scenarios configuration.
• Open a new page by using the browser.newPage() method.
• Go to a “test.k6.io” URL by using the page.goto() method.
• Use the page.locator method to fill out and submit a form.
• Use the check method to verify that the login was successful.

One VU executes the logic repeatedly with a one-second sleep between iterations. The test will finish after ten seconds have passed.

Run a browser test

You can run the browser test from your local machine or from Grafana Cloud k6.

Cloud execution

After creating the browser test script in the Script Editor, click on Create and Run to run it in Grafana Cloud k6.

Alternatively, if you prefer using the CLI, you can save your script locally and run:

bash Copy

k6 cloud <TEST_SCRIPT>.js

For detailed CLI instructions, refer to Run cloud tests from the CLI.

Local execution

To develop and debug your tests, you can run browser tests from your local machine. To run browser tests locally, use the following k6 run command:

bash Copy

k6 run <TEST_SCRIPT>.js

Explore results

The Test Result view displays relevant information for browser tests, such as the 75th percentile of web vitals and how they behave over time.

The data and visualizations update in real-time while the test runs.

For further details, refer to Inspect browser test results.

Cloud options

You can define cloud options in browser tests running in Grafana Cloud k6. The following example uses the cloud property to configure a load zone, test name, and project ID:

JavaScript Copy

export const options = {
  cloud: {
    name: 'My first k6 browser test!',
    projectID: 123456,
    distribution: {
      eu: { loadZone: 'amazon:ie:dublin', percent: 100 },
    },
  },
};

Next steps

You have your first browser test using the test.k6.io website as an example. You can customize your test or create a new one to interact with your sites and start inspecting their performance. You can also run a load test targeting your APIs while validating how good the experience for end-users would be in-app, all in the same test.

To learn more about browser testing with k6, refer to Using k6 browser.