diff --git a/docusaurus/docs/e2e-test-a-plugin/get-started.md b/docusaurus/docs/e2e-test-a-plugin/get-started.md
index c512b91b9..4f8a0c274 100644
--- a/docusaurus/docs/e2e-test-a-plugin/get-started.md
+++ b/docusaurus/docs/e2e-test-a-plugin/get-started.md
@@ -13,6 +13,9 @@ keywords:
sidebar_position: 2
---
+import ScaffoldPluginE2ECreateDSPluginNPM from '@snippets/plugin-e2e-create-ds-plugin.npm.md';
+import ScaffoldPluginE2ECreateDSPluginYarn from '@snippets/plugin-e2e-create-ds-plugin.yarn.md';
+import ScaffoldPluginE2ECreateDSPluginPNPM from '@snippets/plugin-e2e-create-ds-plugin.pnpm.md';
import ScaffoldPluginE2InstallNPM from '@snippets/plugin-e2e-install.npm.md';
import ScaffoldPluginE2EInstallPNPM from '@snippets/plugin-e2e-install.pnpm.md';
import ScaffoldPluginE2EInstallYarn from '@snippets/plugin-e2e-install.yarn.md';
@@ -54,11 +57,17 @@ You can remove any test files (`[filename].spec.js|ts`) that was generated when
Optional: If you would like to follow along with our example tests, use the [create-plugin](../get-started/get-started.mdx) tool to generate a backend data source plugin.
-```shell
-npx @grafana/create-plugin@latest --pluginName='Sample datasource' --orgName='sample-org' --pluginDescription='This is a sample datasource.' --pluginType='datasource' --hasBackend
-```
+
-### Step 1: Installing @grafana/plugin-e2e
+### Step 1: Installing `@grafana/plugin-e2e`
Now open the terminal and run the following command in your plugin's project directory:
@@ -167,7 +176,11 @@ queryString="current-package-manager"
### Step 6: Run tests in CI
-We recommend updating your CI workflow to include the running of end-to-end tests to continuously check for breakages. The following workflow can be used to run end-to-end tests against a range of Grafana versions for every PR in your Github repository. Note that this is a generic example based on a backend plugin. You may want to alter or remove a few of the steps in the `playwright-tests` job before using it in your plugin.
+We recommend using a CI workflow to run end-to-end tests to continuously check for breakages. The following Github workflow will run end-to-end tests against a range of Grafana versions for every PR in your Github repository.
+
+:::note
+This is a generic example based on a backend plugin. You may need to alter or remove some of the steps in the `playwright-tests` job before using it in your plugin.
+:::
{
+test('annotation query should be OK when query is valid', async ({ annotationEditPage, page, selectors }) => {
await annotationEditPage.datasource.set('E2E Test Data Source');
await annotationEditPage
.getByTestIdOrAriaLabel(selectors.components.CodeEditor.container)
diff --git a/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.npm.md b/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.npm.md
new file mode 100644
index 000000000..b550de9d0
--- /dev/null
+++ b/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.npm.md
@@ -0,0 +1,3 @@
+```shell
+npx @grafana/create-plugin@latest --pluginName='E2E Test datasource' --orgName='sample-org' --pluginDescription='This is a sample datasource.' --pluginType='datasource' --hasBackend --no-hasGithubWorkflows --no-hasGithubLevitateWorkflow
+```
diff --git a/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.pnpm.md b/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.pnpm.md
new file mode 100644
index 000000000..f3c6b2e55
--- /dev/null
+++ b/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.pnpm.md
@@ -0,0 +1,3 @@
+```shell
+pnpm dlx @grafana/create-plugin@latest --pluginName='E2E Test datasource' --orgName='sample-org' --pluginDescription='This is a sample datasource.' --pluginType='datasource' --hasBackend --no-hasGithubWorkflows --no-hasGithubLevitateWorkflow
+```
diff --git a/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.yarn.md b/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.yarn.md
new file mode 100644
index 000000000..667f1270e
--- /dev/null
+++ b/docusaurus/docs/snippets/plugin-e2e-create-ds-plugin.yarn.md
@@ -0,0 +1,3 @@
+```shell
+yarn create @grafana/plugin --pluginName='E2E Test datasource' --orgName='sample-org' --pluginDescription='This is a sample datasource.' --pluginType='datasource' --hasBackend --no-hasGithubWorkflows --no-hasGithubLevitateWorkflow
+```
diff --git a/packages/plugin-e2e/README.md b/packages/plugin-e2e/README.md
index cdc3d0f2c..2614ebc2b 100644
--- a/packages/plugin-e2e/README.md
+++ b/packages/plugin-e2e/README.md
@@ -2,6 +2,10 @@
E2E test Grafana plugins with ease.
+**Links**
+
+- [`@grafana/plugin-e2e` docs](https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/introduction)
+
## Overview
`@grafana/plugin-e2e` is designed specifically for Grafana plugin developers. It extends [Playwright test](https://github.com/microsoft/playwright/) capabilities with fixtures, models, and expect matchers, enabling comprehensive end-to-end testing of Grafana plugins across multiple versions of Grafana. This package simplifies the testing process, ensuring your plugin is robust and compatible with various Grafana environments.
@@ -14,44 +18,66 @@ E2E test Grafana plugins with ease.
- **Version Compatibility:** Ensures that your plugin is tested across multiple versions of Grafana, guaranteeing compatibility and stability.
- **Integration with Playwright:** Seamlessly integrates with the Playwright testing framework, leveraging its powerful browser automation capabilities.
-## Getting Started
+## Get started
+
+Checkout our [`Get started`](https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/get-started) guide for detailed instructions on how to install, configure, write tests and run your e2e tests in CI.
### Prerequisites
+- You need to have a Grafana plugin [development environment](https://grafana.com/developers/plugin-tools/get-started/set-up-development-environment)
- Node.js 18+
-- Basic knowledge of Playwright
-- Grafana plugin [development environment](https://grafana.com/developers/plugin-tools/get-started/set-up-development-environment)
-
-### Installation
-
-To install `@grafana/plugin-e2e`, run the following command in your project directory:
-
-```bash
-npm install @grafana/plugin-e2e@latest --save-dev
-```
-
-To install Playwright along with the default browsers:
-
-```bash
-npm init playwright@latest
+- Basic Knowledge of Playwright. If you have not worked with Playwright before, we recommend following the [Getting started](https://playwright.dev/docs/intro) section in their documentation
+
+#### Install Playwright
+
+Please refer to the [Playwright documentation](https://playwright.dev/docs/intro#installing-playwright) for instruction on how to install. `@grafana/plugin-e2e` extends Playwright APIs, so you need to have `Playwright/test` with a minimum version of 0.40.0 installed as a dev dependency in the package.json file of your plugin.
+
+#### Configure Playwright
+
+Open the Playwright config file that was generated when Playwright was installed and paste the following configuration.
+
+```ts
+import { dirname } from 'path';
+import { defineConfig, devices } from '@playwright/test';
+const pluginE2eAuth = `${dirname(require.resolve('@grafana/plugin-e2e'))}/auth`;
+
+export default defineConfig({
+ testDir: './tests', // change this to the directory that was chosen when installing Playwright
+ reporter: 'html',
+ use: {
+ baseURL: 'http://localhost:3000',
+ },
+ projects: [
+ {
+ name: 'auth',
+ testDir: pluginE2eAuth,
+ testMatch: [/.*\.js/],
+ },
+ {
+ name: 'run-tests',
+ use: {
+ ...devices['Desktop Chrome'],
+ storageState: 'playwright/.auth/admin.json',
+ },
+ dependencies: ['auth'],
+ },
+ ],
+});
```
-> Note: @grafana/plugin-e2e uses @playwright/test version 1.40.0 internally, so the version you install in the plugin needs to be the same or higher.
-
-## Usage
-
### Writing Tests
Here's a basic example of how to write an E2E test using `@grafana/plugin-e2e`:
-```typescript
-import { expect, test } from '@grafana/plugin-e2e';
+```ts
+import { test, expect } from '@grafana/plugin-e2e';
-test('query data request should return 200 when query is valid', async ({ panelEditPage }) => {
- await panelEditPage.datasource.set('gdev-testdata');
- const queryEditorRow = await panelEditPage.getQueryEditorRow('A');
- await queryEditorRow.getByLabel('Labels').fill('key=value1, key2=value3');
+test('data query should return values 1 and 3', async ({ panelEditPage, readProvisionedDataSource }) => {
+ const ds = await readProvisionedDataSource({ fileName: 'datasources.yml' });
+ await panelEditPage.datasource.set(ds.name);
+ await panelEditPage.setVisualization('Table');
await expect(panelEditPage.refreshPanel()).toBeOK();
+ await expect(panelEditPage.panel.data).toContainText(['1', '3']);
});
```
@@ -63,6 +89,6 @@ To run your tests, use the following command:
npx playwright test
```
-# Contributing
+## Contributing
We welcome contributions to @grafana/plugin-e2e. If you're interested in contributing, please read our [contributing guidelines](./CONTRIBUTING.md).