API-Tests über Formularkontext

Die FormComponent.execute()-Methode führt beliebiges JavaScript innerhalb des Dynamics 365 Formularkontexts direkt für die Xrm-API aus. Dieser Ansatz ermöglicht einen Hybridtestansatz. Verwenden Sie Playwright, um zu einem Datensatz zu navigieren, und verwenden Sie execute() dann, um Daten programmgesteuert zu überprüfen oder zu bearbeiten. Dieser Ansatz ersetzt UI-Interaktionen, die langsam oder unzuverlässig sind.

So funktioniert es

Wenn Sie einen modellgesteuerten App-Eintrag im Browser öffnen, ist das Xrm-Objekt verfügbar.window.Xrm Die execute() Methode überbrückt den Playwright Node.js Kontext und den Browserseitenkontext. Sie fügt Ihre Funktion in den Browser ein und gibt das Ergebnis zurück:

const result = await modelDrivenApp.form.execute(async (formContext) => {
  // This code runs inside the browser, with access to the full Xrm API
  return formContext.getAttribute('nwind_ordernumber')?.getValue();
});

console.log(`Order number from Xrm: ${result}`);

formContext ist das Standardobjekt Dynamics 365 Xrm.Form.FormContext. Sie können eine beliebige Xrm-Client-API-Methode verwenden.

Lesen von Feldwerten über Xrm

Dient execute() zum Lesen von Feldwerten, ohne sich auf DOM-Selektoren zu verlassen:

// Read a text field
const orderNumber = await mda.form.execute(
  (ctx) => ctx.getAttribute('nwind_ordernumber')?.getValue()
);

// Read a lookup field
const customer = await mda.form.execute((ctx) => {
  const lookup = ctx.getAttribute('nwind_customerid')?.getValue();
  return lookup?.[0]?.name ?? null;
});

// Read a choice/option set
const statusCode = await mda.form.execute(
  (ctx) => ctx.getAttribute('nwind_orderstatusid')?.getValue()
);

Schreiben von Feldwerten über Xrm

Programmgesteuertes Festlegen von Feldwerten ohne Ausfüllen von Eingabeelementen:

await mda.form.execute((ctx) => {
  ctx.getAttribute('nwind_ordernumber')?.setValue('ORD-API-001');
  ctx.getAttribute('nwind_notes')?.setValue('Updated via Xrm API');
});

Überprüfen von Geschäftslogikregeln

Testen Sie, dass Geschäftsregeln auf Feldebene oder Formularebene ordnungsgemäß ausgelöst werden.

// Open a record
await mda.grid.openRecord({ rowNumber: 0 });

// Trigger a field change
await mda.form.setAttribute('nwind_orderstatusid', 'Shipped');

// Validate that a business rule made the tracking field required
const requiredLevel = await mda.form.execute(
  (ctx) => ctx.getAttribute('nwind_trackingnumber')?.getRequiredLevel()
);

expect(requiredLevel).toBe('required');

Überprüfung der Gültigkeit und des Bearbeitungszustands des Formulars

Verwenden Sie die isDirty(), isValid() und save() Methoden, um zu überprüfen, ob Formularänderungen ordnungsgemäß nachverfolgt werden und dass die Überprüfung vor und nach dem Speichern bestanden wird.

// After making changes, verify the form is dirty
const isDirty = await mda.form.isDirty();
expect(isDirty).toBe(true);

// Save and verify no validation errors
await mda.form.save();
expect(await mda.form.isValid()).toBe(true);
expect(await mda.form.isDirty()).toBe(false);

Ausführen von Xrm WebApi-Aufrufen

Die vollständige Xrm.WebApi ist innerhalb execute() verfügbar. Verwenden Sie sie, um Dataverse-Datensätze direkt abzufragen oder zu verändern.

// Query Dataverse records without navigating the grid
const result = await mda.form.execute(async (formContext) => {
  const response = await (window as any).Xrm.WebApi.retrieveMultipleRecords(
    'nwind_orders',
    '?$filter=nwind_orderstatus eq 1&$select=nwind_ordernumber&$top=5'
  );
  return response.entities.map((e: any) => e.nwind_ordernumber);
});

expect(result.length).toBeGreaterThan(0);

Test von Plugin-Nebenwirkungen

Verwenden Sie execute() nach dem Speichern eines Datensatzes, um zu überprüfen, ob ein Plug-In ein verwandtes Feld ordnungsgemäß aktualisiert hat.

// Create a new order via UI
await mda.navigateToFormView('nwind_orders');
await page.locator('input[data-id="nwind_ordernumber.fieldControl-text-box-text"]').fill('ORD-PLUGIN-TEST');
await mda.form.save();

// Wait for plugin async processing
await page.waitForTimeout(3000);

// Verify the plugin set the calculated total
const calculatedTotal = await mda.form.execute(
  (ctx) => ctx.getAttribute('nwind_calculatedtotal')?.getValue()
);

expect(calculatedTotal).toBeGreaterThan(0);

Kombinieren der UI-Navigation mit API-Assertionen

Ein gängiges Muster besteht darin, die Navigation über die Benutzeroberfläche zu steuern und dann den Zustand über die API zu überprüfen. Im folgenden Beispiel wird ein Auftrag aus dem Raster geöffnet, auf die Schaltfläche Bestellung senden geklickt, und anschließend wird die Xrm-API verwendet, um zu bestätigen, dass der Auftragsstatus auf Ausstehend aktualisiert wurde.

test('submit order sets status to Pending', async ({ page, context }) => {
  const app = new AppProvider(page, context);
  await app.launch({ ... });
  const mda = app.getModelDrivenAppPage();

  // Navigate to the order via the grid (UI path)
  await mda.navigateToGridView('nwind_orders');
  await mda.grid.filterByKeyword('ORD-001');
  await mda.grid.waitForGridLoad();
  await mda.grid.openRecord({ rowNumber: 0 });

  // Click Submit via the command bar (UI path)
  await mda.commanding.clickButton('Submit Order');
  await page.waitForTimeout(2000);

  // Validate the status via Xrm API (API assertion)
  const status = await mda.form.execute(
    (ctx) => ctx.getAttribute('nwind_orderstatusid')?.getValue()
  );

  expect(status).toBe(100000001); // Pending option set value
});

Referenz zur Formularkontext-API

Der rückruf execute() empfängt ein Standardkontextobjekt Dynamics 365 form. Schlüsselmethoden:

Die vollständige Xrm-Client-API-Referenz finden Sie unter Microsoft Dataverse Client-API-Referenz.

Nächste Schritte

• Testen modellgesteuerter Apps
• Seitenobjektmodell
• API-Referenz

Siehe auch

• FormComponent-API
• Beispieltests
• Xrm-Client-API-Referenz