@grafana/plugin-e2e 0.1.0 → 0.2.0

package/dist/api.d.ts

@@ -6,17 +6,113 @@ export type PluginOptions = {
     selectorRegistration: void;
 };
 export type PluginFixture = {
+    /**
+     * The current Grafana version.
+     *
+     * 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
+     */
     selectors: E2ESelectors;
+    /**
+     * Isolated {@link DashboardPage} instance for each test.
+     *
+     * 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 PanelEditPage.getQueryEditorEditorRow} to retrieve the query
+     * editor row locator for a given query refId
+     */
     newDashboardPage: DashboardPage;
+    /**
+     * Isolated {@link PanelEditPage} instance for each test.
+     *
+     * 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
+     */
     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
+     */
     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
+     */
     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;
+    /**
+     * Fixture command that will create an isolated DataSourceConfigPage instance for a given data source type.
+     *
+     * The data source config page cannot be navigated to without a data source uid, so this fixture will create a new
+     * data source using the Grafana API, create a new DataSourceConfigPage instance and navigate to the page.
+     */
     createDataSourceConfigPage: (args: CreateDataSourcePageArgs) => Promise<DataSourceConfigPage>;
+    /**
+     * Fixture command that creates a data source via the Grafana API.
+     *
+     * If you have tests that depend on the the existance of a data source,
+     * you may use this command in a setup project. Read more about setup projects
+     * here: https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
+     */
     createDataSource: (args: CreateDataSourceArgs) => Promise<DataSource>;
+    /**
+     * Fixture command that login to Grafana using the Grafana API.
+     * If the same credentials should be used in every test,
+     * invoke this fixture in a setup project.
+     * See https://playwright.dev/docs/auth#basic-shared-account-in-all-tests
+     *
+     * If no credentials are provided, the default admin/admin credentials will be used.
+     *
+     * The default credentials can be overridden in the playwright.config.ts file:
+     * eg.
+     * export default defineConfig({
+        use: {
+          httpCredentials: {
+            username: 'user',
+            password: 'pass',
+          },
+        },
+      });
+     *
+     * To override credentials in a single test:
+     * test.use({ httpCredentials: { username: 'admin', password: 'admin' } });
+     * To avoid authentication in a single test:
+     * test.use({ storageState: { cookies: [], origins: [] } });
+     */
     login: () => Promise<void>;
+    /**
+     * Fixture command that reads a the yaml file for a provisioned dashboard
+     * or data source and returns it as json.
+     */
     readProvision<T = any>(args: ReadProvisionArgs): Promise<T>;
+    /**
+     * Function that checks if a feature toggle is enabled. Only works for frontend feature toggles.
+     */
     isFeatureToggleEnabled<T = object>(featureToggle: keyof T): Promise<boolean>;
 };
 export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & PluginFixture & PluginOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;

package/dist/api.js

@@ -8,8 +8,18 @@ const test_1 = require("@playwright/test");
 const fixtures_1 = __importDefault(require("./fixtures"));
 const matchers_1 = __importDefault(require("./matchers"));
 const selectorEngine_1 = require("./selectorEngine");
+// extend Playwright with Grafana plugin specific fixtures
 exports.test = test_1.test.extend(fixtures_1.default);
 exports.expect = test_1.expect.extend(matchers_1.default);
+/** Register a custom selector engine that resolves locators for Grafana E2E selectors
+ *
+ * The same functionality is available in the {@link GrafanaPage.getByTestIdOrAriaLabel} 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();
+ * */
 test_1.selectors.register('selector', selectorEngine_1.grafanaE2ESelectorEngine);
 var test_2 = require("@playwright/test");
 Object.defineProperty(exports, "selectors", { enumerable: true, get: function () { return test_2.selectors; } });

package/dist/e2e-selectors/resolver.d.ts

@@ -1,3 +1,10 @@
 import { E2ESelectors } from './types';
 import { VersionedSelectors } from './versioned/types';
+/**
+ * Resolves selectors based on the Grafana version
+ *
+ * If the selector has multiple versions, the last version that is less
+ * than or equal to the Grafana version will be returned.
+ * If the selector doesn't have a version, it will be returned as is.
+ */
 export declare const resolveSelectors: (versionedSelectors: VersionedSelectors, grafanaVersion: string) => E2ESelectors;

package/dist/e2e-selectors/resolver.js

