umbraco-playwright-testhelpers

Umbraco Playwright Testhelpers

これは何ですか？

@umbraco/playwright-testhelpers は、Umbraco のバックオフィスインスタンスに対する E2E テストを作成するための Playwright フィクスチャ、API ヘルパー、UI ヘルパーを提供する公式の Umbraco パッケージです。

リポジトリ: https://github.com/umbraco/Umbraco.Playwright.Testhelpers

インストール

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

関連スキル

• umbraco-e2e-testing - これらのヘルパーを使用した E2E テストパターン
• umbraco-test-builders - JsonModels.Builders（testhelpers が内部的に使用）
• umbraco-testing - テストの概要に関するマスタースキル

---

パッケージのエクスポート

このパッケージは以下の主要な項目をエクスポートします：

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 エクスポートは、Playwright の test を 2 つのフィクスチャで拡張します：

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
});

フィクスチャの仕組み

// 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 ヘルパー（umbracoApi）

ApiHelpers クラスは、各エンティティタイプに対応するサブヘルパーを提供します：

プロパティ	ヘルパークラス	目的
content	ContentApiHelper	コンテンツ/ドキュメントの操作
documentTypes	DocumentTypeApiHelper	ドキュメントタイプの操作
dataTypes	DatatypeApiHelper	データタイプの操作
media	MediaApiHelper	メディアの操作
mediaTypes	MediaTypeApiHelper	メディアタイプの操作
templates	TemplatesApiHelper	テンプレートの操作
languages	LanguagesApiHelper	言語の操作
users	UserApiHelper	ユーザーの操作
userGroups	UserGroupApiHelper	ユーザーグループの操作
members	MemberApiHelper	メンバーの操作
memberTypes	MemberTypeApiHelper	メンバータイプの操作
memberGroups	MemberGroupApiHelper	メンバーグループの操作
macros	MacroApiHelper	マクロの操作
scripts	ScriptApiHelper	スクリプトの操作
stylesheets	StylesheetApiHelper	スタイルシートの操作
partialViews	PartialViewApiHelper	部分ビューの操作
relationTypes	RelationTypeApiHelper	リレーションタイプの操作
packages	PackageApiHelper	パッケージの操作
domain	DomainApiHelper	ドメインの操作
translation	TranslationApiHelper	翻訳の操作
webhook	WebhookApiHelper	Webhook の操作

コア API メソッド

// 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);

---

ドキュメントタイプ API ヘルパー

// 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);

---

コンテンツ API ヘルパー

// 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);

---

データタイプ API ヘルパー

// 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');

---

メディア API ヘルパー

// 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 ヘルパー（umbracoUi）

ナビゲーション

// 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');

ツリー操作

// 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 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);

エディター操作

// 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');

ロケーターの取得

// 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();

アサーション

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

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

ドキュメントタイプ UI

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

// Update permissions
await umbracoUi.updateDocumentPermissionsToAllowCultureVariant();

コンテンツ UI

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

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

ファイルアップロード

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

ドラッグアンドドロップ

// 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

AliasHelper の詳細なドキュメントについては、umbraco-test-builders を参照してください。

---

JsonHelper

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

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

---

完全な例

完全なテスト例とテンプレートについては、umbraco-e2e-testing を参照してください。

---

ソース参照

• リポジトリ: https://github.com/umbraco/Umbraco.Playwright.Testhelpers
• ローカルパス: /Users/philw/Projects/Umbraco.Playwright.Testhelpers/
• 主要ファイル:
  • lib/helpers/ApiHelpers.ts - API ヘルパークラス
  • lib/helpers/UiHelpers.ts - UI ヘルパークラス
  • lib/helpers/testExtension.ts - テストフィクスチャ拡張
  • lib/helpers/ConstantHelper.ts - 定数
  • lib/helpers/AliasHelper.ts - エイリアスユーティリティ