@umbraco/playwright-testhelpers 17.0.18 → 17.1.0-beta

package/README.md

@@ -1,48 +1,158 @@
-# Umbraco.Playwright.Testhelpers
-This package contains the Test-helpers for the Umbraco Playwright tests!
+# Umbraco Playwright Test Helpers
+
+Test helpers for writing Playwright end-to-end tests for Umbraco CMS.
+
+**Repository:** https://github.com/umbraco/umbraco-playwright-testhelpers
 
 ## Prerequisites
-This project was made with Node V16, so the minimum requirement is node `16.17.1`
-Having playwright installed, you can install playwright by running `npx playwright install`
 
-## Getting started
-You can import a helper into your code like so
+- **Node.js:** Minimum version `16.17.1`
+- **Playwright:** Install via `npx playwright install`
 
+## Installation
+
+```bash
+npm install @umbraco/playwright-testhelpers
 ```
-import {  ConstantHelper } from "@umbraco/playwright-testhelpers";
-```
 
-You can then use it in your code like so:
+## Usage
+
+### Basic Test Setup
+
+Import the `test` fixture from the package to get access to `umbracoApi` and `umbracoUi` helpers:
+
+```typescript
+import { test } from "@umbraco/playwright-testhelpers";
+
+test('my test', async ({ umbracoApi, umbracoUi }) => {
+  // Your test code here
+});
 ```
-let settingsSection = ConstantHelper.sections.settings;
+
+### API Helpers
+
+Use API helpers for test setup, teardown, and backend verification:
+
+```typescript
+import { test } from "@umbraco/playwright-testhelpers";
+
+test('create document type via API', async ({ umbracoApi }) => {
+  const name = 'TestDocType';
+
+  // Cleanup before test
+  await umbracoApi.documentType.ensureNameNotExists(name);
+
+  // Create via API
+  await umbracoApi.documentType.createDefaultDocumentType(name);
+
+  // Cleanup after test
+  await umbracoApi.documentType.ensureNameNotExists(name);
+});
 ```
 
-## Contributing to Umbraco.Playwright.Testhelpers
+### UI Helpers
 
-### Adding new helpers
-When adding new helpers, it is important to add them as properties in the `ApiHelpers.ts` class 
-Lets say we have just created a `MacroApiHelper`, first we would need to import it at the top in the `ApiHelpers.ts` file like so:
+Use UI helpers for browser-based interactions:
+
+```typescript
+import { test } from "@umbraco/playwright-testhelpers";
+
+test('create content via UI', async ({ umbracoUi }) => {
+  await umbracoUi.goToBackOffice();
+  await umbracoUi.content.clickActionsMenuAtRoot();
+  await umbracoUi.content.clickCreateButton();
+});
 ```
-import {MacroApiHelper} from "./MacroApiHelper";
+
+### Combined API and UI Testing
+
+A common pattern is using API helpers for setup/teardown and UI helpers for the actual test:
+
+```typescript
+import { test } from "@umbraco/playwright-testhelpers";
+
+test('edit document type', async ({ umbracoApi, umbracoUi }) => {
+  const name = 'TestDocType';
+
+  // Setup via API
+  await umbracoApi.documentType.ensureNameNotExists(name);
+  await umbracoApi.documentType.createDefaultDocumentType(name);
+
+  // Test via UI
+  await umbracoUi.goToBackOffice();
+  await umbracoUi.documentType.goToDocumentType(name);
+
+  // Cleanup via API
+  await umbracoApi.documentType.ensureNameNotExists(name);
+});
 ```
-Then, add it as a property
+
+### Constants and Utilities
+
+```typescript
+import { ConstantHelper, AliasHelper, NotificationConstantHelper } from "@umbraco/playwright-testhelpers";
+
+// Access UI sections
+const settingsSection = ConstantHelper.sections.settings;
+
+// Convert strings to aliases
+const alias = AliasHelper.toAlias('My Document Type'); // 'myDocumentType'
+
+// Access notification messages
+const successMsg = NotificationConstantHelper.success.created;
 ```
+
+## Available Helpers
+
+### API Helpers (`umbracoApi.*`)
+
+`dataType`, `dictionary`, `document`, `documentBlueprint`, `documentType`, `healthCheck`, `indexer`, `language`, `login`, `logViewer`, `media`, `mediaType`, `member`, `memberGroup`, `memberType`, `modelsBuilder`, `objectTypes`, `package`, `partialView`, `publishedCache`, `redirectManagement`, `relationType`, `script`, `smtp`, `stylesheet`, `telemetry`, `template`, `temporaryFile`, `user`, `userGroup`, `webhook`
+
+### UI Helpers (`umbracoUi.*`)
+
+`content`, `contentRender`, `currentUserProfile`, `dataType`, `dictionary`, `documentBlueprint`, `documentType`, `examineManagement`, `externalLogin`, `form`, `healthCheck`, `install`, `language`, `login`, `logViewer`, `media`, `mediaType`, `member`, `memberGroup`, `memberType`, `modelsBuilder`, `package`, `partialView`, `profiling`, `publishedStatus`, `redirectManagement`, `relationType`, `script`, `stylesheet`, `telemetryData`, `template`, `user`, `userGroup`, `webhook`, `welcomeDashboard`
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `URL` | Umbraco base URL | `https://localhost:44339` |
+| `UMBRACO_USER_LOGIN` | Admin user email | `nge@umbraco.dk` |
+| `UMBRACO_USER_PASSWORD` | Admin user password | `1234567890` |
+| `UMBRACO_MEMBER_LOGIN` | Test member email | `member@example.com` |
+| `UMBRACO_MEMBER_PASSWORD` | Test member password | `Umbraco9Rocks!` |
+
+## Contributing
+
+### Adding New Helpers
+
+1. Create your helper file (e.g., `MacroApiHelper.ts`)
+
+2. Import and add as a property in `ApiHelpers.ts`:
+```typescript
+import { MacroApiHelper } from "./MacroApiHelper";
+
 export class ApiHelpers {
-  macros: MacroApiHelper;
-  ...
- }
+  macro: MacroApiHelper;
+
+  constructor(page: Page) {
+    this.macro = new MacroApiHelper(this);
+  }
+}
 ```
 
