---
title: "Run your first browser tests | Grafana Cloud documentation"
description: "Use the Grafana k6 browser-testing APIs to interact with your sites and inspect their performance by running browser tests."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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](/docs/k6/latest/javascript-api/k6-browser/) 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](/auth/sign-up/create-user).

## 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

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/admin');

    await page.locator('input[name="username"]').fill('admin');
    await page.locator('input[name="password"]').fill('admin');

    await page.waitForLoadState('networkidle'); // waits until the `networkidle` event

    await page.locator('button[type="submit"]').click();

    const label = await page.locator('h2');
    const textContent = (await label.textContent()).trim();

    check(textContent, {
      header: (t) => t === 'Latest pizza recommendations',
    });
  } finally {
    await page.close();
  }
}
```

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 `https://quickpizza.grafana.com/admin` 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
k6 cloud <TEST_SCRIPT>.js
```

For detailed CLI instructions, refer to [Run cloud tests from the CLI](/docs/k6/latest/using-k6-browser/running-browser-tests/).

> Note
> 
> *Browser VUs* consume 10 times more VU hours compared to *Protocol VUs*. For more details, refer to [Understand your Performance Testing invoice](/docs/grafana-cloud/cost-management-and-billing/understand-your-invoice/performance-testing-invoice/).

### Local execution

To develop and debug your tests, you can [run browser tests from your local machine](/docs/k6/latest/using-k6-browser/running-browser-tests/). To run browser tests locally, use the following `k6 run` command:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
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](/docs/grafana-cloud/testing/k6/analyze-results/view-browser-timeline-screenshots/).

## Cloud options

You can define [cloud options](/docs/grafana-cloud/testing/k6/author-run/cloud-scripting-extras/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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

> Note
> 
> For browser tests with multiple Virtual Users (VUs), Grafana Cloud k6 automatically scales browser executions within the specified load zones.
> 
> Refer to [Grafana Cloud features](/docs/grafana-cloud/cost-management-and-billing/understand-grafana-cloud-features/#k6-testing) for the maximum number of Virtual Users you can configure for a browser test.

## Next steps

You have your first browser test using the `quickpizza.grafana.com` 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](/docs/k6/latest/using-k6-browser/running-browser-tests/#run-both-browser-level-and-protocol-level-tests-in-a-single-script).

To learn more about browser testing with k6, refer to [Using k6 browser](/docs/k6/latest/using-k6-browser/).