@@ -6,12 +6,15 @@ const processSelectors = (selectors, versionedSelectors, grafanaVersion) => {
     const keys = Object.keys(versionedSelectors);
     for (let index = 0; index < keys.length; index++) {
         const key = keys[index];
+        // @ts-ignore
         const value = versionedSelectors[key];
         if (typeof value === 'object' && Object.keys(value).length > 0 && !semver.valid(Object.keys(value)[0])) {
+            // @ts-ignore
             selectors[key] = processSelectors({}, value, grafanaVersion);
         }
         else {
             if (typeof value === 'object' && Object.keys(value).length > 0 && semver.valid(Object.keys(value)[0])) {
+                // @ts-ignore
                 const sorted = Object.keys(value).sort(semver.rcompare);
                 let validVersion = sorted[0];
                 for (let index = 0; index < sorted.length; index++) {
@@ -21,9 +24,11 @@ const processSelectors = (selectors, versionedSelectors, grafanaVersion) => {
                         break;
                     }
                 }
+                // @ts-ignore
                 selectors[key] = value[validVersion];
             }
             else {
+                // @ts-ignore
                 selectors[key] = value;
             }
         }
@@ -31,6 +36,13 @@ const processSelectors = (selectors, versionedSelectors, grafanaVersion) => {
     }
     return selectors;
 };
+/**
+ * Resolves selectors based on the Grafana version
+ *
+ * If the selector has multiple versions, the last version that is less
+ * than or equal to the Grafana version will be returned.
+ * If the selector doesn't have a version, it will be returned as is.
+ */
 const resolveSelectors = (versionedSelectors, grafanaVersion) => {
     const selectors = {};
     return processSelectors(selectors, versionedSelectors, grafanaVersion.replace(/\-.*/, ''));

package/dist/e2e-selectors/resolver.test.js

@@ -25,10 +25,13 @@ describe('resolveSelectors', () => {
             '10.3.0': 'data-testid Code editor container',
             [constants_1.MIN_GRAFANA_VERSION]: 'Code editor container',
         };
+        // semver great than
         let selectors = (0, resolver_1.resolveSelectors)(versionedSelectors, '10.4.0');
         expect(selectors.components.CodeEditor.container).toBe('data-testid Code editor container');
+        // semver equals to
         selectors = (0, resolver_1.resolveSelectors)(versionedSelectors, '10.3.0');
         expect(selectors.components.CodeEditor.container).toBe('data-testid Code editor container');
+        // semver equals to when using pre-release
         selectors = (0, resolver_1.resolveSelectors)(versionedSelectors, '10.3.0-pre');
         expect(selectors.components.CodeEditor.container).toBe('data-testid Code editor container');
         selectors = (0, resolver_1.resolveSelectors)(versionedSelectors, '9.2.0');

package/dist/e2e-selectors/types.d.ts

@@ -191,6 +191,9 @@ export type Components = {
         content: string;
     };
     Alert: {
+        /**
+         * @deprecated use alertV2 from Grafana 8.3 instead
+         */
         alert: (severity: string) => string;
         alertV2: (severity: string) => string;
     };
@@ -402,6 +405,7 @@ export type Pages = {
     };
     AddDataSource: {
         url: string;
+        /** @deprecated Use dataSourcePluginsV2 */
         dataSourcePlugins: (pluginName: string) => string;
         dataSourcePluginsV2: (pluginName: string) => string;
     };
@@ -472,6 +476,9 @@ export type Pages = {
                 };
                 List: {
                     url: (uid: string) => string;
+                    /**
+                     * @deprecated use addAnnotationCTAV2 from Grafana 8.3 instead
+                     */
                     addAnnotationCTA: string;
                     addAnnotationCTAV2: string;
                 };

package/dist/e2e-selectors/versioned/components.d.ts

@@ -96,6 +96,9 @@ export declare const versionedComponents: {
                 };
             };
             BarGauge: {
+                /**
+                 * @deprecated use valueV2 from Grafana 8.3 instead
+                 */
                 value: string;
                 valueV2: string;
             };
@@ -173,7 +176,13 @@ export declare const versionedComponents: {
         active: () => string;
     };
     RefreshPicker: {
+        /**
+         * @deprecated use runButtonV2 from Grafana 8.3 instead
+         */
         runButton: string;
+        /**
+         * @deprecated use intervalButtonV2 from Grafana 8.3 instead
+         */
         intervalButton: string;
         runButtonV2: string;
         intervalButtonV2: string;
@@ -199,6 +208,9 @@ export declare const versionedComponents: {
         content: string;
     };
     Alert: {
+        /**
+         * @deprecated use alertV2 from Grafana 8.3 instead
+         */
         alert: (severity: string) => string;
         alertV2: (severity: string) => string;
     };
@@ -293,6 +305,9 @@ export declare const versionedComponents: {
         content: string;
     };
     FolderPicker: {
+        /**
+         * @deprecated use containerV2 from Grafana 8.3 instead
+         */
         container: string;
         containerV2: string;
         input: string;
@@ -305,14 +320,23 @@ export declare const versionedComponents: {
             '10.0.0': string;
             '8.3.0': string;
         };
+        /**
+         * @deprecated use inputV2 instead
+         */
         input: () => string;
         inputV2: string;
     };
     TimeZonePicker: {
+        /**
+         * @deprecated use TimeZonePicker.containerV2 from Grafana 8.3 instead
+         */
         container: string;
         containerV2: string;
     };
     WeekStartPicker: {
+        /**
+         * @deprecated use WeekStartPicker.containerV2 from Grafana 8.3 instead
+         */
         container: string;
         containerV2: string;
         placeholder: string;
@@ -334,8 +358,14 @@ export declare const versionedComponents: {
         select: (name: string) => string;
     };
     Search: {
+        /**
+         * @deprecated use sectionV2 from Grafana 8.3 instead
+         */
         section: string;
         sectionV2: string;
+        /**
+         * @deprecated use itemsV2 from Grafana 8.3 instead
+         */
         items: string;
         itemsV2: string;
         cards: string;
@@ -355,6 +385,9 @@ export declare const versionedComponents: {
         icon: string;
     };
     CallToActionCard: {
+        /**
+         * @deprecated use buttonV2 from Grafana 8.3 instead
+         */
         button: (name: string) => string;
         buttonV2: (name: string) => string;
     };

package/dist/e2e-selectors/versioned/components.js

@@ -5,6 +5,7 @@ const constants_1 = require("./constants");
 exports.versionedComponents = {
     Breadcrumbs: {
         breadcrumb: {
+            // did not exist prior to 9.4.0
             '9.4.0': (title) => `data-testid ${title} breadcrumb`,
         },
     },
@@ -100,6 +101,9 @@ exports.versionedComponents = {
                 },
             },
             BarGauge: {
+                /**
+                 * @deprecated use valueV2 from Grafana 8.3 instead
+                 */
                 value: 'Bar gauge value',
                 valueV2: 'data-testid Bar gauge value',
             },
@@ -113,6 +117,7 @@ exports.versionedComponents = {
                 header: 'table header',
                 footer: 'table-footer',
                 body: {
+                    // did not exist prior to 10.2.0
                     '10.2.0': 'data-testid table body',
                 },
             },
@@ -139,6 +144,7 @@ exports.versionedComponents = {
             select: 'Panel editor option pane select',
             fieldLabel: (type) => `${type} field property editor`,
         },
+        // not sure about the naming *DataPane*
         DataPane: {
             content: 'Panel editor data pane content',
         },
@@ -149,6 +155,7 @@ exports.versionedComponents = {
         },
         toggleVizOptions: 'data-testid toggle-viz-options',
         toggleTableView: 'toggle-table-view',
+        // [Geomap] Map controls
         showZoomField: 'Map controls Show zoom control field property editor',
         showAttributionField: 'Map controls Show attribution field property editor',
         showScaleField: 'Map controls Show scale field property editor',
@@ -177,7 +184,13 @@ exports.versionedComponents = {
         active: () => '[class*="-activeTabStyle"]',
     },
     RefreshPicker: {
+        /**
+         * @deprecated use runButtonV2 from Grafana 8.3 instead
+         */
         runButton: 'RefreshPicker run button',
+        /**
+         * @deprecated use intervalButtonV2 from Grafana 8.3 instead
+         */
         intervalButton: 'RefreshPicker interval button',
         runButtonV2: 'data-testid RefreshPicker run button',
         intervalButtonV2: 'data-testid RefreshPicker interval button',
@@ -203,6 +216,9 @@ exports.versionedComponents = {
         content: 'Alert editor tab content',
     },
     Alert: {
+        /**
+         * @deprecated use alertV2 from Grafana 8.3 instead
+         */
         alert: (severity) => `Alert ${severity}`,
         alertV2: (severity) => `data-testid Alert ${severity}`,
     },
@@ -297,6 +313,9 @@ exports.versionedComponents = {
         content: 'Field overrides editor content',
     },
     FolderPicker: {
+        /**
+         * @deprecated use containerV2 from Grafana 8.3 instead
+         */
         container: 'Folder picker select container',
         containerV2: 'data-testid Folder picker select container',
         input: 'Select a folder',
@@ -307,16 +326,26 @@ exports.versionedComponents = {
     DataSourcePicker: {
         container: {
             '10.0.0': 'data-testid Data source picker select container',
+            // did not exist prior to 8.3.0
             '8.3.0': 'Data source picker select container',
         },
+        /**
+         * @deprecated use inputV2 instead
+         */
         input: () => 'input[id="data-source-picker"]',
         inputV2: 'data-testid Select a data source',
     },
     TimeZonePicker: {
+        /**
+         * @deprecated use TimeZonePicker.containerV2 from Grafana 8.3 instead
+         */
         container: 'Time zone picker select container',
         containerV2: 'data-testid Time zone picker select container',
     },
     WeekStartPicker: {
+        /**
+         * @deprecated use WeekStartPicker.containerV2 from Grafana 8.3 instead
+         */
         container: 'Choose starting day of the week',
         containerV2: 'data-testid Choose starting day of the week',
         placeholder: 'Choose starting day of the week',
@@ -336,8 +365,14 @@ exports.versionedComponents = {
         select: (name) => `Value picker select ${name}`,
     },
     Search: {
+        /**
+         * @deprecated use sectionV2 from Grafana 8.3 instead
+         */
         section: 'Search section',
         sectionV2: 'data-testid Search section',
+        /**
+         * @deprecated use itemsV2 from Grafana 8.3 instead
+         */
         items: 'Search items',
         itemsV2: 'data-testid Search items',
         cards: 'data-testid Search cards',
@@ -357,6 +392,9 @@ exports.versionedComponents = {
         icon: 'Loading indicator',
     },
     CallToActionCard: {
+        /**
+         * @deprecated use buttonV2 from Grafana 8.3 instead
+         */
         button: (name) => `Call to action button ${name}`,
         buttonV2: (name) => `data-testid Call to action button ${name}`,
     },

package/dist/e2e-selectors/versioned/pages.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Selectors grouped/defined in Pages
+ *
+ * @alpha
+ */
 export declare const versionedPages: {
     Login: {
         url: string;
@@ -35,6 +40,7 @@ export declare const versionedPages: {
             '8.5.0': string;
             '10.1.0': string;
         };
+        /** @deprecated Use dataSourcePluginsV2 */
         dataSourcePlugins: {
             '8.5.0': (pluginName: string) => string;
             '9.5.0': (pluginName: string) => string;
@@ -75,6 +81,9 @@ export declare const versionedPages: {
     Dashboard: {
         url: (uid: string) => string;
         DashNav: {
+            /**
+             * @deprecated use navV2 from Grafana 8.3 instead
+             */
             nav: string;
             navV2: string;
             publicDashboardTag: string;
@@ -101,6 +110,9 @@ export declare const versionedPages: {
                 sectionItems: (item: string) => string;
                 saveDashBoard: string;
                 saveAsDashBoard: string;
+                /**
+                 * @deprecated use components.TimeZonePicker.containerV2 from Grafana 8.3 instead
+                 */
                 timezone: string;
                 title: string;
             };
@@ -145,6 +157,9 @@ export declare const versionedPages: {
                     General: {
                         headerLink: string;
                         modeLabelNew: string;
+                        /**
+                         * @deprecated
+                         */
                         modeLabelEdit: string;
                         generalNameInput: string;
                         generalNameInputV2: string;
@@ -207,6 +222,9 @@ export declare const versionedPages: {
     };
     Dashboards: {
         url: string;
+        /**
+         * @deprecated use components.Search.dashboardItem from Grafana 8.3 instead
+         */
         dashboards: (title: string) => string;
     };
     SaveDashboardAsModal: {

package/dist/e2e-selectors/versioned/pages.js

@@ -2,6 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.versionedPages = void 0;
 const constants_1 = require("./constants");
+/**
+ * Selectors grouped/defined in Pages
+ *
+ * @alpha
+ */
 exports.versionedPages = {
     Login: {
         url: '/login',
@@ -39,6 +44,7 @@ exports.versionedPages = {
             '8.5.0': '/datasources/new',
             '10.1.0': '/connections/datasources/new',
         },
+        /** @deprecated Use dataSourcePluginsV2 */
         dataSourcePlugins: {
             '8.5.0': (pluginName) => `Data source plugin item ${pluginName}`,
             '9.5.0': (pluginName) => `Add new data source ${pluginName}`,
@@ -79,6 +85,9 @@ exports.versionedPages = {
     Dashboard: {
         url: (uid) => `/d/${uid}`,
         DashNav: {
+            /**
+             * @deprecated use navV2 from Grafana 8.3 instead
+             */
             nav: 'Dashboard navigation',
             navV2: 'data-testid Dashboard navigation',
             publicDashboardTag: 'data-testid public dashboard tag',
@@ -105,6 +114,9 @@ exports.versionedPages = {
                 sectionItems: (item) => `Dashboard settings section item ${item}`,
                 saveDashBoard: 'Dashboard settings aside actions Save button',
                 saveAsDashBoard: 'Dashboard settings aside actions Save As button',
+                /**
+                 * @deprecated use components.TimeZonePicker.containerV2 from Grafana 8.3 instead
+                 */
                 timezone: 'Time zone picker select container',
                 title: 'Tab General',
             },
@@ -149,6 +161,9 @@ exports.versionedPages = {
                     General: {
                         headerLink: 'Variable editor Header link',
                         modeLabelNew: 'Variable editor Header mode New',
+                        /**
+                         * @deprecated
+                         */
                         modeLabelEdit: 'Variable editor Header mode Edit',
                         generalNameInput: 'Variable editor Form Name field',
                         generalNameInputV2: 'data-testid Variable editor Form Name field',
@@ -211,6 +226,9 @@ exports.versionedPages = {
     },
     Dashboards: {
         url: '/dashboards',
+        /**
+         * @deprecated use components.Search.dashboardItem from Grafana 8.3 instead
+         */
         dashboards: (title) => `Dashboard search item ${title}`,
     },
     SaveDashboardAsModal: {

package/dist/models/AnnotationEditPage.d.ts

@@ -7,5 +7,9 @@ export declare class AnnotationEditPage extends GrafanaPage {
     datasource: DataSourcePicker;
     constructor(ctx: PluginTestCtx, args: DashboardEditViewArgs<string>);
     goto(options?: NavigateOptions): Promise<void>;
+    /**
+     * Executes the annotation query defined in the annotation page and returns the response promise
+     * @param options - Optional. RequestOptions to pass to waitForResponse
+     */
     runQuery(options?: RequestOptions): Promise<import("playwright-core").Response>;
 }

package/dist/models/AnnotationEditPage.js

@@ -20,8 +20,13 @@ class AnnotationEditPage extends GrafanaPage_1.GrafanaPage {
             : AddDashboard.Settings.Annotations.Edit.url(this.args.id);
         return super.navigate(url, options);
     }
+    /**
+     * Executes the annotation query defined in the annotation page and returns the response promise
+     * @param options - Optional. RequestOptions to pass to waitForResponse
+     */
     async runQuery(options) {
         const responsePromise = this.ctx.page.waitForResponse((resp) => resp.url().includes(this.ctx.selectors.apis.DataSource.query), options);
+        //TODO: add new selector and use it in grafana/ui
         await this.ctx.page.getByRole('button', { name: 'TEST' }).click();
         return responsePromise;
     }

package/dist/models/AnnotationPage.js

@@ -45,6 +45,7 @@ class AnnotationPage extends GrafanaPage_1.GrafanaPage {
     async clickAddNew() {
         const { Dashboard } = this.ctx.selectors.pages;
         if (!this.dashboard?.uid) {
+            //the dashboard doesn't have any annotations yet (except for the built-in one)
             if (semver.gte(this.ctx.grafanaVersion, '8.3.0')) {
                 await this.getByTestIdOrAriaLabel(Dashboard.Settings.Annotations.List.addAnnotationCTAV2).click();
             }
@@ -53,6 +54,8 @@ class AnnotationPage extends GrafanaPage_1.GrafanaPage {
             }
         }
         else {
+            //the dashboard already has annotations
+            //TODO: add new selector and use it in grafana/ui
             await this.ctx.page.getByRole('button', { name: 'New query' }).click();
         }
         const editIndex = await this.ctx.page.evaluate(() => {

package/dist/models/DataSourceConfigPage.d.ts

@@ -5,6 +5,16 @@ export declare class DataSourceConfigPage extends GrafanaPage {
     constructor(ctx: PluginTestCtx, datasource: DataSource);
     deleteDataSource(): Promise<void>;
     goto(options?: NavigateOptions): Promise<void>;
+    /**
+     * Mocks the response of the datasource health check call
+     * @param json the json response to return
+     * @param status the HTTP status code to return. Defaults to 200
+     */
     mockHealthCheckResponse<T = any>(json: T, status?: number): Promise<void>;
+    /**
+     * Clicks the save and test button and waits for the response
+     *
+     * Optionally, you can skip waiting for the response by passing in { skipWaitForResponse: true } as the options parameter
+     */
     saveAndTest(options?: TriggerQueryOptions): Promise<void | import("playwright-core").Response>;
 }

package/dist/models/DataSourceConfigPage.js

@@ -14,11 +14,21 @@ class DataSourceConfigPage extends GrafanaPage_1.GrafanaPage {
     async goto(options) {
         return super.navigate(this.ctx.selectors.pages.EditDataSource.url(this.datasource.uid), options);
     }
+    /**
+     * Mocks the response of the datasource health check call
+     * @param json the json response to return
+     * @param status the HTTP status code to return. Defaults to 200
+     */
     async mockHealthCheckResponse(json, status = 200) {
         await this.ctx.page.route(`${this.ctx.selectors.apis.DataSource.health(this.datasource.uid ?? '', this.datasource.id.toString() ?? '')}`, async (route) => {
             await route.fulfill({ json, status });
         });
     }
+    /**
+     * Clicks the save and test button and waits for the response
+     *
+     * Optionally, you can skip waiting for the response by passing in { skipWaitForResponse: true } as the options parameter
+     */
     async saveAndTest(options) {
         if (options?.skipWaitForResponse) {
             return this.getByTestIdOrAriaLabel(this.ctx.selectors.pages.DataSource.saveAndTest).click();

package/dist/models/DataSourcePicker.js

@@ -10,6 +10,8 @@ class DataSourcePicker extends GrafanaPage_1.GrafanaPage {
         await this.getByTestIdOrAriaLabel(this.ctx.selectors.components.DataSourcePicker.container)
             .locator('input')
             .fill(name);
+        // this is a hack to get the selection to work in 10.ish versions of Grafana.
+        // TODO: investigate if the select component can somehow be refactored so that its easier to test with playwright
         await this.ctx.page.keyboard.press('ArrowDown');
         await this.ctx.page.keyboard.press('ArrowUp');
         await this.ctx.page.keyboard.press('Enter');

package/dist/models/ExplorePage.js

@@ -32,6 +32,7 @@ class ExplorePage extends GrafanaPage_1.GrafanaPage {
             });
         }
         catch (_) {
+            // handle the case when the run button is hidden behind the "Show more items" button
             await this.getByTestIdOrAriaLabel(components.PageToolbar.item(components.PageToolbar.shotMoreItems)).click();
             await this.getByTestIdOrAriaLabel(components.RefreshPicker.runButtonV2).last().click();
         }

package/dist/models/GrafanaPage.d.ts

@@ -1,12 +1,43 @@
 import { Locator, Request, Response } from '@playwright/test';
 import { NavigateOptions, PluginTestCtx } from '../types';
+/**
+ * Base class for all Grafana pages.
+ *
+ * Exposes methods for locating Grafana specific elements on the page
+ */
 export declare abstract class GrafanaPage {
     readonly ctx: PluginTestCtx;
     constructor(ctx: PluginTestCtx);
     protected navigate(url: string, options?: NavigateOptions): Promise<void>;
+    /**
+     * Get a locator for a Grafana element by data-testid or aria-label
+     * @param selector the data-testid or aria-label of the element
+     * @param root optional root locator to search within. If no locator is provided, the page will be used
+     */
     getByTestIdOrAriaLabel(selector: string, root?: Locator): Locator;
+    /**
+     * Mocks the response of the datasource query call
+     * @param json the json response to return
+     * @param status the HTTP status code to return. Defaults to 200
+     */
     mockQueryDataResponse<T = any>(json: T, status?: number): Promise<void>;
+    /**
+     * Mocks the response of the datasource resource request
+     * @param path the path of the resource to mock
+     * @param json the json response to return
+     * @param status the HTTP status code to return. Defaults to 200
+     */
     mockResourceResponse<T = any>(path: string, json: T, status?: number): Promise<void>;
+    /**
+     * Waits for a data source query data request to be made.
+     *
+     * @param cb optional callback to filter the request. Use this to filter by request body or other request properties
+     */
     waitForQueryDataRequest(cb?: (request: Request) => boolean | Promise<boolean>): Promise<Request>;
+    /**
+     * Waits for a data source query data response
+     *
+     * @param cb optional callback to filter the response. Use this to filter by response body or other response properties
+     */
     waitForQueryDataResponse(cb?: (request: Response) => boolean | Promise<boolean>): Promise<Response>;
 }

package/dist/models/GrafanaPage.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GrafanaPage = void 0;
+/**
+ * Base class for all Grafana pages.
+ *
+ * Exposes methods for locating Grafana specific elements on the page
+ */
 class GrafanaPage {
     ctx;
     constructor(ctx) {
@@ -15,25 +20,47 @@ class GrafanaPage {
             ...options,
         });
     }
+    /**
+     * Get a locator for a Grafana element by data-testid or aria-label
+     * @param selector the data-testid or aria-label of the element
+     * @param root optional root locator to search within. If no locator is provided, the page will be used
+     */
     getByTestIdOrAriaLabel(selector, root) {
         if (selector.startsWith('data-testid')) {
             return (root || this.ctx.page).getByTestId(selector);
         }
         return (root || this.ctx.page).locator(`[aria-label="${selector}"]`);
     }
+    /**
+     * Mocks the response of the datasource query call
+     * @param json the json response to return
+     * @param status the HTTP status code to return. Defaults to 200
+     */
     async mockQueryDataResponse(json, status = 200) {
         await this.ctx.page.route(this.ctx.selectors.apis.DataSource.queryPattern, async (route) => {
             await route.fulfill({ json, status });
         });
     }
+    /**
+     * Mocks the response of the datasource resource request
+     * @param path the path of the resource to mock
+     * @param json the json response to return
+     * @param status the HTTP status code to return. Defaults to 200
+     */
     async mockResourceResponse(path, json, status = 200) {
         await this.ctx.page.route(`${this.ctx.selectors.apis.DataSource.resourceUIDPattern}/${path}`, async (route) => {
             await route.fulfill({ json, status });
         });
+        // some data sources use the backendSrv directly, and then the path may be different
         await this.ctx.page.route(`${this.ctx.selectors.apis.DataSource.resourcePattern}/${path}`, async (route) => {
             await route.fulfill({ json, status });
         });
     }
+    /**
+     * Waits for a data source query data request to be made.
+     *
+     * @param cb optional callback to filter the request. Use this to filter by request body or other request properties
+     */
     async waitForQueryDataRequest(cb) {
         return this.ctx.page.waitForRequest((request) => {
             if (request.url().includes(this.ctx.selectors.apis.DataSource.query) && request.method() === 'POST') {
@@ -42,6 +69,11 @@ class GrafanaPage {
             return false;
         });
     }
+    /**
+     * Waits for a data source query data response
+     *
+     * @param cb optional callback to filter the response. Use this to filter by response body or other response properties
+     */
     async waitForQueryDataResponse(cb) {
         return this.ctx.page.waitForResponse((response) => {
             if (response.url().includes(this.ctx.selectors.apis.DataSource.query)) {

package/dist/models/PanelEditPage.js

@@ -67,6 +67,7 @@ class PanelEditPage extends GrafanaPage_1.GrafanaPage {
         return locator;
     }
     getPanelError() {
+        // the selector (not the selector value) used to identify a panel error changed in 9.4.3
         if (semver.lte(this.ctx.grafanaVersion, '9.4.3')) {
             return this.getByTestIdOrAriaLabel(this.ctx.selectors.components.Panels.Panel.headerCornerInfo(ERROR_STATUS));
         }
@@ -74,6 +75,7 @@ class PanelEditPage extends GrafanaPage_1.GrafanaPage {
     }
     async refreshPanel(options) {
         const responsePromise = this.ctx.page.waitForResponse((resp) => resp.url().includes(this.ctx.selectors.apis.DataSource.query), options);
+        // in older versions of grafana, the refresh button is rendered twice. this is a workaround to click the correct one
         await this.getByTestIdOrAriaLabel(this.ctx.selectors.components.PanelEditor.General.content)
             .locator(`selector=${this.ctx.selectors.components.RefreshPicker.runButtonV2}`)
             .click();

package/dist/models/TimeRange.js

@@ -11,9 +11,11 @@ class TimeRange extends GrafanaPage_1.GrafanaPage {
             await this.getByTestIdOrAriaLabel(this.ctx.selectors.components.TimePicker.openButton).click();
         }
         catch (e) {
+            // seems like in older versions of Grafana the time picker markup is rendered twice
             await this.ctx.page.locator('[aria-controls="TimePickerContent"]').last().click();
         }
         if (zone) {
+            //todo: add an e2e selector for the time zone picker and use it in grafana ui
             await this.ctx.page.getByRole('button', { name: 'Change time settings' }).click();
             await this.getByTestIdOrAriaLabel(this.ctx.selectors.components.TimeZonePicker.containerV2).fill(zone);
         }

package/dist/models/VariableEditPage.d.ts

@@ -9,5 +9,12 @@ export declare class VariableEditPage extends GrafanaPage {
     constructor(ctx: PluginTestCtx, args: DashboardEditViewArgs<string>);
     goto(options?: NavigateOptions): Promise<void>;
     setVariableType(type: VariableType): Promise<void>;
+    /**
+     * Triggers the variable query to run. Note that unlike {@link PanelEditPage.refreshPanel}, this method doesn't
+     * return a request promise. This is because there's no canonical way of querying variables - data sources may
+     * call any endpoint or resolve variables in the frontend. If you need to wait for a specific request, you can
+     * do that in your test.
+     * @example await this.ctx.page.waitForResponse((resp) => resp.url().includes('<url>')
+     */
     runQuery(): Promise<void>;
 }

package/dist/models/VariableEditPage.js

@@ -29,11 +29,20 @@ class VariableEditPage extends GrafanaPage_1.GrafanaPage {
         await this.ctx.page.keyboard.press('Enter');
         await this.getByTestIdOrAriaLabel(this.ctx.selectors.pages.Dashboard.Settings.Variables.Edit.General.generalTypeSelectV2).scrollIntoViewIfNeeded();
     }
+    /**
+     * Triggers the variable query to run. Note that unlike {@link PanelEditPage.refreshPanel}, this method doesn't
+     * return a request promise. This is because there's no canonical way of querying variables - data sources may
+     * call any endpoint or resolve variables in the frontend. If you need to wait for a specific request, you can
+     * do that in your test.
+     * @example await this.ctx.page.waitForResponse((resp) => resp.url().includes('<url>')
+     */
     async runQuery() {
+        // in 9.2.0, the submit button got a new purpose. it no longer submits the form, but instead runs the query
         if (gte(this.ctx.grafanaVersion, '9.2.0')) {
             await this.getByTestIdOrAriaLabel(this.ctx.selectors.pages.Dashboard.Settings.Variables.Edit.General.submitButton).click();
         }
         else {
+            // in 9.1.3, the submit button submits the form
             await this.ctx.page.keyboard.press('Tab');
         }
     }

package/dist/selectorEngine.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Returns a selector engine that resolves selectors by data-testid or aria-label
+ */
 export declare const grafanaE2ESelectorEngine: () => {
     query(root: Element, selector: string): Element;
     queryAll(root: Element, selector: string): NodeListOf<Element>;

package/dist/selectorEngine.js

@@ -1,13 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.grafanaE2ESelectorEngine = void 0;
+/**
+ * Returns a selector engine that resolves selectors by data-testid or aria-label
+ */
 const grafanaE2ESelectorEngine = () => ({
+    // Returns the first element matching given selector in the root's subtree.
     query(root, selector) {
         if (selector.startsWith('data-testid')) {
             return root.querySelector(`[data-testid="${selector}"]`);
         }
         return root.querySelector(`[aria-label="${selector}"]`);
     },
+    // Returns all elements matching given selector in the root's subtree.
     queryAll(root, selector) {
         if (selector.startsWith('data-testid')) {
             return root.querySelectorAll(`[data-testid="${selector}"]`);

package/dist/types.d.ts

@@ -1,9 +1,15 @@
 import { Locator, PlaywrightTestArgs } from '@playwright/test';
 import { E2ESelectors } from './e2e-selectors/types';
+/**
+ * The context object passed to page object models
+ */
 export type PluginTestCtx = {
     grafanaVersion: string;
     selectors: E2ESelectors;
 } & Pick<PlaywrightTestArgs, 'page' | 'request'>;
+/**
+ * The data source object
+ */
 export interface DataSource<T = any> {
     id?: number;
     editable?: boolean;
@@ -18,56 +24,167 @@ export interface DataSource<T = any> {
     jsonData?: T;
     secureJsonData?: T;
 }
+/**
+ * The dashboard object
+ */
 export interface Dashboard {
     uid: string;
     title?: string;
 }
+/**
+ * The YAML provision file parsed to a javascript object
+ */
 export type ProvisionFile<T = DataSource> = {
     datasources: Array<DataSource<T>>;
 };
 export type CreateDataSourceArgs = {
+    /**
+     * The data source to create
+     */
     datasource: DataSource;
 };
 export type CreateDataSourcePageArgs = {
+    /**
+     * The data source type to create
+     */
     type: string;
+    /**
+     * The data source name to create
+     */
     name?: string;
+    /**
+     * Set this to false to delete the data source via Grafana API after the test. Defaults to true.
+     */
     deleteDataSourceAfterTest?: boolean;
 };
 export type RequestOptions = {
+    /**
+     * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can
+     * be changed by using the
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
     timeout?: number;
 };
 export interface TimeRangeArgs {
+    /**
+     * The from time
+     * @example 'now-6h'
+     * @example '2020-01-01 00:00:00'
+     */
     from: string;
+    /**
+     * The to time
+     * @example 'now'
+     * @example '2020-01-01 00:00:00'
+     */
     to: string;
+    /**
+     * The time zone
+     * @example 'utc'
+     * @example 'browser'
+     */
     zone?: string;
 }
 export type DashboardPageArgs = {
+    /**
+     * The uid of the dashboard to go to
+     */
     uid?: string;
+    /**
+     * The time range to set
+     */
     timeRange?: TimeRangeArgs;
+    /**
+     * Query parameters to add to the url
+     */
     queryParams?: URLSearchParams;
 };
+/**
+ * DashboardEditViewArgs is used to pass arguments to the page object models that represent a dashboard edit view,
+ * such as {@link PanelEditPage}, {@link VariableEditPage} and {@link AnnotationEditPage}.
+ *
+ * If dashboard is not specified, it's assumed that it's a new dashboard. Otherwise, the dashboard uid is used to
+ * navigate to an already existing dashboard.
+ */
 export type DashboardEditViewArgs<T> = {
     dashboard?: DashboardPageArgs;
     id: T;
 };
 export type ReadProvisionArgs = {
+    /**
+     * The path, relative to the provisioning folder, to the dashboard json file
+     */
     filePath: string;
 };
 export type NavigateOptions = {
+    /**
+     * Referer header value.
+     */
     referer?: string;
+    /**
+     * Maximum operation time in milliseconds. Defaults to `0` - no timeout.
+     */
     timeout?: number;
+    /**
+     * When to consider operation succeeded, defaults to `load`. Events can be either:
+     * - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
+     * - `'load'` - consider operation to be finished when the `load` event is fired.
+     * - `'networkidle'` - **DISCOURAGED** consider operation to be finished when there are no network connections for
+     *   at least `500` ms. Don't use this method for testing, rely on web assertions to assess readiness instead.
+     * - `'commit'` - consider operation to be finished when network response is received and the document started
+     *   loading.
+     */
     waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+    /**
+     * Query parameters to add to the url. Optional
+     */
     queryParams?: URLSearchParams;
 };
 export type TriggerQueryOptions = {
+    /**
+     * Set this to true to skip waiting for the response. Defaults to false.
+     */
     skipWaitForResponse: boolean;
 };
+/**
+ * Panel visualization types
+ */
 export type Visualization = 'Alert list' | 'Bar gauge' | 'Clock' | 'Dashboard list' | 'Gauge' | 'Graph' | 'Heatmap' | 'Logs' | 'News' | 'Pie Chart' | 'Plugin list' | 'Polystat' | 'Stat' | 'Table' | 'Text' | 'Time series' | 'Worldmap Panel';
 export type AlertVariant = 'success' | 'warning' | 'error' | 'info';
 export interface AlertPageOptions {
+    /**
+     * Maximum wait time in milliseconds, defaults to 30 seconds, pass `0` to disable the timeout. The default value can
+     * be changed by using the
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
     timeout?: number;
+    /**
+     * Matches elements containing an element that matches an inner locator. Inner locator is queried against the outer
+     * one. For example, `article` that has `text=Playwright` matches `<article><div>Playwright</div></article>`.
+     *
+     * Note that outer and inner locators must belong to the same frame. Inner locator must not contain {@link
+     * FrameLocator}s.
+     */
     has?: Locator;
+    /**
+     * Matches elements that do not contain an element that matches an inner locator. Inner locator is queried against the
+     * outer one. For example, `article` that does not have `div` matches `<article><span>Playwright</span></article>`.
+     *
+     * Note that outer and inner locators must belong to the same frame. Inner locator must not contain {@link
+     * FrameLocator}s.
+     */
     hasNot?: Locator;
+    /**
+     * Matches elements that do not contain specified text somewhere inside, possibly in a child or a descendant element.
+     * When passed a [string], matching is case-insensitive and searches for a substring.
+     */
     hasNotText?: string | RegExp;
+    /**
+     * Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
+     * passed a [string], matching is case-insensitive and searches for a substring. For example, `"Playwright"` matches
+     * `<article><div>Playwright</div></article>`.
+     */
     hasText?: string | RegExp;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafana/plugin-e2e",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -44,5 +44,5 @@
     "semver": "^7.5.4",
     "uuid": "^9.0.1"
   },
-  "gitHead": "cd4548fcbe0a49b97effddfdc44cb21b659afccf"
+  "gitHead": "b907d536ea7d9d4ad920b10789663e99288cac58"
 }