Docs: Plugin E2E - Get started follow up (#753)

Co-authored-by: Jack Westbrook <[email protected]>

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
-```
+<CodeSnippets
+snippets={[
+{ component: ScaffoldPluginE2ECreateDSPluginNPM, label: 'npm' },
+{ component: ScaffoldPluginE2ECreateDSPluginYarn, label: 'yarn' },
+{ component: ScaffoldPluginE2ECreateDSPluginPNPM, label: 'pnpm' }
+]}
+groupId="package-manager"
+queryString="current-package-manager"
+/>
 
-### 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.
+:::
 
 <CodeSnippets
 snippets={[

docusaurus/docs/e2e-test-a-plugin/selecting-ui-elements.md

@@ -33,7 +33,7 @@ Selectors defined in the `@grafana/e2e-selectors` package are tied to a specific
 ```ts
 import { test, expect } from '@grafana/plugin-e2e';
 
-test('annotation query should be OK when query is valid', async ({ panelEditPage, page, selectors }) => {
+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)

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
+```

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
+```

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
+```

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).