-Then, use the constructor to populate the property
+3. For UI helpers, extend `UiBaseLocators` and add to `UiHelpers.ts`
 
+### Testing Changes Locally
+
+```bash
+npm run build
+npm pack
+npm i /path/to/umbraco-playwright-testhelpers-x.x.x.tgz
 ```
-constructor(page: Page) {
-    this.macros = new MacroApiHelper(this);
-    ...
-}
-```
 
-### Testing your changes locally
-When you have changes you want to test, you can run `npm run build` & `npm pack` in the root of this folder, You will need to copy the absolute path of the file you just created with `npm pack`.
-then run `npm i absolute path to your file` in the project where you are using this package. An example could be `npm i C:\Users\ABC\Desktop\Umbraco.Playwright.Testhelpers\umbraco-playwright-testhelpers-1.0.0.tgz`.
-If you have new changes, you can follow the same steps as before.
+## License
+
+MIT

package/dist/lib/helpers/BasePage.d.ts

@@ -0,0 +1,447 @@
+import { Locator, Page } from "@playwright/test";
+/**
+ * Base page class providing common UI interaction methods.
+ * All methods follow best practices for reliability:
+ * - click: Always checks element visibility before clicking
+ * - enterText: Always clears before filling text
+ * - select: Waits for element visibility before selecting
+ *
+ * @example
+ * ```typescript
+ * class MyPage extends BasePage {
+ *   readonly submitBtn: Locator;
+ *
+ *   constructor(page: Page) {
+ *     super(page);
+ *     this.submitBtn = page.getByRole('button', { name: 'Submit' });
+ *   }
+ *
+ *   async submit() {
+ *     await this.click(this.submitBtn);
+ *   }
+ * }
+ * ```
+ */
+export declare class BasePage {
+    readonly page: Page;
+    constructor(page: Page);
+    /**
+     * Clicks an element after verifying it is visible.
+     * @param locator - The element to click
+     * @param options - Optional click configuration
+     */
+    click(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Double-clicks an element after verifying it is visible.
+     * @param locator - The element to double-click
+     * @param options - Optional configuration
+     */
+    doubleClick(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Right-clicks an element after verifying it is visible.
+     * @param locator - The element to right-click
+     * @param options - Optional configuration
+     */
+    rightClick(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Clicks an element using JavaScript (bypasses actionability checks).
+     * Use when standard click doesn't work due to overlapping elements.
+     * @param locator - The element to click
+     */
+    forceClick(locator: Locator): Promise<void>;
+    /**
+     * Enters text into an input field after clearing it.
+     * Verifies element visibility before interaction.
+     * @param locator - The input element
+     * @param text - The text to enter
+     * @param options - Optional configuration
+     */
+    enterText(locator: Locator, text: string, options?: {
+        clearFirst?: boolean;
+        verify?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Types text character by character (simulates real typing).
+     * Useful when fill() doesn't trigger necessary events.
+     * @param locator - The input element
+     * @param text - The text to type
+     * @param options - Optional configuration
+     */
+    typeText(locator: Locator, text: string, options?: {
+        clearFirst?: boolean;
+        delay?: number;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Clears an input field.
+     * @param locator - The input element to clear
+     */
+    clearText(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Presses a keyboard key while focused on an element.
+     * @param locator - The element to focus
+     * @param key - The key to press (e.g., 'Enter', 'Tab', 'Escape')
+     */
+    pressKey(locator: Locator, key: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects an option from a dropdown by value.
+     * @param locator - The select element
+     * @param value - The option value to select
+     */
+    selectByValue(locator: Locator, value: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects an option from a dropdown by visible text.
+     * @param locator - The select element
+     * @param text - The option text to select
+     */
+    selectByText(locator: Locator, text: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects an option from a dropdown by index.
+     * @param locator - The select element
+     * @param index - The option index to select (0-based)
+     */
+    selectByIndex(locator: Locator, index: number, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects multiple options from a multi-select dropdown.
+     * @param locator - The select element
+     * @param values - Array of option values to select
+     */
+    selectMultiple(locator: Locator, values: string[], options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Checks a checkbox if it's not already checked.
+     * @param locator - The checkbox element
+     */
+    check(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Unchecks a checkbox if it's currently checked.
+     * @param locator - The checkbox element
+     */
+    uncheck(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Sets a checkbox to a specific state.
+     * @param locator - The checkbox element
+     * @param checked - Whether the checkbox should be checked
+     */
+    setChecked(locator: Locator, checked: boolean, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Hovers over an element.
+     * @param locator - The element to hover over
+     */
+    hover(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Focuses on an element.
+     * @param locator - The element to focus
+     */
+    focus(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Hovers over one element and clicks another (for menus that appear on hover).
+     * @param hoverLocator - The element to hover over
+     * @param clickLocator - The element to click after hover
+     */
+    hoverAndClick(hoverLocator: Locator, clickLocator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Waits for an element to be visible.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForVisible(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be hidden.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForHidden(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be attached to the DOM.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForAttached(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be detached from the DOM.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForDetached(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for the page to finish loading (network idle).
+     */
+    waitForPageLoad(): Promise<void>;
+    /**
+     * Waits for the DOM to be fully loaded.
+     */
+    waitForDOMContentLoaded(): Promise<void>;
+    /**
+     * Waits for all network requests to complete.
+     */
+    waitForLoadState(): Promise<void>;
+    /**
+     * Waits for an element to be enabled.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForEnabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be disabled.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForDisabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to contain specific text.
+     * @param locator - The element to wait for
+     * @param text - The text to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForText(locator: Locator, text: string, timeout?: number): Promise<void>;
+    /**
+     * Waits for an input to have a specific value.
+     * @param locator - The input element to wait for
+     * @param value - The value to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForValue(locator: Locator, value: string, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to have a specific attribute value.
+     * @param locator - The element to wait for
+     * @param name - The attribute name
+     * @param value - The expected attribute value
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForAttribute(locator: Locator, name: string, value: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to have a specific CSS class.
+     * @param locator - The element to wait for
+     * @param className - The CSS class to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForClass(locator: Locator, className: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be editable.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForEditable(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be checked.
+     * @param locator - The checkbox/radio element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForChecked(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be unchecked.
+     * @param locator - The checkbox/radio element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForUnchecked(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for a specific URL or URL pattern.
+     * @param url - The URL string or regex pattern to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForURL(url: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Waits for a navigation to complete.
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForNavigation(timeout?: number): Promise<void>;
+    /**
+     * Waits for a specific time (use sparingly, prefer explicit waits).
+     * @param milliseconds - Time to wait in milliseconds
+     */
+    waitForTimeout(milliseconds: number): Promise<void>;
+    /**
+     * Waits for a network request to a specific URL.
+     * @param urlOrPredicate - URL string, regex, or predicate function
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForRequest(urlOrPredicate: string | RegExp | ((request: any) => boolean), timeout?: number): Promise<any>;
+    /**
+     * Waits for a network response from a specific URL.
+     * @param urlOrPredicate - URL string, regex, or predicate function
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForResponse(urlOrPredicate: string | RegExp | ((response: any) => boolean), timeout?: number): Promise<any>;
+    /**
+     * Waits for an element to be focused.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForFocused(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be empty (no text content).
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForEmpty(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for a function to return true.
+     * @param predicate - Function that returns a boolean or Promise<boolean>
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForFunction(predicate: () => boolean | Promise<boolean>, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to have a specific CSS property value.
+     * @param locator - The element to wait for
+     * @param property - The CSS property name
+     * @param value - The expected CSS property value
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForCSS(locator: Locator, property: string, value: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element is visible.
+     * @param locator - The element to check
+     * @param isVisible - Whether the element should be visible (default: true)
+     */
+    isVisible(locator: Locator, isVisible?: boolean, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element is enabled.
+     * @param locator - The element to check
+     */
+    isEnabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element is disabled.
+     * @param locator - The element to check
+     */
+    isDisabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element contains specific text.
+     * @param locator - The element to check
+     * @param text - The text to look for
+     */
+    containsText(locator: Locator, text: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element has specific text.
+     * @param locator - The element to check
+     * @param text - The exact text expected
+     */
+    hasText(locator: Locator, text: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an input has a specific value.
+     * @param locator - The input element to check
+     * @param value - The expected value
+     */
+    hasValue(locator: Locator, value: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element has a specific attribute value.
+     * @param locator - The element to check
+     * @param name - The attribute name
+     * @param value - The expected attribute value
+     */
+    hasAttribute(locator: Locator, name: string, value: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that a specific number of elements exist.
+     * @param locator - The locator to count
+     * @param count - The expected count
+     */
+    hasCount(locator: Locator, count: number, timeout?: number): Promise<void>;
+    /**
+     * Gets the text content of an element.
+     * @param locator - The element to get text from
+     * @returns The text content
+     */
+    getText(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<string>;
+    /**
+     * Gets the value of an input element.
+     * @param locator - The input element
+     * @returns The input value
+     */
+    getValue(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<string>;
+    /**
+     * Gets an attribute value from an element.
+     * @param locator - The element
+     * @param attributeName - The attribute name
+     * @returns The attribute value or null
+     */
+    getAttribute(locator: Locator, attributeName: string, options?: {
+        timeout?: number;
+    }): Promise<string | null>;
+    /**
+     * Checks if an element is currently visible.
+     * @param locator - The element to check
+     * @returns True if visible, false otherwise
+     */
+    checkIsVisible(locator: Locator): Promise<boolean>;
+    /**
+     * Checks if a checkbox is checked.
+     * @param locator - The checkbox element
+     * @returns True if checked, false otherwise
+     */
+    isChecked(locator: Locator): Promise<boolean>;
+    /**
+     * Scrolls an element into view.
+     * @param locator - The element to scroll to
+     */
+    scrollIntoView(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Sets files on a file input element.
+     * @param locator - The file input element
+     * @param filePath - Path to the file(s) to set
+     */
+    setInputFiles(locator: Locator, filePath: string | string[]): Promise<void>;
+    /**
+     * Clears files from a file input.
+     * @param locator - The file input element
+     */
+    clearInputFiles(locator: Locator): Promise<void>;
+    /**
+     * Drags an element and drops it on another element.
+     * @param source - The element to drag
+     * @param target - The element to drop on
+     */
+    dragTo(source: Locator, target: Locator, options?: {
+        sourcePosition?: {
+            x: number;
+            y: number;
+        };
+        targetPosition?: {
+            x: number;
+            y: number;
+        };
+    }): Promise<void>;
+}