Référence d’API

Cette API de kit de ressources Playwright Power Platform référence des classes publiques, des méthodes et des types que vous pouvez utiliser pour automatiser les tests de bout en bout des applications canevas et basées sur des modèles.

`AppProvider`

Point d’entrée pour le lancement d’applications Power Platform. Instanciez une fois par test, puis appelez launch().

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

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

`AppLaunchOptions`

Options passées pour AppProvider.launch() configurer l’application à ouvrir et comment procéder.

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`

Spécifie le type d’application Power Platform à lancer.

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

`AppLaunchMode`

Détermine si l’application s’ouvre en mode lecture ou en mode édition.

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

`ModelDrivenAppPage`

Retourné par AppProvider.getModelDrivenAppPage(). Fournit l’accès au composant et à la navigation.

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

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

`GridComponent`

Encapsule la grille du groupe de disponibilité utilisée dans les vues de liste pilotées par modèle. Accessible via 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`

Options permettant d’identifier l’enregistrement à ouvrir à partir de la grille.

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`

Encapsule le runtime de formulaire Dynamics 365. Accessible via 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()`

Exécute du code arbitraire dans le contexte de formulaire du navigateur avec un accès complet à l’API cliente Xrm :

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

Consultez les tests d’API via le contexte de formulaire pour une utilisation détaillée.

`CommandingComponent`

Encapsule la barre de commandes de l’application pilotée par modèle. Accessible via ModelDrivenAppPage.commanding.

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

`CanvasAppPage`

Retourné par AppProvider.getCanvasAppPage(). Fournit le localisateur d’images iframe de canevas.

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

`GenUxPage`

Retourné par AppProvider.getGenUxPage(). Fournit des interactions avec le concepteur GENUX du portail Power Apps Maker pour la création, la génération, l’inspection et la publication d’applications basées sur des modèles à partir d’invites IA.

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`

Expose l’iframe FrameLocator UCI Preview. Utilisez cette propriété pour interroger directement les éléments de formulaire générés :

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

`GenUxPage.verifyThoughtStreaming()`

Recherche les indicateurs de streaming GenUX temporaires, tels que le texte de pensée, le bouton Arrêter et les pensées de l’agent. Chaque vérification est optimale : la génération peut se terminer avant l’apparition de tous les indicateurs. La seule assertion dure est que la diffusion en continu est en cours ou "Your page is now generated" est visible.

`GenUxPage.searchAndPlayApp()`

Retourne null quand play est désactivé (l’application n’est pas encore publiée) au lieu de lever une erreur. Utiliser test.skip() sur un null retour :

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

Fonctions utilitaires

Fonctions d’assistance autonomes pour les tâches courantes d’installation et de configuration.

`buildCanvasAppUrlFromEnv`

CANVAS_APP_URL Lit à partir de l’environnement :

function buildCanvasAppUrlFromEnv(): string

`getStorageStatePath`

Retourne le chemin d’accès au fichier d’état de stockage Power Apps pour l’e-mail donné :

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

`ConfigHelper`

Fournit des assistances de configuration, telles que la vérification de l’expiration de l’état de stockage mis en cache.

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

Utilitaires de localisateur

Méthodes d’assistance pour localiser des contrôles Power Apps dans des iframes.

`LocatorUtils`

Méthodes statiques pour rechercher des contrôles d’application de canevas et des éléments de galerie par nom.

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

Exportations de types

Exportez tous les types à partir de la racine du package :

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

Référence d’API

AppProvider

AppLaunchOptions

AppType

AppLaunchMode

ModelDrivenAppPage

GridComponent

OpenRecordOptions

FormComponent

FormComponent.execute()

CommandingComponent

CanvasAppPage

GenUxPage

GenUxPage.previewFrame

GenUxPage.verifyThoughtStreaming()

GenUxPage.searchAndPlayApp()