@umbraco/playwright-testhelpers 17.0.18 → 17.0.19

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/ContentUiHelper.d.ts

@@ -192,6 +192,7 @@ export declare class ContentUiHelper extends UiBaseLocators {
     waitForModalHidden(): Promise<void>;
     clickSaveButtonForContent(): Promise<void>;
     enterTextstring(text: string): Promise<void>;
+    isTextstringPropertyVisible(isVisible?: boolean): Promise<void>;
     doesContentTreeHaveName(contentName: string): Promise<void>;
     enterRichTextArea(value: string): Promise<void>;
     enterTextArea(value: string): Promise<void>;
@@ -273,6 +274,7 @@ export declare class ContentUiHelper extends UiBaseLocators {
     isDocumentTypeNameVisible(contentName: string, isVisible?: boolean): Promise<void>;
     doesModalHaveText(text: string): Promise<void>;
     isTabNameVisible(tabName: string): Promise<void>;
+    clickTabWithName(tabName: string): Promise<void>;
     doesDocumentHaveName(name: string): Promise<void>;
     doesDocumentTableColumnNameValuesMatch(expectedValues: string[]): Promise<void>;
     searchByKeywordInCollection(keyword: string): Promise<void>;
@@ -455,4 +457,8 @@ export declare class ContentUiHelper extends UiBaseLocators {
     isAddBlockListElementWithNameVisible(blockName: string): Promise<void>;
     enterBlockPropertyValue(propertyName: string, value: string): Promise<void>;
     isBlockPropertyEditable(propertyName: string, isEditable?: boolean): Promise<void>;
+    isInlineBlockPropertyVisible(propertyName: string, isVisible?: boolean): Promise<void>;
+    isInlineBlockPropertyVisibleForBlockWithName(blockName: string, propertyName: string, isVisible?: boolean, index?: number): Promise<void>;
+    enterInlineBlockPropertyValue(propertyName: string, value: string, index?: number): Promise<void>;
+    doesInlineBlockPropertyHaveValue(propertyName: string, value: string, index?: number): Promise<void>;
 }

package/dist/lib/helpers/ContentUiHelper.js

@@ -432,6 +432,14 @@ class ContentUiHelper extends UiBaseLocators_1.UiBaseLocators {
         await this.textstringTxt.clear();
         await this.textstringTxt.fill(text);
     }
+    async isTextstringPropertyVisible(isVisible = true) {
+        if (isVisible) {
+            await (0, test_1.expect)(this.textstringTxt).toBeVisible();
+        }
+        else {
+            await (0, test_1.expect)(this.textstringTxt).not.toBeVisible();
+        }
+    }
     async doesContentTreeHaveName(contentName) {
         await (0, test_1.expect)(this.contentTree).toContainText(contentName);
     }
@@ -766,6 +774,11 @@ class ContentUiHelper extends UiBaseLocators_1.UiBaseLocators {
     async isTabNameVisible(tabName) {
         return (0, test_1.expect)(this.tabItems.filter({ hasText: tabName })).toBeVisible();
     }
+    async clickTabWithName(tabName) {
+        const tabLocator = this.tabItems.filter({ hasText: tabName });
+        await (0, test_1.expect)(tabLocator).toBeVisible();
+        await tabLocator.click();
+    }
     async doesDocumentHaveName(name) {
         return (0, test_1.expect)(this.enterAName).toHaveValue(name);
     }
@@ -1568,6 +1581,25 @@ class ContentUiHelper extends UiBaseLocators_1.UiBaseLocators {
         await (0, test_1.expect)(propertyLocator).toBeVisible();
         await (0, test_1.expect)(propertyLocator).toBeEditable({ editable: isEditable });
     }
+    async isInlineBlockPropertyVisible(propertyName, isVisible = true) {
+        const propertyLocator = this.blockListEntry.locator(this.blockProperty).filter({ hasText: propertyName });
+        await (0, test_1.expect)(propertyLocator).toBeVisible({ visible: isVisible });
+    }
+    async isInlineBlockPropertyVisibleForBlockWithName(blockName, propertyName, isVisible = true, index = 0) {
+        const blockEntryLocator = this.blockListEntry.filter({ hasText: blockName }).nth(index);
+        const propertyLocator = blockEntryLocator.locator(this.blockProperty).filter({ hasText: propertyName });
+        await (0, test_1.expect)(propertyLocator).toBeVisible({ visible: isVisible });
+    }
+    async enterInlineBlockPropertyValue(propertyName, value, index = 0) {
+        const propertyLocator = this.blockListEntry.nth(index).locator(this.blockProperty).filter({ hasText: propertyName });
+        await (0, test_1.expect)(propertyLocator).toBeVisible();
+        await propertyLocator.locator('input').clear();
+        await propertyLocator.locator('input').fill(value);
+    }
+    async doesInlineBlockPropertyHaveValue(propertyName, value, index = 0) {
+        const propertyLocator = this.blockListEntry.nth(index).locator(this.blockProperty).filter({ hasText: propertyName }).locator('input');
+        await (0, test_1.expect)(propertyLocator).toHaveValue(value);
+    }
 }
 exports.ContentUiHelper = ContentUiHelper;
 //# sourceMappingURL=ContentUiHelper.js.map