Plugin E2E: Remove custom selector engine

packages/plugin-e2e/README.md

@@ -20,7 +20,7 @@ end-to-end test Grafana plugins with ease.
 
 ## 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.
+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 end-to-end tests in CI.
 
 ### Prerequisites
 
@@ -67,7 +67,7 @@ export default defineConfig({
 
 ### Writing Tests
 
-Here's a basic example of how to write an E2E test using `@grafana/plugin-e2e`:
+Here's a basic example of how to write an end-to-end test using `@grafana/plugin-e2e`:
 
 ```ts
 import { test, expect } from '@grafana/plugin-e2e';

packages/plugin-e2e/src/index.ts

@@ -1,4 +1,4 @@
-import { test as base, expect as baseExpect, selectors } from '@playwright/test';
+import { test as base, expect as baseExpect } from '@playwright/test';
 
 import { AlertPageOptions, AlertVariant, ContainTextOptions, PluginFixture, PluginOptions } from './types';
 import { annotationEditPage } from './fixtures/annotationEditPage';
@@ -24,7 +24,6 @@ import { panelEditPage } from './fixtures/panelEditPage';
 import { selectors as e2eSelectors } from './fixtures/selectors';
 import { variableEditPage } from './fixtures/variableEditPage';
 import { options } from './options';
-import { grafanaE2ESelectorEngine } from './selectorEngine';
 import { toHaveAlert } from './matchers/toHaveAlert';
 import { toDisplayPreviews } from './matchers/toDisplayPreviews';
 import { toBeOK } from './matchers/toBeOK';
@@ -87,17 +86,6 @@ export const expect = baseExpect.extend({
   toBeOK,
 });
 
-/** Register a custom selector engine that resolves locators for Grafana E2E selectors
- *
- * The same functionality is available in the {@link GrafanaPage.getByGrafanaSelector} method. However,
- * by registering the selector engine, one can resolve locators by Grafana E2E selectors also within a locator.
- *
- * Example:
- * const queryEditorRow = await panelEditPage.getQueryEditorRow('A'); // returns a locator
- * queryEditorRow.locator(`selector=${selectors.components.TimePicker.openButton}`).click();
- * */
-selectors.register('selector', grafanaE2ESelectorEngine);
-
 export { selectors } from '@playwright/test';
 
 declare global {

packages/plugin-e2e/src/models/pages/PanelEditPage.ts

@@ -152,9 +152,9 @@ export class PanelEditPage extends GrafanaPage {
     );
 
     // in older versions of grafana, the refresh button is rendered twice. this is a workaround to click the correct one
-    const refreshPanelButton = this.getByGrafanaSelector(
-      this.ctx.selectors.components.PanelEditor.General.content
-    ).locator(`selector=${this.ctx.selectors.components.RefreshPicker.runButtonV2}`);
+    const refreshPanelButton = this.getByGrafanaSelector(this.ctx.selectors.components.RefreshPicker.runButtonV2, {
+      root: this.getByGrafanaSelector(this.ctx.selectors.components.PanelEditor.General.content),
+    });
 
     await refreshPanelButton.click();
 

packages/plugin-e2e/src/types.ts

@@ -35,7 +35,7 @@ export type PluginOptions = {
   /**
    * Optionally, you can add or override feature toggles.
    * The feature toggles you specify here will only work in the frontend. If you need a feature toggle to work across the entire stack, you
-   * need to need to enable the feature in the Grafana config. See https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#feature_toggles
+   * need to need to enable the feature in the Grafana config. Also see https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/feature-toggles
    *
    * To override feature toggles globally in the playwright.config.ts file: 
    * export default defineConfig({
@@ -47,7 +47,7 @@ export type PluginOptions = {
       },
     });
    * 
-   * To override feature toggles for tests on a certain file:
+   * To override feature toggles for tests in a certain file:
      test.use({
       featureToggles: {
         exploreMixedDatasource: true,
@@ -60,29 +60,31 @@ export type PluginOptions = {
    * The Grafana user to use for the tests. If no user is provided, the default admin/admin user will be used.
    *
    * You can use different users for different projects. See the fixture createUser for more information on how to create a user,
-   * and the fixture login for more information on how to authenticate.
+   * and the fixture login for more information on how to authenticate. Also see https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/use-authentication
    */
   user?: CreateUserArgs;
 };
 
 export type PluginFixture = {
   /**
-   * The current Grafana version.
+   * The Grafana version that was detected when the test runner was started.
    *
    * If a GRAFANA_VERSION environment variable is set, this will be used. Otherwise,
    * the version will be picked from window.grafanaBootData.settings.buildInfo.version.
    */
   grafanaVersion: string;
 
   /**
-   * The E2E selectors to use for the current version of Grafana
+   * The E2E selectors to use for the current version of Grafana.
+   * See https://grafana.com/developers/plugin-tools/e2e-test-a-plugin/selecting-elements#grafana-end-to-end-selectors for more information.
    */
   selectors: E2ESelectors;
 
   /**
    * Isolated {@link DashboardPage} instance for each test.
    *
-   * Navigates to a new to a new dashboard page.
+   * When using this fixture in a test, you will get a new, empty dashboard page.
+   * To load an existing dashboard, use the {@link gotoDashboardPage} fixture.
    */
   dashboardPage: DashboardPage;
 
@@ -91,39 +93,29 @@ export type PluginFixture = {
    *
    * Navigates to a new dashboard page and adds a new panel.
    *
-   * Use {@link PanelEditPage.setVisualization} to change the visualization
-   * Use {@link PanelEditPage.datasource.set} to change the datasource
-   * Use {@link ExplorePage.getQueryEditorEditorRow} to retrieve the query
-   * editor row locator for a given query refId
+   * When using this fixture in a test, you will get a new dashboard page with a new empty panel edit page
+   * To load an existing dashboard with an existing panel, use the {@link gotoPanelEditPage} fixture.
    */
   panelEditPage: PanelEditPage;
 
   /**
    * Isolated {@link VariableEditPage} instance for each test.
    *
-   * Navigates to a new dashboard page and adds a new variable.
-   *
-   * Use {@link VariableEditPage.setVariableType} to change the variable type
+   * When using this fixture in a test, you will get a new dashboard page with a new empty variable edit page
+   * To load an existing dashboard with an existing variable, use the {@link gotoVariableEditPage} fixture.
    */
   variableEditPage: VariableEditPage;
 
   /**
    * Isolated {@link AnnotationEditPage} instance for each test.
    *
-   * Navigates to a new dashboard page and adds a new annotation.
-   *
-   * Use {@link AnnotationEditPage.datasource.set} to change the datasource
+   * When using this fixture in a test, you will get a new dashboard page with a new empty annotation edit page
+   * To load an existing dashboard with an existing annotation, use the {@link gotoAnnotationEditPage} fixture.
    */
   annotationEditPage: AnnotationEditPage;
 
   /**
    * Isolated {@link ExplorePage} instance for each test.
-   *
-   * Navigates to a the explore page.
-   *
-   * Use {@link ExplorePage.datasource.set} to change the datasource
-   * Use {@link ExplorePage.getQueryEditorEditorRow} to retrieve the query editor
-   * row locator for a given query refId
    */
   explorePage: ExplorePage;