Edit 3 e2e files (#807)

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

@@ -1,7 +1,7 @@
 ---
-id: authentication
-title: Authentication
-description: Authentication
+id: use-authentication
+title: Use authentication
+description: Add authentication to end-to-end tests using the plugin-e2e tool.
 keywords:
   - grafana
   - plugins
@@ -15,13 +15,15 @@ sidebar_position: 40
 
 ## Introduction
 
-To be able to interact with the Grafana UI, you need to be logged in to Grafana. `@grafana/plugin-e2e` provides a declarative way to handle authentication and creating users that can be used to test role-based access control (RBAC) in your plugin.
+To be able to interact with the Grafana UI, you need to be logged in to Grafana. `@grafana/plugin-e2e` provides a declarative way to handle authentication and create users. In this guide, you will see examples of how to do this with and without using role-based access control (RBAC) in your plugin.
 
-### Plugins that don't use RBAC
+## Plugins that don't use RBAC
 
-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`.
+If your plugin doesn't use RBAC, you can use the default server administrator credentials to login.
 
-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.
+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 logins to Grafana using `admin:admin`. The authenticated state is stored on disk with this file name pattern: `<plugin-root>/playwright/.auth/<username>.json`.
+
+The second project, `run-tests`, runs all tests in the `./tests` directory. This project reuses the authentication state from the `auth` project. As a consequence, login only happens once, and all tests in the `run-tests` project start already authenticated.
 
 ```ts title="playwright.config.ts"
 import { dirname } from 'path';
@@ -49,9 +51,11 @@ export default defineConfig({
 });
 ```
 
-### Plugins that use RBAC
+## Plugins that use RBAC
+
+If your plugin uses RBAC, you may want to write tests that verify that certain plugin features are role-based.
 
-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`.
+The `@grafana/plugin-e2e` tool 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';

docusaurus/docs/e2e-test-a-plugin/feature-toggles.md

@@ -1,7 +1,7 @@
 ---
 id: feature-toggles
 title: Use Grafana feature toggles
-description: How to use Grafana feature toggles in end-to-end tests
+description: How to use Grafana feature toggles in end-to-end tests.
 keywords:
   - grafana
   - plugins
@@ -15,15 +15,15 @@ sidebar_position: 50
 
 ## Introduction
 
-Grafana uses a mechanism known as [feature toggles](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/) to enable code to be turned "on" or "off" at runtime. Plugins can optionally react to the state of a feature toggle to change their behaviour as appropriate, if they do, it can be beneficial to cover this within your end-to-end tests. This guide describes the features of `@grafana/plugin-e2e` that make it easier to work with feature toggles.
+Grafana uses a mechanism known as [feature toggles](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/feature-toggles/) to enable code to be turned "on" or "off" at runtime. Plugins can optionally react to the state of a feature toggle to change their behavior as appropriate; if they do, you can cover this within your end-to-end tests. This guide describes the features of `@grafana/plugin-e2e` that make it easier to work with feature toggles.
 
-### Passing feature toggle configuration to Grafana
+## Passing feature toggle configuration to Grafana
 
-The easisest way to configure feature toggles that are available across the entire Grafana stack is to specify the [environment variables](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#override-configuration-with-environment-variables) operational when starting your Grafana instance.
+The easiest way to configure feature toggles that are available across the entire Grafana stack is to specify the environment variables operational when starting your Grafana instance. For instructions on how to do so, refer to [our documentation](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#override-configuration-with-environment-variables).
 
-### Override frontend feature toggles in end-to-end tests
+## Override frontend feature toggles in end-to-end tests
 
-`@grafana/plugin-e2e` allows you to override the frontend feature toggles that Grafana is configured to use. You can do that by specifying the custom option `featureToggles` in the Playwright config file.
+The `@grafana/plugin-e2e` tool allows you to override the frontend feature toggles that Grafana is configured to use. You can do that by specifying the custom option `featureToggles` in the Playwright config file.
 
 ```typescript
 // playwright.config.ts
@@ -50,9 +50,9 @@ Feature toggles that are defined this way are propagated to `window.grafanaBootD
 
 :::
 
-#### Override feature toggles in a specific test file
+## Override feature toggles in a specific test file
 
-You can override feature toggles for tests in a certain test file.
+To override feature toggles for tests in a specific test file, use code like this.
 
 ```typescript
 import { test, expect } from '@grafana/plugin-e2e';
@@ -64,7 +64,7 @@ test.use({
 });
 ```
 
-### Check whether a feature is enabled in your test
+## Check whether a feature is enabled in your test
 
 Use the `isFeatureToggleEnabled` fixture to determine whether a certain feature toggle is enabled. Under the hood, `isFeatureToggleEnabled` checks whether the given feature is defined and enabled in the `window.grafanaBootData.settings.featureToggles` object.
 

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

@@ -1,6 +1,6 @@
 ---
 id: setup-resources
-title: Configure the resources you need
+title: Configure necessary resources
 description: Configure any dashboards, data sources or other Grafana resources necessary for end-to-end testing your plugin, through provisioning.
 keywords:
   - grafana
@@ -17,15 +17,15 @@ sidebar_position: 60
 
 ## Introduction
 
-In many cases, you'll need certain resources to be configured in Grafana before you can run your end-to-end tests. For example, to test how a panel plugin displays data, you'll need a data source configured to query and return that data. This guide covers how to setup the resources that you need through [provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/).
+In many cases, you'll need certain resources to be configured in Grafana before you can run your end-to-end tests. For example, to test how a panel plugin displays data, you'll need a data source configured to query and return that data. This guide covers how to set up these resources through [provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/).
 
-### Test isolation
+## Test isolation
 
-[Test isolation](https://playwright.dev/docs/browser-contexts#what-is-test-isolation) is a central part of Playwright testing. On this subject, we recommend testing plugin features independently and not run through advanced flows where certain steps have dependencies to the previous steps.
+[Test isolation](https://playwright.dev/docs/browser-contexts#what-is-test-isolation) is a central part of Playwright testing. On this subject, we recommend testing plugin features independently as oppose to running them through advanced flows where certain steps have dependencies to the previous steps.
 
-#### A concrete example
+### A concrete example
 
-Let's say you want to test template variable interpolation in your data source plugin. For any interpolation to take place in the DataSource file, there needs to be a template variable defined. Since the goal is to test variable interpolation, we don't want to create the template variable within the test code. A better approach is to open a provisioned dashboard that has a template variable defined already and use that in our test.
+Let's say you want to test template variable interpolation in your data source plugin. For any interpolation to take place in the `DataSource` file, there needs to be a template variable defined. Since the goal is to test variable interpolation, we don't want to create the template variable within the test code. Instead, we will use a provisioned dashboard that has a template variable already defined in our test.
 
 In the following example, we navigate to a provisioned dashboard. The dashboard has a multi-valued template variable `env` with the values `test` and `prod`. We add a new panel and set a SQL query that refers to the `env` variable. We then spy on the query data request, asserting that it was called with the expanded values associated with the template variable.
 
@@ -50,22 +50,27 @@ test('should expand multi-valued variable before calling backend', async ({
 });
 ```
 
-### Provision any required resources
+## Provision necessary resources
 
 You can use [provisioning](https://grafana.com/docs/grafana/latest/administration/provisioning/) to configure resources such as dashboards and data sources.
 
 :::note
+
 If running end-to-end tests in CI requires provisioning, you may need to remove the `provisioning` folder from your plugin's `.gitignore` file.
+
 :::
 
-:::danger Be careful not to commit secrets to public repositories. Use [environment variable](https://grafana.com/docs/grafana/latest/administration/provisioning/#using-environment-variables) interpolation for sensitive data.
+:::danger
+
+Be careful not to commit secrets to public repositories. Use [environment variable interpolation](https://grafana.com/docs/grafana/latest/administration/provisioning/#using-environment-variables) for sensitive data.
+
 :::
 
-### Read provisioned files
+## Read provisioned files
 
-`@grafana/plugin-e2e` provides fixtures that enables you to read files that you have placed in the `provisioning` folder.
+The `@grafana/plugin-e2e` tool 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,9 +84,9 @@ 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.
+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 when you don't want to hard code the dashboard UID.
 
 ```ts title="variableEditPage.spec.ts"
 const dashboard = await readProvisionedDashboard({ fileName: 'dashboard.json' });