Menu
Documentationbreadcrumb arrow Grafana k6breadcrumb arrow Using k6 browserbreadcrumb arrow Running browser tests
Open source

Running browser tests

Follow along to learn how to:

  1. Run a test
  2. Interact with elements on your webpage
  3. Wait for page navigation
  4. Run both browser-level and protocol-level tests in a single script

Run a test

To run a simple local script:

  1. Copy the following code, paste it into your favorite editor, and save it as script.js.

    Note that providing an executor and setting the browser scenario option’s type to chromium is mandatory. Please see the options and scenarios documentation for more information.

    JavaScript 
    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('http://test.k6.io/');
    await page.screenshot({ path: 'screenshots/screenshot.png' });
  } finally {
    await page.close();
  }
}

    The preceding code imports the browser the browser module), and uses its newPage method to open a new page.

    After getting the page, you can interact with it using the Page methods. This example visits a test URL and takes a screenshot of the page.

    Subsequently, the page is closed. This allows for the freeing up of allocated resources and enables the accurate calculation of Web Vital metrics.

    Note

    Starting from v0.52.0 the browser module API has been converted to an asynchronous API. That means that most of the methods now return promises. Refer to the migration guide to learn more about the changes and how to update your scripts.

  2. Then, run the test on your terminal with this command:

    bash 
    k6 run script.js
    docker 
    # WARNING!
# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
# 'no-sandbox' argument. Only use it with trustworthy websites.
#
# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
# Chrome arguments to not use 'no-sandbox' such as:
# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# http://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i -v $(pwd):/home/k6/screenshots grafana/k6:master-with-browser run - <script.js
    windows 
    k6 run script.js
    powershell 
    k6 run script.js

    You can also use the browser module options to customize the launching of a browser process. For instance, you can start a headful browser using the previous test script with this command.

    bash 
    K6_BROWSER_HEADLESS=false k6 run script.js
    docker 
    # WARNING!
# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
# 'no-sandbox' argument. Only use it with trustworthy websites.
#
# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
# Chrome arguments to not use 'no-sandbox' such as:
# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# http://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i -v $(pwd):/home/k6/screenshots -e K6_BROWSER_HEADLESS=false grafana/k6:master-with-browser run - <script.js
    windows 
    set "K6_BROWSER_HEADLESS=false" && k6 run script.js
    powershell 
    $env:K6_BROWSER_HEADLESS=false ; k6 run script.js

    Note

    When using Docker to run k6 browser tests, make sure you have pulled the correct image with Chromium built-in. See k6 Installation via Docker for more information.

  3. Optional step: running browser tests in Docker on Mac computers with Apple Silicon:

    1. Make sure you’re running the latest Docker version.

    2. Update Rosetta and export an environment variable with the following:

      bash 
      softwareupdate --install-rosetta &&
  export DOCKER_DEFAULT_PLATFORM=linux/amd64

    3. Select VirtuoFS in Settings > General > VirtuoFS.

    4. Enable the Rosetta emulation in Settings > Features in development > Use Rosetta for x86/amd64 emulation on Apple Silicon.

    5. Restart Docker.

    6. Run the browser image with the following command (adds the --platform flag):

      bash 
      docker run --rm -i --platform linux/amd64 -v $(pwd):/home/k6/screenshots -e K6_BROWSER_HEADLESS=false grafana/k6:master-with-browser run - <script.js