umbraco-playwright-testhelpers

Umbraco Playwright Testhelpers

What is it?

@umbraco/playwright-testhelpers is the official Umbraco package that provides Playwright fixtures, API helpers, and UI helpers for writing E2E tests against an Umbraco backoffice instance.

Repository: https://github.com/umbraco/Umbraco.Playwright.Testhelpers

Installation

npm install @umbraco/playwright-testhelpers --save-dev

Related Skills

• umbraco-e2e-testing - E2E test patterns using these helpers
• umbraco-test-builders - JsonModels.Builders (used internally by testhelpers)
• umbraco-testing - Master skill for testing overview

---

Package Exports

The package exports these main items:

import {
  test,              // Extended Playwright test with fixtures
  ApiHelpers,        // Direct API helper class
  UiHelpers,         // Direct UI helper class
  ConstantHelper,    // Constants for sections, actions, buttons
  AliasHelper,       // Alias generation utilities
  JsonHelper         // JSON parsing utilities
} from '@umbraco/playwright-testhelpers';

---

Test Fixtures

The test export extends Playwright's test with two fixtures:

import { test } from '@umbraco/playwright-testhelpers';

test('my test', async ({ umbracoApi, umbracoUi }) => {
  // umbracoApi - API helpers for fast test setup/teardown
  // umbracoUi - UI helpers for backoffice interaction
});

How Fixtures Work

// testExtension.ts (internal)
const test = base.extend<{umbracoApi: ApiHelpers} & {umbracoUi: UiHelpers}>({
  umbracoApi: async ({ page }, use) => {
    const umbracoApi = new ApiHelpers(page);
    await use(umbracoApi);
  },
  umbracoUi: async ({ page }, use) => {
    const umbracoUi = new UiHelpers(page);
    await use(umbracoUi);
  }
});

---

API Helpers (umbracoApi)

The ApiHelpers class provides sub-helpers for each entity type:

Property	Helper Class	Purpose
content	ContentApiHelper	Content/document operations
documentTypes	DocumentTypeApiHelper	Document type operations
dataTypes	DatatypeApiHelper	Data type operations
media	MediaApiHelper	Media operations
mediaTypes	MediaTypeApiHelper	Media type operations
templates	TemplatesApiHelper	Template operations
languages	LanguagesApiHelper	Language operations
users	UserApiHelper	User operations
userGroups	UserGroupApiHelper	User group operations
members	MemberApiHelper	Member operations
memberTypes	MemberTypeApiHelper	Member type operations
memberGroups	MemberGroupApiHelper	Member group operations
macros	MacroApiHelper	Macro operations
scripts	ScriptApiHelper	Script operations
stylesheets	StylesheetApiHelper	Stylesheet operations
partialViews	PartialViewApiHelper	Partial view operations
relationTypes	RelationTypeApiHelper	Relation type operations
packages	PackageApiHelper	Package operations
domain	DomainApiHelper	Domain operations
translation	TranslationApiHelper	Translation operations
webhook	WebhookApiHelper	Webhook operations

Core API Methods

// Base HTTP methods (available on umbracoApi directly)
await umbracoApi.get(url, params?);
await umbracoApi.post(url, data?);
await umbracoApi.delete(url, data?);

// CSRF token (automatically handled)
await umbracoApi.getCsrfToken();

// Login
await umbracoApi.login(skipCheckTours?: boolean);

---

Document Type API Helper

// Ensure cleanup (idempotent - won't fail if not exists)
await umbracoApi.documentTypes.ensureNameNotExists('MyDocType');

// Create default document type
const docType = await umbracoApi.documentTypes.createDefaultDocumentType('MyDocType');

// Create element type (for blocks)
const elementType = await umbracoApi.documentTypes.createDefaultElementType('MyElement', 'myElement');

// Create document type with block grid
const element = await umbracoApi.documentTypes.createDefaultDocumentWithBlockGridEditor(element?, dataType?);

// Save document type (using builder)
const docType = new DocumentTypeBuilder()
  .withName('MyDocType')
  .withAlias('myDocType')
  .build();
await umbracoApi.documentTypes.save(docType);

---

Content API Helper

// Reference: ContentApiHelper.ts patterns
// Note: Actual methods depend on version - check source

// Common patterns:
await umbracoApi.content.ensureNameNotExists('MyContent');
await umbracoApi.content.createDefaultContent(name, documentTypeId);
await umbracoApi.content.getByName('MyContent');
await umbracoApi.content.publish(contentId);

---

Data Type API Helper

// Get built-in data type
const dataType = await umbracoApi.dataTypes.getByName('Textstring');

// Create block grid data type
const blockGrid = await umbracoApi.dataTypes.createDefaultBlockGrid('MyBlockGrid', elementType);

// Ensure cleanup
await umbracoApi.dataTypes.ensureNameNotExists('MyDataType');

---

Media API Helper

// Create media folder
await umbracoApi.media.createDefaultMediaFolder('MyFolder');

// Create image with file
await umbracoApi.media.createImageWithFile(
  'MyImage',
  { src: '/path/to/image.jpg' },
  'image.jpg',
  '/local/path/to/image.jpg',
  'image/jpeg'
);

// Cleanup
await umbracoApi.media.ensureNameNotExists('MyImage');
await umbracoApi.media.clearRecycleBin();

---

UI Helpers (umbracoUi)

Navigation

// Navigate to section
await umbracoUi.goToSection(ConstantHelper.sections.content);
await umbracoUi.goToSection(ConstantHelper.sections.settings);
await umbracoUi.goToSection(ConstantHelper.sections.media);

