Instructions personnalisées pour les agents IA

Les assistants de codage IA apprennent à partir du contexte. Lorsque vous fournissez un fichier d’instructions personnalisé qui décrit vos conventions de projet, l’IA génère du code de test qui correspond à votre style, utilise les API de boîte à outils appropriées et évite les erreurs courantes, sans avoir à expliquer les mêmes modèles chaque session.

Cet article explique comment écrire des fichiers d’instructions personnalisés pour différents assistants IA et ce qu’il faut inclure pour les tests Playwright power Platform.

Pourquoi les instructions personnalisées sont importantes

Sans instructions personnalisées, les assistants IA peuvent :

• Utiliser les méthodes "raw" page.locator() au lieu des méthodes "grid" et "form" ModelDrivenAppPage
• Oubli de définir la portée des localisateurs à iframe[name="fullscreen-app-host"]
• Utiliser des délais d’attente courts qui provoquent une défaillance dans les galeries alimentées par Dataverse
• Générer des sélecteurs fragiles nth-child au lieu d’attributs [row-index]
• Utiliser des données de test codées en dur qui provoquent des conflits entre les exécutions

Les instructions personnalisées résolvent ce problème en donnant à l’IA une référence toujours disponible pour l’API et les modèles de votre kit de ressources.

CLAUDE.md pour Claude (Anthropic)

Claude Code lit un CLAUDE.md fichier à la racine du référentiel (et dans les sous-répertoires). Créez 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!,
});

Applications canevas : toujours cibler l’iframe

Les applications de canevas s’affichent à l’intérieur d’un iframe imbriqué, de sorte que toutes les requêtes de localisateur doivent être limitées à cette trame pour rechercher les contrôles de manière fiable.

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

Applications de canevas : utilisez le délai d’attente de la galerie 60s pour waitFor

Les contrôles de galerie dans les applications de canevas peuvent prendre plus de temps pour s’afficher. Utilisez donc un délai d’expiration de 60 secondes lorsque vous attendez que les éléments de la galerie soient visibles.

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

Applications basées sur des modèles : utiliser GridComponent et FormComponent

Les applications basées sur des modèles exposent des composants intégrés de grille et de formulaire avec lesquels vous pouvez interagir directement via l'objet de page d'aide.

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

Utiliser des données de test uniques pour éviter les conflits

Ajoutez un horodatage ou un identificateur unique pour tester les données afin que les exécutions de tests parallèles ne se heurtent pas les unes aux autres.

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

Grille d’application pilotée par modèle : utilisez [row-index] et non nth-child

GridComponent gère cela en interne : n'écrivez pas de sélecteurs nth-child bruts.

Authentification : utiliser getStorageStatePath pour storageState

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

Importations

Importez toujours à partir du package du kit de ressources :

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

Configuration avancée de Claude Code

Pour le contexte par session, utilisez la commande barre oblique pour charger le /init contexte du projet ou ajoutez la mémoire au niveau de l’agent sous .claude/ la racine du dépôt :

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

Exemple .claude/settings.json:

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

.github/copilot-instructions.md pour GitHub Copilot

GitHub Copilot lit .github/copilot-instructions.md dans votre référentiel. Créez ce fichier :

# 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 pour Cursor et Windsurf

Le curseur lit .cursorrules et Windsurf lit .windsurfrules à la racine du dépôt. Créez l’un ou l’autre fichier avec le même contenu :

# 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'`

Agents de test Playwright

Les agents de test Playwright sont des processus IA de longue durée qui peuvent exécuter et corriger des tests de manière autonome. Configurez un agent pour comprendre votre kit de ressources en transmettant vos instructions personnalisées en tant que contexte système :

// 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.
      `,
    },
  },
});

Éléments à inclure dans les instructions personnalisées

Un bon fichier d’instructions personnalisées pour ce projet couvre :

Valider vos instructions

Testez vos instructions personnalisées en demandant à l’IA de :

1. Écrire un test pour une galerie de canevas : vérifiez qu’elle utilise l’iframe et le délai d’expiration 60s
2. Écrire un test CRUD piloté par un modèle : vérifier qu’il utilise des GridComponent méthodes
3. Réécrire un enregistrement codegen : vérifier qu’il utilise AppProvider

Si l’IA produit toujours du code playwright brut au lieu du code du kit de ressources, ajoutez une règle plus explicite à votre fichier d’instructions.

Étapes suivantes

• Serveur MCP Playwright
• Création de tests d’IA avec Copilot
• Démarrer

Voir aussi

• Vue d’ensemble des tests assistés par l’IA
• Exemples de tests
• Documentation sur les agents de test Playwright