Benutzerdefinierte Anweisungen für KI-Agents

KI-Codierungsassistenten lernen aus dem Kontext. Wenn Sie eine benutzerdefinierte Anleitungsdatei bereitstellen, die Ihre Projektkonventionen beschreibt, generiert die KI Testcode, der Ihrem Stil entspricht, verwendet die richtigen Toolkit-APIs und vermeidet häufige Fehler – ohne dass Sie die gleichen Muster jeder Sitzung erklären müssen.

In diesem Artikel wird gezeigt, wie Sie benutzerdefinierte Anweisungsdateien für verschiedene KI-Assistenten schreiben und was Sie für Power Platform Playwright-Tests einschließen müssen.

Warum benutzerdefinierte Anweisungen wichtig sind

Ohne benutzerdefinierte Anweisungen können KI-Assistenten:

• Verwenden Sie page.locator() Rohdaten anstelle der Methoden ModelDrivenAppPage Raster und Formular.
• Vergessen Sie nicht, Locatoren auf iframe[name="fullscreen-app-host"] zuzuordnen
• Verwenden Sie kurze Timeouts, die bei von Dataverse gesicherten Galerien fehlschlagen
• Generieren von spröden nth-child Selektoren anstelle von [row-index] Attributen
• Verwenden von hartcodierten Testdaten, die Konflikte zwischen Ausführungen verursachen

Benutzerdefinierte Anweisungen lösen dieses Problem, indem sie der KI eine immer verfügbare Referenz für die API und Muster Ihres Toolkits geben.

CLAUDE.md für Claude (Anthropic)

Claude Code liest eine CLAUDE.md Datei im Repositorystamm (und in Unterverzeichnissen). Erstellen Sie packages/e2e-tests/CLAUDE.md:

# Power Platform Playwright Tests

## Project structure

- Toolkit: `power-platform-playwright-toolkit` (local package)
- Tests: `packages/e2e-tests/tests/`
- Page objects: `packages/e2e-tests/pages/`
- Auth state: `packages/e2e-tests/.playwright-ms-auth/`

## Key conventions

### Always use AppProvider to launch apps

```typescript
const app = new AppProvider(page, context);
await app.launch({
  app: 'App Name',
  type: AppType.Canvas,           // or AppType.ModelDriven
  mode: AppLaunchMode.Play,
  skipMakerPortal: true,
  directUrl: process.env.CANVAS_APP_URL!,
});

Canvas-Apps: immer den iFrame anvisieren

Canvas-Apps werden in einem geschachtelten iframe gerendert, sodass alle Locator-Abfragen auf diesen Frame zugeschnitten sein müssen, um Steuerelemente zuverlässig zu finden.

const canvasFrame = page.frameLocator('iframe[name="fullscreen-app-host"]');

Canvas-Apps: Timeout von 60s für Gallery WaitFor verwenden

Katalogsteuerelemente in Canvas-Apps können länger gerendert werden. Verwenden Sie daher ein Timeout von 60 Sekunden, wenn sie darauf warten, dass Katalogelemente sichtbar werden.

await canvasFrame.locator('[data-control-part="gallery-item"]').first()
  .waitFor({ state: 'visible', timeout: 60000 });

Modellgesteuerte Apps: Verwenden von GridComponent und FormComponent

Modellgesteuerte Apps machen integrierte Raster- und Formularkomponenten verfügbar, mit denen Sie direkt über das Hilfsseitenobjekt interagieren können.

const mda = app.getModelDrivenAppPage();
await mda.grid.filterByKeyword('ORD-001');
await mda.grid.waitForGridLoad();
await mda.grid.openRecord({ rowNumber: 0 });
await mda.form.getAttribute('nwind_ordernumber');
await mda.form.save();

Verwenden sie eindeutige Testdaten, um Konflikte zu vermeiden

Fügen Sie einen Zeitstempel oder einen eindeutigen Bezeichner an, um Daten zu testen, damit parallele Testläufe nicht miteinander kollidieren.

const accountName = `Test Account ${Date.now()}`;

Modellgesteuertes App-Raster: [Zeilenindex] statt nth-child verwenden

Das GridComponent wird intern behandelt: Schreiben Sie keine rohen nth-child-Selektoren.

Auth: Nutzen Sie getStorageStatePath für storageState

import { getStorageStatePath } from 'power-platform-playwright-toolkit';
test.use({ storageState: getStorageStatePath(process.env.MS_AUTH_EMAIL!) });

Importe

Immer aus dem Toolkitpaket importieren:

import {
  AppProvider,
  AppType,
  AppLaunchMode,
  buildCanvasAppUrlFromEnv,
  getStorageStatePath,
} from 'power-platform-playwright-toolkit';

Erweiterte Claude Code-Konfiguration

Verwenden Sie für den Kontext pro Sitzung den /init Slash-Befehl, um den Projektkontext zu laden, oder fügen Sie Speicher auf Agentenebene im .claude/ Repository-Stamm hinzu.

.claude/
  settings.json      # MCP server config, permissions
  commands/          # Custom slash commands

Beispiel .claude/settings.json:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp"]
    }
  },
  "permissions": {
    "allow": [
      "Bash(npx playwright *)",
      "Bash(npm run auth*)"
    ]
  }
}

.github/copilot-instructions.md für GitHub Copilot

GitHub Copilot liest .github/copilot-instructions.md in Ihrem Repository vor. Erstellen Sie diese Datei:

# Copilot instructions for Power Platform Playwright tests

## Tech stack
- Playwright test runner with TypeScript
- Custom toolkit: `power-platform-playwright-toolkit`
- Rush monorepo (use `node common/scripts/install-run-rush.js build` not `npm run build`)

## Test file conventions
- Tests live in `packages/e2e-tests/tests/`
- Page objects live in `packages/e2e-tests/pages/`
- Import from `'power-platform-playwright-toolkit'`, not from relative paths

## App launch
Always use [`AppProvider`](api-reference.md#appprovider) with `skipMakerPortal: true` and `directUrl`.

## Canvas apps
- Scope all locators to `page.frameLocator('iframe[name="fullscreen-app-host"]')`
- Use 60 second timeouts for gallery `waitFor` calls
- Identify controls via `data-control-name` attribute (inspect in DevTools)

## Model-driven apps
- Use `app.getModelDrivenAppPage()` to get [`ModelDrivenAppPage`](api-reference.md#modeldrivenapppage) 
- Use `mda.grid.*` for grid interactions, `mda.form.*` for form interactions
- After `filterByKeyword`, always call `mda.grid.waitForGridLoad()`

## Test data
- Always use unique names: `\`Test ${Date.now()}\``
- Never hardcode strings that could clash across parallel test runs

