Migrate from @grafana/e2e
When Grafana 11.0.0 is released the @grafana/e2e
will be deprecated and support will be dropped. We recommend all plugin authors to migrate their end-to-end tests to use Playwright and @grafana/plugin-e2e
instead of Cypress and @grafana/e2e
.
In this guide you'll learn:
- how to manually setup
@grafana/plugin-e2e
in your plugin - how to migrate tests
- how to run Playwright tests in CI
- how to uninstall Cypress and
@grafana/e2e
Manually installing @grafana/plugin-e2e​
Plugins scaffolded with create-plugin v4.6.0 and greater automatically include configuration for @grafana/plugin-e2e
and @playwright/test
. To add this configuration manually, follow these steps:
Step 1: Installing Playwright​
The @grafana/plugin-e2e
tool extends Playwright APIs, so you need to have @playwright/test
with a minimum version of 1.41.2 installed as a dev dependency in the package.json
file of your plugin. Refer to the Playwright documentation for instruction on how to install. Make sure you can run the example tests that were generated during the installation. If the example tests ran successfully, you may go ahead and delete them as they won't be needed anymore.
Step 2: Installing @grafana/plugin-e2e
​
Open the terminal and run the following command in your plugin's project directory:
- npm
- yarn
- pnpm
npm install @grafana/plugin-e2e@latest --save-dev
yarn add @grafana/plugin-e2e@latest --dev
pnpm add @grafana/plugin-e2e@latest -D
Step 3: Configure Playwright​
Open the Playwright config file that was generated when Playwright was installed.
- Uncomment
baseUrl
and change it to'http://localhost:3000'
.
baseURL: 'http://localhost:3000',
-
Playwright uses projects to logically group tests that have the same configuration. We're going to add two projects:
auth
is a setup project that will log in to Grafana and store the authenticated state on disk.run-tests
runs all the tests in your browser of choice. By adding a dependency to theauth
project we ensure that login only happens once, and all tests in therun-tests
project will start as already authenticated.
Your Playwright config should have the following project configuration:
import { dirname } from 'path';
import { defineConfig, devices } from '@playwright/test';
import type { PluginOptions } from '@grafana/plugin-e2e';
const pluginE2eAuth = `${dirname(require.resolve('@grafana/plugin-e2e'))}/auth`;
export default defineConfig<PluginOptions>({
...
projects: [
{
name: 'auth',
testDir: pluginE2eAuth,
testMatch: [/.*\.js/],
},
{
name: 'run-tests',
use: {
...devices['Desktop Chrome'],
// @grafana/plugin-e2e writes the auth state to this file,
// the path should not be modified
storageState: 'playwright/.auth/admin.json',
},
dependencies: ['auth'],
}
],
});
The authenticated state is stored on disk with the following file name pattern: <plugin-root>/playwright/.auth/<username>.json
.
To prevent these files from being version controlled, you can add the following line to your .gitignore
file:
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
/playwright/.auth/
Migrating from @grafana/e2e
​
Once you have Playwright and @grafana/plugin-e2e
installed and configured, you can follow these steps to migrate from @grafana/e2e
.
Migrating tests​
There's no tooling in place for automatically migrating existing @grafana/e2e
based Cypress tests to @grafana/plugin-e2e
based Playwright tests. This means you would have to convert your tests one by one or replace them with a new set of tests based on Playwright. Refer to the following resources to get inspiration on how the playwright tests should be written:
- How to test data source plugins
- How to test panel plugins
- Best practices around test isolation
- How to select UI elements
- Plugin examples repository
Running tests in CI​
To run Playwright tests targeting multiple versions of Grafana in CI, use one of the example workflows in the CI guide.
Note that Grafana does not offer any supported way to run end-to-end tests targeting multiple versions of Grafana in other CI platforms such as Drone or CircleCI. But you can easily configure your CI to replicate what the referenced Github Action is doing as there is nothing specific that we do that can not be done in other CI systems.
Uninstalling Cypress and @grafana/e2e​
Although we recommend moving from @grafana/e2e
to @grafana/plugin-e2e
in a timely manner, there's nothing preventing you from having the two side by side during a transitional phase.
When all Cypress tests have been migrated, open the terminal and run the following scripts from within your local plugin development directory:
1. Remove Cypress tests and config file​
rm ./cypress.json
rm -rf ./cypress
2. Uninstall dependencies​
npm uninstall --save-dev @grafana/e2e @grafana/e2e-selectors
3. Update scripts​
In the package.json
file, remove the e2e:update
script entirely and change the e2e
script to the following:
"e2e": "playwright test",