// Navigate to specific items
await umbracoUi.navigateToContent('MyContent');
await umbracoUi.navigateToMedia('MyMedia');
await umbracoUi.navigateToDocumentType('MyDocType');
await umbracoUi.navigateToDataType('MyDataType');
await umbracoUi.navigateToTemplate('MyTemplate');

Tree Operations

// Get tree item by path
const item = await umbracoUi.getTreeItem('contentTypes', ['MyFolder', 'MyDocType']);

// Refresh trees
await umbracoUi.refreshContentTree();
await umbracoUi.refreshMediaTree();

// Wait for tree load
await umbracoUi.waitForTreeLoad('settings');

Click Operations

// Click by data-element attribute
await umbracoUi.clickDataElementByElementName('tree-item-myItem');

// Click by text
await umbracoUi.clickButtonByText('Save');

// Click element
await umbracoUi.clickElement(locator);

// Click multiple elements
await umbracoUi.clickMultiple(locator);

Editor Operations

// Set header name (with alias generation wait)
await umbracoUi.setEditorHeaderName('My Document');

// Get editor header name
await umbracoUi.getEditorHeaderName('My Document');

// Add property group and editor
await umbracoUi.goToAddEditor('Content', 'Title');

Locator Getters

// Get elements
const helpButton = await umbracoUi.getGlobalHelp();
const userButton = await umbracoUi.getGlobalUser();
const element = await umbracoUi.getDataElementByElementName('my-element');
const button = await umbracoUi.getButtonByText('Save');
const button = await umbracoUi.getButtonByLabelKey('buttons_save');
const contextAction = await umbracoUi.getContextMenuAction('action-create');

// Notifications
const success = await umbracoUi.getSuccessNotification();
const error = await umbracoUi.getErrorNotification();

Assertions

// Check notifications
await umbracoUi.isSuccessNotificationVisible();
await umbracoUi.isErrorNotificationVisible();

// Check data type exists
await umbracoUi.doesDataTypeExist('MyDataType');

Document Type UI

// Create with template
await umbracoUi.createNewDocumentTypeWithTemplate();

// Update permissions
await umbracoUi.updateDocumentPermissionsToAllowCultureVariant();

Content UI

// Create content
await umbracoUi.createContentWithDocumentType('MyDocType');

// Switch culture
await umbracoUi.switchCultureInContent('Danish');

File Upload

// Upload file
await umbracoUi.fileUploader('/path/to/file.jpg');

Drag and Drop

// Drag and drop elements
await umbracoUi.dragAndDrop(
  fromLocator,
  toLocator,
  verticalOffset,
  horizontalOffset,
  steps?
);

---

ConstantHelper

import { ConstantHelper } from '@umbraco/playwright-testhelpers';

// Sections
ConstantHelper.sections.content    // "content"
ConstantHelper.sections.media      // "media"
ConstantHelper.sections.settings   // "settings"
ConstantHelper.sections.users      // "users"
ConstantHelper.sections.member     // "member"
ConstantHelper.sections.packages   // "packages"
ConstantHelper.sections.translation // "translation"

// Actions (data-element values)
ConstantHelper.actions.create      // "action-create"
ConstantHelper.actions.delete      // "action-delete"
ConstantHelper.actions.copy        // "action-copy"
ConstantHelper.actions.move        // "action-move"
ConstantHelper.actions.sort        // "action-sort"
ConstantHelper.actions.save        // "saveNew"
ConstantHelper.actions.publish     // "publishNew"
ConstantHelper.actions.documentType // "action-documentType"
ConstantHelper.actions.dataType    // "action-data-type"
ConstantHelper.actions.remove      // "actions_remove"

// Buttons (label-key values)
ConstantHelper.buttons.save           // "buttons_save"
ConstantHelper.buttons.saveAndPublish // "buttons_saveAndPublish"
ConstantHelper.buttons.delete         // "general_delete"
ConstantHelper.buttons.ok             // "general_ok"
ConstantHelper.buttons.close          // "general_close"
ConstantHelper.buttons.insert         // "general_insert"
ConstantHelper.buttons.download       // "general_download"
ConstantHelper.buttons.submit         // "general_submit"
ConstantHelper.buttons.rollback       // "actions_rollback"
ConstantHelper.buttons.add            // "general_add"
ConstantHelper.buttons.submitChanges  // "buttons_submitChanges"
ConstantHelper.buttons.remove         // "general_remove"
ConstantHelper.buttons.change         // "general_change"
ConstantHelper.buttons.select         // "buttons_select"

// Content Apps
ConstantHelper.contentApps.info // '[data-element="sub-view-umbInfo"]'

---

AliasHelper

See umbraco-test-builders for comprehensive AliasHelper documentation.

---

JsonHelper

import { JsonHelper } from '@umbraco/playwright-testhelpers';

// Parse response body
const response = await umbracoApi.get(url);
const body = await JsonHelper.getBody(response);

---

Complete Examples

See umbraco-e2e-testing for full test examples and templates.

---

Source Reference

• Repository: https://github.com/umbraco/Umbraco.Playwright.Testhelpers
• Local path: /Users/philw/Projects/Umbraco.Playwright.Testhelpers/
• Main files:
  • lib/helpers/ApiHelpers.ts - API helper class
  • lib/helpers/UiHelpers.ts - UI helper class
  • lib/helpers/testExtension.ts - Test fixture extension
  • lib/helpers/ConstantHelper.ts - Constants
  • lib/helpers/AliasHelper.ts - Alias utilities