agents.md für Cursor und Windsurfen

Cursor liest .cursorrules und Windsurf liest .windsurfrules im Repository-Stamm. Erstellen Sie entweder eine Datei mit demselben Inhalt:

# Power Platform Playwright test conventions

You are helping write end-to-end tests for Power Platform apps using Playwright and a custom toolkit.

## Framework
- Test runner: Playwright (`@playwright/test`)
- Toolkit: `power-platform-playwright-toolkit` (workspace package)
- App types: Canvas, ModelDriven, CustomPage (canvas embedded in MDA)

## Critical rules

1. **Canvas apps always use an iframe**
   - Frame: `page.frameLocator('iframe[name="fullscreen-app-host"]')`
   - All canvas locators must be scoped to this frame

2. **Gallery timeouts must be 60 seconds**
   - Dataverse galleries take 30–60s to load
   - Use `waitFor({ state: 'visible', timeout: 60000 })`

3. **Model-driven grids use GridComponent**
   - Never use raw `page.locator('[role="row"]')` for grid rows
   - Use `mda.grid.filterByKeyword()`, `mda.grid.getCellValue()`, `mda.grid.openRecord()`

4. **Always use unique test data**
   - Pattern: `` `Test Name ${Date.now()}` ``

5. **Import only from the toolkit**
   - `import { AppProvider, AppType, AppLaunchMode } from 'power-platform-playwright-toolkit'`

Testagenten für Playwright

Playwright-Test-Agents sind langlebige KI-Prozesse, die Tests autonom ausführen und beheben können. Konfigurieren Sie einen Agent, um Ihr Toolkit zu verstehen, indem Sie Ihre benutzerdefinierten Anweisungen als Systemkontext übergeben:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  // ...
  use: {
    // Agent context: pass custom instructions to the test agent
    agentContext: {
      systemPrompt: `
        You are testing Power Platform apps using the power-platform-playwright-toolkit.
        Canvas apps render in iframe[name="fullscreen-app-host"].
        Always scope canvas locators to the frame.
        Gallery waitFor timeouts should be 60000ms.
        Use mda.grid.* and mda.form.* for model-driven apps.
      `,
    },
  },
});

Was in benutzerdefinierte Anweisungen eingeschlossen werden soll

Eine gute benutzerdefinierte Anleitungsdatei für dieses Projekt umfasst:

Überprüfen Ihrer Anweisungen

Testen Sie Ihre benutzerdefinierten Anweisungen, indem Sie die KI auffordern:

1. Schreiben Sie einen Test für eine Canvas-Galerie: Überprüfen Sie, ob das iframe und das 60-Sekunden-Timeout verwendet werden.
2. Schreiben eines modellgesteuerten CRUD-Tests: Überprüfen, ob methoden verwendet werden GridComponent
3. Neuschreiben einer Codegen-Aufzeichnung: Überprüfen, ob sie verwendet wird AppProvider

Wenn die KI immer noch unformatierten Playwright-Code anstelle von Toolkit-Code erzeugt, fügen Sie Ihrer Anweisungendatei eine explizitere Regel hinzu.

Nächste Schritte

• Playwright MCP-Server
• AI-Testerstellung mit Copilot
• Erste Schritte

Siehe auch

• Übersicht über KI-unterstützte Tests
• Beispieltests
• Playwright-Testagenten-Dokumentation