Instrucciones personalizadas para agentes de IA

Los asistentes de codificación de IA aprenden del contexto. Cuando se proporciona un archivo de instrucciones personalizado que describe las convenciones del proyecto, la inteligencia artificial genera código de prueba que coincide con el estilo, usa las API del kit de herramientas adecuadas y evita errores comunes, sin tener que explicar los mismos patrones cada sesión.

En este artículo se muestra cómo escribir archivos de instrucciones personalizados para diferentes asistentes de IA y qué incluir para las pruebas de Power Platform Playwright.

¿Por qué importan las instrucciones personalizadas?

Sin instrucciones personalizadas, los asistentes de IA podrían:

• Usar page.locator() crudo en lugar de los métodos de ModelDrivenAppPage de cuadrícula y formulario
• No olvide acotar los localizadores a iframe[name="fullscreen-app-host"]
• Uso de tiempos de espera cortos que producen errores en galerías respaldadas por Dataverse
• Genere selectores frágiles nth-child en lugar de atributos [row-index]
• Uso de datos de prueba codificados de forma dura que provocan conflictos entre ejecuciones

Las instrucciones personalizadas resuelven este problema proporcionando a la IA una referencia siempre disponible para la API y los patrones del kit de herramientas.

CLAUDE.md para Claude (antrópico)

Claude Code lee un CLAUDE.md archivo en la raíz del repositorio (y en subdirectorios). Creación de 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!,
});

Aplicaciones de lienzo: siempre delimitar al iframe

Las aplicaciones de Canvas se renderizan dentro de un iframe anidado, por lo que todas las consultas de localizador deben estar constriñidas a ese marco para encontrar controles de manera confiable.

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

Aplicaciones de lienzo: utilice un tiempo de espera de 60 segundos para la función de espera de la galería.

Los controles de la galería en aplicaciones de lienzo pueden tardar más tiempo en representarse, por lo que se usa un tiempo de espera de 60 segundos al esperar a que los elementos de la galería sean visibles.

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

Aplicaciones controladas por modelos: usar GridComponent y FormComponent

Las aplicaciones controladas por modelos exponen componentes integrados de cuadrícula y formulario con los que puede interactuar directamente a través del objeto de página auxiliar.

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

Uso de datos de prueba únicos para evitar conflictos

Anexe una marca de tiempo o un identificador único para probar los datos para que las ejecuciones de pruebas paralelas no entren en conflicto entre sí.

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

Cuadrícula de aplicaciones controladas por modelos: use [row-index] en lugar de nth-child

GridComponent gestiona esto internamente: no escriba selectores nth-child en su forma original.

Autenticación: uso de getStorageStatePath para storageState

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

Importaciones

Importe siempre desde el paquete del kit de herramientas:

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

Configuración avanzada de Claude Code

Para el contexto por sesión, use el /init comando de barra diagonal para cargar el contexto del proyecto o agregue memoria de nivel de agente en .claude/ la raíz del repositorio:

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

Ejemplo .claude/settings.json:

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

.github/copilot-instructions.md para GitHub Copilot

GitHub Copilot lee .github/copilot-instructions.md en tu repositorio. Cree este archivo:

# 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 para Cursor y Windsurf

El cursor lee .cursorrules y Windsurf lee .windsurfrules en la raíz del repositorio. Cree cualquiera de los archivos con el mismo contenido:

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

Agentes de prueba de Playwright

Los agentes de prueba de Playwright son procesos de inteligencia artificial de larga duración que pueden ejecutar y corregir pruebas de forma autónoma. Configure un agente para comprender el kit de herramientas pasando las instrucciones personalizadas como contexto del sistema:

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

Qué incluir en las instrucciones personalizadas

Un buen archivo de instrucciones personalizado para este proyecto abarca:

Validación de las instrucciones

Pruebe las instrucciones personalizadas pidiendo a la inteligencia artificial que:

1. Escribe una prueba para una galería de lienzos: verifica que utiliza el elemento Iframe y un tiempo de espera de 60 segundos.
2. Escriba una prueba CRUD basada en modelos: compruebe que usa GridComponent métodos.
3. Reescritura de una grabación de codegen: compruebe que usa AppProvider

Si la inteligencia artificial sigue produciendo código Playwright sin procesar en lugar de código del framework, añade una regla más explícita al archivo de instrucciones.

Pasos siguientes

• Servidor MCP de Playwright
• creación de pruebas de AI con Copilot
• Introducción

Consulte también

• Introducción a las pruebas asistidas por IA
• Pruebas de ejemplo
• Documentación de agentes de prueba de Playwright