مرجع واجهة برمجة التطبيقات

تشير واجهة برمجة تطبيقات مجموعة أدوات Power Platform Playwright هذه إلى الفئات والأساليب والأنواع العامة التي يمكنك استخدامها لأتمتة الاختبار الشامل للتطبيقات المستندة إلى اللوحات والتطبيقات المستندة إلى النموذج.

AppProvider

نقطة الإدخال لبدء تشغيل تطبيقات Power Platform. أنشئ مثيلا مرة واحدة لكل اختبار، ثم استدع launch().

class AppProvider {
  constructor(page: Page, context: BrowserContext)

  launch(options: AppLaunchOptions): Promise<void>
  getModelDrivenAppPage(): ModelDrivenAppPage
  getCanvasAppPage(): CanvasAppPage
  getGenUxPage(): GenUxPage
}

AppLaunchOptions

تم تمرير الخيارات إلى AppProvider.launch() لتكوين التطبيق الذي سيتم فتحه وكيفية فتحه.

interface AppLaunchOptions {
  app: string;                  // Display name of the app
  type: AppType;                // Canvas | ModelDriven
  mode: AppLaunchMode;          // Play | Edit
  skipMakerPortal?: boolean;    // true: use directUrl, skip make.powerapps.com navigation
  directUrl?: string;           // Full URL when skipMakerPortal is true
}

AppType

يحدد نوع تطبيق Power Platform لتشغيله.

enum AppType {
  Canvas = 'canvas',
  ModelDriven = 'model-driven',
}

AppLaunchMode

تحديد ما إذا كان التطبيق يفتح في وضع التشغيل أو وضع التحرير.

enum AppLaunchMode {
  Play = 'play',
  Edit = 'edit',
}

---

ModelDrivenAppPage

تم إرجاعه بواسطة AppProvider.getModelDrivenAppPage(). يوفر التنقل والوصول إلى المكونات.

class ModelDrivenAppPage {
  readonly grid: GridComponent
  readonly form: FormComponent
  readonly commanding: CommandingComponent

  navigateToGridView(entityLogicalName: string): Promise<void>
  navigateToFormView(entityLogicalName: string): Promise<void>
}

---

GridComponent

التفاف شبكة AG المستخدمة في طرق عرض القائمة المستندة إلى النموذج. يتم الوصول إليه عبر ModelDrivenAppPage.grid.

class GridComponent {
  waitForGridLoad(): Promise<void>

  filterByKeyword(keyword: string): Promise<void>
  filterByColumn(columnName: string, value: string): Promise<void>

  getCellValue(rowIndex: number, columnName: string): Promise<string | null>
  getRowCount(): Promise<number>
  isGridEmpty(): Promise<boolean>

  openRecord(options: OpenRecordOptions): Promise<void>
  selectRow(rowIndex: number): Promise<void>
  selectRows(rowIndexes: number[]): Promise<void>
}

OpenRecordOptions

خيارات لتحديد السجل الذي سيتم فتحه من الشبكة.

interface OpenRecordOptions {
  rowNumber?: number;         // 0-based row index
  columnName?: string;        // column to match (display name or schema name)
  columnValue?: string;       // value to match in the column
}

---

FormComponent

التفاف وقت تشغيل النموذج Dynamics 365. يتم الوصول إليه عبر ModelDrivenAppPage.form.

class FormComponent {
  getAttribute(fieldName: string): Promise<string | null>
  setAttribute(fieldName: string, value: string): Promise<void>

  save(): Promise<void>
  isDirty(): Promise<boolean>
  isValid(): Promise<boolean>

  navigateToTab(tabName: string): Promise<void>

  setFieldVisibility(fieldName: string, visible: boolean): Promise<void>
  setFieldDisabled(fieldName: string, disabled: boolean): Promise<void>
  setFieldRequiredLevel(
    fieldName: string,
    level: 'none' | 'recommended' | 'required'
  ): Promise<void>

  execute<T>(
    fn: (formContext: Xrm.FormContext) => T | Promise<T>
  ): Promise<T>
}

FormComponent.execute()

تشغيل التعليمات البرمجية العشوائية في سياق نموذج المتصفح مع الوصول الكامل إلى واجهة برمجة تطبيقات عميل Xrm:

const value = await mda.form.execute(
  (ctx) => ctx.getAttribute('nwind_ordernumber')?.getValue()
);

راجع اختبار واجهة برمجة التطبيقات من خلال سياق النموذج للحصول على استخدام مفصل.

---

CommandingComponent

التفاف شريط أوامر التطبيق المستند إلى النموذج. يتم الوصول إليه عبر ModelDrivenAppPage.commanding.

class CommandingComponent {
  clickButton(ariaLabel: string): Promise<void>
  clickMoreCommands(): Promise<void>
}

---

CanvasAppPage

تم إرجاعه بواسطة AppProvider.getCanvasAppPage(). يوفر محدد موقع إطار iframe لللوحة.

class CanvasAppPage {
  getFrame(): FrameLocator
  waitForLoad(controlName?: string): Promise<void>
}

