Docs: Plugin-E2E: Docs improvements (#778)

Co-authored-by: Joseph Perez <[email protected]>

docusaurus/docs/e2e-test-a-plugin/_category_.json

@@ -5,9 +5,5 @@
     "description": "Test a Grafana plugin using the @grafana/plugin-e2e tool."
   },
   "collapsible": true,
-  "collapsed": true,
-  "link": {
-    "type": "doc",
-    "id": "e2e-test-a-plugin/introduction"
-  }
+  "collapsed": true
 }

docusaurus/docs/e2e-test-a-plugin/authentication.md

@@ -19,54 +19,52 @@ To be able to interact with the Grafana UI, you need to be logged in to Grafana.
 
 ### Plugins that don't use RBAC
 
-If your plugin doesn't use RBAC, you can use the default server administrator credentials to login. The following snippet is a [setup project](https://playwright.dev/docs/test-global-setup-teardown#setup-example) that invokes a function in the `@grafana/plugin-e2e` package that will login to Grafana using `admin:admin`. The authenticated state is stored on disk and the file name pattern is as follows: `<plugin-root>/playwright/.auth/<username>.json`.
+If your plugin doesn't use RBAC, you can use the default server administrator credentials to login. In the following example, there's a [setup project](https://playwright.dev/docs/test-global-setup-teardown#setup-example) called `auth`. This project invokes a function in the `@grafana/plugin-e2e` package that will login to Grafana using `admin:admin`. The authenticated state is stored on disk and the file name pattern is as follows: `<plugin-root>/playwright/.auth/<username>.json`.
 
-```ts
-// playwright.config.js|ts
-projects: [
-  {
-    name: 'auth',
-    testDir: 'node_modules/@grafana/plugin-e2e/dist/auth',
-    testMatch: [/.*\.js/],
-  },
-];
-```
+The second project, `run-tests`, runs all tests in the `./tests` directory. This project reuses the authentication state from the `auth` project. This means login only happens once, and all tests in the `run-tests` project will start already authenticated.
+
+```ts title="playwright.config.ts"
+import { dirname } from 'path';
+import { defineConfig, devices } from '@playwright/test';
 
-The next project we add will run all tests in the `./tests` directory. We're reusing the authentication state from the `auth` project that we just added. This means login will only happen once, and all tests in the `run-tests` project will start already authenticated.
+const pluginE2eAuth = `${dirname(require.resolve('@grafana/plugin-e2e'))}/auth`;
 
-```ts
-projects: [
-  {
-    name: 'auth',
-    testDir: 'node_modules/@grafana/plugin-e2e/dist/auth',
-    testMatch: [/.*\.js/],
-  },
-  {
-    name: 'run-tests',
-    testDir: './tests',
-    use: {
-      ...devices['Desktop Chrome'],
-      storageState: 'playwright/.auth/admin.json',
+export default defineConfig({
+    ...
+    projects: [
+    {
+      name: 'auth',
+      testDir: pluginE2eAuth,
+      testMatch: [/.*\.js/],
     },
-    dependencies: ['auth'],
-  },
-];
+    {
+      name: 'run-tests',
+      use: {
+        ...devices['Desktop Chrome'],
+        storageState: 'playwright/.auth/admin.json',
+      },
+      dependencies: ['auth'],
+    }
+  ],
+});
 ```
 
 ### Plugins that use RBAC
 
 If your plugin uses RBAC, you may want to write tests that verify that certain plugin features are role-based. `@grafana/plugin-e2e` lets you define users with roles in the playwright config file. In the following example, a new user with the role `Viewer` is created in the `createViewerUserAndAuthenticate` setup project. In the next project, authentication state for the user with the viewer role is reused when running the tests. Note that tests that are specific for the `Viewer` role have been added to a dedicated `testDir`.
 
 ```ts title="playwright.config.ts"
+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: 'createViewerUserAndAuthenticate',
-        testDir: 'node_modules/@grafana/plugin-e2e/dist/auth',
+        testDir: pluginE2eAuth,
         testMatch: [/.*auth\.setup\.ts/],
         use: {
           user: {

docusaurus/docs/e2e-test-a-plugin/get-started.md

@@ -29,9 +29,14 @@ import ScaffoldPluginE2EDSWorkflowNPM from '@snippets/plugin-e2e-ds-workflow.npm
 import ScaffoldPluginE2EDSWorkflowYarn from '@snippets/plugin-e2e-ds-workflow.yarn.md';
 import ScaffoldPluginE2EDSWorkflowPNPM from '@snippets/plugin-e2e-ds-workflow.pnpm.md';
 
-# Get started
+This guide walks you through how to get started with end-to-end testing in your plugin.
 
-This article will guide through how to install and configure `@grafana/plugin-e2e`, write tests and setup a basic Github workflow that can run your end-to-end tests targeting multiple versions of Grafana.
+**Topics include:**
+
+- how to install `@grafana/plugin-e2e`
+- how to configure authentication
+- how to write tests
+- how to setup a basic Github workflow that runs tests against multiple versions of Grafana
 
 :::warning
 `@grafana/plugin-e2e` is still in beta and subject to breaking changes.
@@ -45,15 +50,9 @@ This article will guide through how to install and configure `@grafana/plugin-e2
 
 ### Installing 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 1.41.2 installed as a dev dependency in the package.json file of your plugin.
+`@grafana/plugin-e2e` 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. Please refer to the [Playwright documentation](https://playwright.dev/docs/intro#installing-playwright) for instruction on how to install. Make sure you can run the example tests that were generated when you installed Playwright before you proceed to the next step in this guide.
 
-You can remove any test files (`[filename].spec.js|ts`) that was generated when you installed Playwright. Let's also add the following line to your `.gitignore` file.
-
-```shell title=".gitignore"
-/playwright/.auth/
-```
-
-## Set up `plugin-e2e`
+## Set up @grafana/plugin-e2e
 
 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.
 
@@ -124,6 +123,12 @@ export default defineConfig({
 });
 ```
 
+The authenticated state is stored on disk and the file name pattern is as follows: `<plugin-root>/playwright/.auth/<username>.json`. To prevent these files from being version controlled, you can add the following line to your `.gitignore` file:
+
+```shell title=".gitignore"
+/playwright/.auth/
+```
+
 ### Step 3: Start Grafana
 
 Next, start up the latest version of Grafana on your local machine.
@@ -146,6 +151,8 @@ GRAFANA_VERSION=10.1.6 npm run server
 
 ### Step 4: Write tests
 
+While installing Playwright in your project, a few example test files were generatated. We won't need those, so you can go ahead and delete these files.
+
 You are now ready to write your tests. In this example, we're using the panel edit page to test the query editor for a backend data source plugin. The plugin was scaffolded with the [create-plugin](../get-started/get-started.mdx) tool, and for this data source the query endpoint returns hard coded data points. This test asserts that the values `1` and `3` are being displayed in the `Table` panel.
 
 ```ts title="queryEditor.spec.ts"
@@ -176,10 +183,12 @@ queryString="current-package-manager"
 
 ### Step 6: Run tests in CI
 
-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. 
+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
 
-:::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

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

@@ -26,7 +26,7 @@ All [pages](https://github.com/grafana/plugin-tools/tree/main/packages/plugin-e2
 panelEditPage.getByTestIdOrAriaLabel(selectors.components.CodeEditor.container).click();
 ```
 
-## The `selectors` fixture
+## The selectors fixture
 
 Selectors defined in the `@grafana/e2e-selectors` package are tied to a specific Grafana version. This means that the selectors can change from one version to another. When a new end-to-end test session is started, `@grafana/plugin-e2e` checks what version of Grafana is under test and resolves selectors that are associated with the running version. The selectors are provided through the `selectors` fixture.
 

docusaurus/docs/e2e-test-a-plugin/setup-resources.md

@@ -65,7 +65,7 @@ If running end-to-end tests in CI requires provisioning, you may need to remove
 
 `@grafana/plugin-e2e` provides fixtures that enables you to read files that you have placed in the `provisioning` folder.
 
-#### `readProvisionedDataSource` fixture
+#### readProvisionedDataSource fixture
 
 The `readProvisionedDataSource` fixture allows you to read a file from your plugin's `provisioning/datasources` folder. This gives you typings and it also allows you to keep data source configuration in one place.
 
@@ -79,7 +79,7 @@ const datasource = readProvisionedDataSource({ fileName: 'datasources.yml' });
 await panelEditPage.datasource.set(datasource.name);
 ```
 
-#### `readProvisionedDashboard` fixture
+#### readProvisionedDashboard fixture
 
 The `readProvisionedDashboard` fixture allows you to read the content of a dashboard JSON file from your `provisioning/dashboards` folder. It can be useful when navigating to a provisioned dashboard and you don't want to hard code the dashboard UID.