This is documentation for the next version of Grafana k6 documentation. For the latest stable release, go to the latest version.

Set up

Set up distributed k6

Run browser tests in Kubernetes

Open source

Run browser tests in Kubernetes

Running browser tests in Kubernetes provides several benefits especially in locked down environments. Some reasons you might want to run browser tests in Kubernetes include staying consistent with other testing tools and infrastructure components in your Kubernetes environment, and the ability to run tests within your private network for security and privacy reasons.

This guide will help you get setup with k6 browser testing using the official grafana/k6:latest-with-browser image. We first explain how to make a simple setup for browser test, and then introduce requirements and how to integrate it with k6 Operator.

Before you begin

This list may expand in the future, as we learn about new use cases of browser testing. Pay attention to the following:

If you use securityContext or OpenShift SCCs/PSPs, verify the policy allows Chromium to start. Capture the exact error string in Troubleshooting so it is searchable.
Chromium is sensitive to restrictive security policies. In particular, avoid overly aggressive capability drops without testing browser startup.

Create and run a browser test

Start with the simplest Pod flow to verify that Chromium can launch in your cluster.

Create a browser test and name it script.js.
Create a ConfigMap with your script:

kubectl create configmap script --from-file script.js

Create a Pod with kubectl apply -f pod.yaml, where pod.yaml looks like

apiVersion: v1
kind: Pod
metadata:
  name: k6-browser-test
spec:
  containers:
    - name: k6
      image: grafana/k6:latest-with-browser
      command:
        - k6
      args:
        - run
        - /script/script.js
      resources:
        requests:
          cpu: "4"
          memory: "8G"
        limits:
          cpu: "4"
          memory: "8G"
      volumeMounts:
        - name: script
          mountPath: /script/script.js
          subPath: script.js
  volumes:
    - name: script
      configMap:
        name: script

Now wait and view the logs to see if it ran successfuly or not. We have some troubleshooting steps below that might help.

Architecture and performance considerations

Browser runner model

grafana/k6:latest-with-browser bundles the k6 binary and Chromium in the same pod. Each k6 runner starts its own browser process, which is simple but CPU and memory-intensive.

There is an open proposal to split browser and k6 runners, enabling an M:N model (M k6 runners to N browser instances) and potentially improving resource efficiency. This is relevant for capacity planning and for teams running larger browser workloads.

CPU rendering

grafana/k6:latest-with-browser includes both the k6 binary and a Chromium build that uses SwiftShader (CPU rendering). This keeps setup simple but can be heavy on CPU and may not work well for apps that require GPU-backed rendering. You can find more details on this GitHub issue.

Performance and sizing recommendations

Browser tests are CPU and memory-heavy. Start with higher limits to confirm stability, then scale down.

Set CPU and memory to match, or exceed, a modern desktop machine for initial runs.
Try to keep CPU/memory utilization under ~80% during steady-state.
Refer to Running large tests for general guidance on running larger tests.

Troubleshooting

If Chromium crashes immediately:
- It’s often due to security policies preventing Chromium from starting.
- In rare cases, we have seen it occur due to trying to run the incorrect arch image on an incompatible arch, for example, running an image built for AMD64 on an ARM-based machine.
Headless: true is not supported in this environment. A common error looks like: Missing X server or $DISPLAY\n[13:13:1211/091921.199737:ERROR:ui/aura/env.cc:257] The platform failed to initialize. Exiting.
capabilities.drop: all is generally a good security posture, but can break Chromium. It requires more capabilities than most CLI workloads.
Either add larger instances or reduce the CPU allocation if you see something like: 0/1 nodes are available: 1 Insufficient cpu. no new claims to deallocate, preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod.. Keep in mind that reducing CPU might worsen the browser test result.
error building browser on IterStart: making browser data directory "/tmp/k6browser-data-...": read-only file system
Fix: mount a writable emptyDir and set TMPDIR to that path (or mount emptyDir at /tmp). Example:
YAML
```
securityContext:
  readOnlyRootFilesystem: true
env:
  - name: TMPDIR
    value: /var/tmp
volumeMounts:
  - name: tmp
    mountPath: /var/tmp
volumes:
  - name: tmp
    emptyDir: {}
```
Error from server (BadRequest): error when creating "plz.yaml": PrivateLoadZone in version "v1alpha1" cannot be handled as a PrivateLoadZone: strict decoding error: unknown field "spec.*.securityContext" Fix: This is a known issue with the PLZ CRD. Refer to this GitHub issue for more details.