From 950329511e830b918ecb37b376333b7d1b06e67f Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Wed, 9 Jul 2025 03:31:16 +0200 Subject: [PATCH] Playwright instructions typescript (#62) * feat: add Playwright test generation instructions and best practices * feat: add Playwright test generation instructions and related prompts * fix: standardize formatting of description and applyTo fields in Playwright instructions * fix: remove files not ready for submitting from README --------- Co-authored-by: Aaron Powell --- README.md | 1 + .../playwright-typescript.instructions.md | 86 +++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 instructions/playwright-typescript.instructions.md diff --git a/README.md b/README.md index db5f2d9..7d9d602 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [Memory Bank](instructions/memory-bank.instructions.md) | Bank specific coding standards and best practices | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmemory-bank.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fmemory-bank.instructions.md) | | [Next.js + Tailwind Development Instructions](instructions/nextjs-tailwind.instructions.md) | Next.js + Tailwind development standards and instructions | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fnextjs-tailwind.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fnextjs-tailwind.instructions.md) | | [Performance Optimization Best Practices](instructions/performance-optimization.instructions.md) | The most comprehensive, practical, and engineer-authored performance optimization instructions for all languages, frameworks, and stacks. Covers frontend, backend, and database best practices with actionable guidance, scenario-based checklists, troubleshooting, and pro tips. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fperformance-optimization.instructions.md) | +| [Playwright Typescript](instructions/playwright-typescript.instructions.md) | Playwright test generation instructions | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-typescript.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fplaywright-typescript.instructions.md) | | [Power Platform Connectors Schema Development Instructions](instructions/power-platform-connector-instructions.md) | Comprehensive development guidelines for Power Platform Custom Connectors using JSON Schema definitions. Covers API definitions (Swagger 2.0), API properties, and settings configuration with Microsoft extensions. | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpower-platform-connector-instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpower-platform-connector-instructions.md) | | [PowerShell Cmdlet Development Guidelines](instructions/powershell.instructions.md) | PowerShell cmdlet and scripting best practices based on Microsoft guidelines | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpowershell.instructions.md) | | [Python Coding Conventions](instructions/python.instructions.md) | Python coding conventions and guidelines | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython.instructions.md) [![Install in VS Code](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpython.instructions.md) | diff --git a/instructions/playwright-typescript.instructions.md b/instructions/playwright-typescript.instructions.md new file mode 100644 index 0000000..ccb01b5 --- /dev/null +++ b/instructions/playwright-typescript.instructions.md @@ -0,0 +1,86 @@ +--- +description: 'Playwright test generation instructions' +applyTo: '**' +--- + +## Test Writing Guidelines + +### Code Quality Standards +- **Locators**: Prioritize user-facing, role-based locators (`getByRole`, `getByLabel`, `getByText`, etc.) for resilience and accessibility. Use `test.step()` to group interactions and improve test readability and reporting. +- **Assertions**: Use auto-retrying web-first assertions. These assertions start with the `await` keyword (e.g., `await expect(locator).toHaveText()`). Avoid `expect(locator).toBeVisible()` unless specifically testing for visibility changes. +- **Timeouts**: Rely on Playwright's built-in auto-waiting mechanisms. Avoid hard-coded waits or increased default timeouts. +- **Clarity**: Use descriptive test and step titles that clearly state the intent. Add comments only to explain complex logic or non-obvious interactions. + + +### Test Structure +- **Imports**: Start with `import { test, expect } from '@playwright/test';`. +- **Organization**: Group related tests for a feature under a `test.describe()` block. +- **Hooks**: Use `beforeEach` for setup actions common to all tests in a `describe` block (e.g., navigating to a page). +- **Titles**: Follow a clear naming convention, such as `Feature - Specific action or scenario`. + + +### File Organization +- **Location**: Store all test files in the `tests/` directory. +- **Naming**: Use the convention `.spec.ts` (e.g., `login.spec.ts`, `search.spec.ts`). +- **Scope**: Aim for one test file per major application feature or page. + +### Assertion Best Practices +- **UI Structure**: Use `toMatchAriaSnapshot` to verify the accessibility tree structure of a component. This provides a comprehensive and accessible snapshot. +- **Element Counts**: Use `toHaveCount` to assert the number of elements found by a locator. +- **Text Content**: Use `toHaveText` for exact text matches and `toContainText` for partial matches. +- **Navigation**: Use `toHaveURL` to verify the page URL after an action. + + +## Example Test Structure + +```typescript +import { test, expect } from '@playwright/test'; + +test.describe('Movie Search Feature', () => { + test.beforeEach(async ({ page }) => { + // Navigate to the application before each test + await page.goto('https://debs-obrien.github.io/playwright-movies-app'); + }); + + test('Search for a movie by title', async ({ page }) => { + await test.step('Activate and perform search', async () => { + await page.getByRole('search').click(); + const searchInput = page.getByRole('textbox', { name: 'Search Input' }); + await searchInput.fill('Garfield'); + await searchInput.press('Enter'); + }); + + await test.step('Verify search results', async () => { + // Verify the accessibility tree of the search results + await expect(page.getByRole('main')).toMatchAriaSnapshot(` + - main: + - heading "Garfield" [level=1] + - heading "search results" [level=2] + - list "movies": + - listitem "movie": + - link "poster of The Garfield Movie The Garfield Movie rating": + - /url: /playwright-movies-app/movie?id=tt5779228&page=1 + - img "poster of The Garfield Movie" + - heading "The Garfield Movie" [level=2] + `); + }); + }); +}); +``` + +## Test Execution Strategy + +1. **Initial Run**: Execute tests with `npx playwright test --project=chromium` +2. **Debug Failures**: Analyze test failures and identify root causes +3. **Iterate**: Refine locators, assertions, or test logic as needed +4. **Validate**: Ensure tests pass consistently and cover the intended functionality +5. **Report**: Provide feedback on test results and any issues discovered + +## Quality Checklist + +Before finalizing tests, ensure: +- [ ] All locators are accessible and specific and avoid strict mode violations +- [ ] Tests are grouped logically and follow a clear structure +- [ ] Assertions are meaningful and reflect user expectations +- [ ] Tests follow consistent naming conventions +- [ ] Code is properly formatted and commented