End-to-End (E2E) Testing
Relevant source files
The following files were used as context for generating this wiki page:
End-to-End (E2E) testing at Grafana is designed to simulate real user interactions within the browser to ensure the entire system functions correctly from the user's perspective. The project utilizes a homegrown solution built on top of the Playwright framework, which replaces legacy testing methods to provide more robust, versioned, and maintainable tests for both core features and external plugins.
The E2E testing strategy focuses on high-level flows without the use of stubs or mocks, ensuring that the tests run against a real Grafana instance. This includes testing core components like the dashboard, data source editors, and alerting systems, as well as providing a specialized @grafana/plugin-e2e tool for plugin developers to maintain compatibility across different Grafana versions.
Sources: contribute/style-guides/e2e-playwright.md:3-9, contribute/developer-guide.md:204-206
Framework Architecture
The framework is inspired by Martin Fowler's Page Object model, separating the technical details of element selection from the logical flow of the tests. This abstraction ensures that UI changes only require updates in a single location rather than across multiple test files.
Core Components
The architecture consists of four primary abstractions:
| Component | Description |
|---|---|
| Selector | A unique identifier (typically data-testid) used to retrieve elements from the browser. |
| Page | An abstraction containing one or more selectors and a visit function to navigate to a specific URL. |
| Component | An abstraction containing selectors for reusable UI elements (e.g., NavToolbar) without a visit function. |
| Flow | A sequence of actions performed on one or more Page abstractions that can be reused across tests. |
Sources: contribute/style-guides/e2e-playwright.md:13-18
Selector Versioning Logic
Grafana employs "versioned selectors" to handle UI changes across different releases. Selectors are stored in packages/grafana-e2e-selectors and can be mapped to specific Grafana versions. This allows a single test suite to run against multiple versions of Grafana by resolving the correct selector for the target version.
The diagram shows how the framework resolves different string identifiers based on the Grafana version being tested.
Sources: contribute/style-guides/e2e-playwright.md:73-87, e2e-playwright/plugin-e2e/plugin-e2e-api-tests/AGENTS.md:28-39
Testing Core Plugins and Features
Core plugins, such as Prometheus or MySQL, have dedicated test suites located in e2e-playwright/plugin-e2e. These tests often serve as "forward-compatibility canaries" to ensure that changes in the Grafana UI do not break the APIs or interaction patterns expected by plugins.
Test Workflow for Prometheus Editor
Tests for the Prometheus query editor demonstrate complex interactions, such as toggling between "Builder" and "Code" modes, interacting with the Metrics Browser, and validating query hints.
This sequence illustrates the typical setup for testing a core data source plugin from configuration to utilization in Explore.
Sources: e2e-playwright/various-suite/prometheus-editor.spec.ts:31-72, e2e-playwright/plugin-e2e/plugin-e2e-api-tests/AGENTS.md:7-10
Execution and Configuration
Tests are executed primarily via yarn scripts defined in the root package.json. These scripts handle environment variables like GRAFANA_URL and manage the lifecycle of the development server.
Common Commands
| Command | Purpose |
|---|---|
yarn e2e:playwright | Runs all Playwright tests against a development server on port 3001. |
yarn e2e:playwright --ui | Opens the Playwright UI for interactive test debugging. |
yarn e2e:playwright --project <name> | Runs a specific project (e.g., mysql, dashboards). |
yarn e2e:acceptance | Runs acceptance tests to verify cloud/on-prem images. |
yarn playwright show-report | Opens the HTML report of the last test run. |
Sources: contribute/style-guides/e2e-playwright.md:27-58, package.json:28-36
Environment and Setup
Before running tests, developers must install the required browser binaries using yarn playwright install chromium. The tests can run against a local development server or an arbitrary instance by setting the GRAFANA_URL environment variable.
Sources: contribute/developer-guide.md:208-212, contribute/style-guides/e2e-playwright.md:37-41
Plugin E2E Testing Support
The @grafana/plugin-e2e package provides fixtures and models specifically for external plugin developers. It extends Playwright with:
- Fixtures: Pre-configured browser contexts and data source creators.
- Page Models: Standardized representations of Grafana pages (e.g.,
DataSourceConfigPage). - Expect Matchers: Custom assertions tailored for Grafana UI elements.
Maintenance of plugin-e2e Compatibility
When a Grafana UI change occurs, developers are instructed to follow a strict priority for fixing broken E2E tests:
- Reuse Selectors: Apply the existing
data-testidto the new UI element. - Version Selectors: Add a new versioned entry to the selector object if the value must change.
- Update plugin-e2e: Update the page model in the
grafana/plugin-toolsrepository (last resort).
Sources: e2e-playwright/plugin-e2e/plugin-e2e-api-tests/AGENTS.md:12-45, e2e-playwright/plugin-e2e/plugin-e2e-api-tests/README.md:3-5
Summary
End-to-end testing in Grafana is a multi-layered system that balances high-level user simulation with the need for long-term maintainability. By utilizing versioned selectors and the Page Object model, the project ensures that tests remain stable despite frequent UI iterations. The integration of specialized tools like @grafana/plugin-e2e further extends this stability to the broader ecosystem, ensuring a consistent experience for both core developers and plugin contributors.