---

GenUxPage

تم إرجاعه بواسطة AppProvider.getGenUxPage(). يوفر تفاعلات مع مصمم الذكاء الاصطناعي Power Apps Maker Portal GenUX لإنشاء التطبيقات المستندة إلى النموذج وإنشاءها وفحصها ونشرها من مطالبات الذكاء الاصطناعي.

class GenUxPage {
  readonly previewFrame: FrameLocator  // UCI Preview iframe locator

  // Power Apps navigation
  goToAppsPage(): Promise<void>
  navigateToStartWithPageDesign(): Promise<void>
  createAppWithName(appName: string): Promise<void>
  addNewPage(): Promise<void>

  // AI generation
  waitForUCIPreviewFrameAndFillPrompt(prompt: string): Promise<void>
  waitForUCIPreviewFrameAndSelectTemplate(templateText: string): Promise<void>
  verifyThoughtStreaming(): Promise<void>
  verifyCodeAndPreviewTabsAvailable(): Promise<void>
  verifyCodeStreaming(): Promise<void>

  // Inspection
  clickPreviewTab(): Promise<void>
  clickCodeTab(): Promise<void>
  waitForGeneratedContent(): Promise<void>
  waitForCodeTabContent(): Promise<void>
  getPreviewTabDom(): Promise<string>
  getCodeTabContent(): Promise<string>

  // Publishing
  publishApp(): Promise<void>
  buildCanvasPlayUrl(): string

  // Form interaction
  submitForm(): Promise<void>
  waitForSubmitSuccess(timeout?: number): Promise<void>

  // App management
  getAppIdFromUrl(): string
  searchAndPlayApp(appName: string, context: BrowserContext): Promise<Page | null>
  deleteAppsMatchingPrefix(prefix: string): Promise<void>
  deleteAppFromAppListIfFound(appName: string): Promise<void>
}

GenUxPage.previewFrame

FrameLocator يعرض ل UCI Preview iframe. استخدم هذه الخاصية للاستعلام عن عناصر النموذج التي تم إنشاؤها مباشرة:

const input = genUxPage.previewFrame.getByRole('textbox', { name: 'First Name' });
await expect(input).toBeVisible();

GenUxPage.verifyThoughtStreaming()

التحقق من مؤشرات دفق GenUX العابرة، مثل نص الفكر وزر الإيقاف وأفكار العامل. كل فحص هو أفضل جهد - قد يكتمل الإنشاء قبل ظهور جميع المؤشرات. التأكيد الثابت الوحيد هو أن البث قيد التقدم أو "Your page is now generated" مرئي.

GenUxPage.searchAndPlayApp()

إرجاع null عند تعطيل التشغيل (لم يتم نشر التطبيق بعد) بدلا من طرح خطأ. استخدم test.skip() عند null إرجاع:

const appPage = await genUxPage.searchAndPlayApp(appName, context);
if (!appPage) test.skip();

---

وظائف الأداة المساعدة

وظائف المساعد المستقلة لمهام الإعداد والتكوين الشائعة.

buildCanvasAppUrlFromEnv

القراءات CANVAS_APP_URL من البيئة:

function buildCanvasAppUrlFromEnv(): string

getStorageStatePath

إرجاع المسار إلى ملف حالة التخزين Power Apps للبريد الإلكتروني المحدد:

function getStorageStatePath(email: string): string
// Returns: packages/e2e-tests/.playwright-ms-auth/state-<email>.json

ConfigHelper

يوفر مساعدي التكوين، مثل التحقق مما إذا كانت حالة التخزين المخزن مؤقتا قد انتهت صلاحيتها.

class ConfigHelper {
  static checkStorageStateExpiration(
    statePath: string
  ): { expired: boolean; expiresOn?: number }
}

---

أدوات تحديد المواقع المساعدة

أساليب المساعد لتحديد موقع عناصر تحكم Power Apps داخل iframes.

LocatorUtils

أساليب ثابتة للعثور على عناصر تحكم تطبيق اللوحة وعناصر المعرض حسب الاسم.

class LocatorUtils {
  static getByControlName(frame: FrameLocator, controlName: string): Locator
  static getGalleryItem(frame: FrameLocator, titleText: string): Locator
}

---

عمليات تصدير النوع

تصدير جميع الأنواع من جذر الحزمة:

import {
  AppProvider,
  AppType,
  AppLaunchMode,
  AppLaunchOptions,
  ModelDrivenAppPage,
  GridComponent,
  FormComponent,
  CommandingComponent,
  CanvasAppPage,
  GenUxPage,
  buildCanvasAppUrlFromEnv,
  getStorageStatePath,
  ConfigHelper,
  LocatorUtils,
} from 'power-platform-playwright-toolkit';

الخطوات التالية

• متغيرات البيئة
• مرجع التكوين
• عينات الاختبارات

راجع أيضًا

• اختبار تطبيقات اللوحة
• اختبار التطبيقات المستندة إلى النموذج
• اختبار واجهة برمجة التطبيقات من خلال سياق النموذج