If you’ve started using Github Copilot to generate Playwright test automation code, boost productivity further by helping Copilot follow your coding style and standards using the copilot-instructions.md file.
You’ve probably noticed that while the generated code often works, it doesn’t always follow your project’s conventions and best practice. As a result you may have to spend time adjusting the generated code to fit your project standards, often making the same changes to newly generated code over and over again.
A good way to combat this problem is to provide the AI with guidance on how to generate the Playwright code, by itemising all the structures and standards that you would like it to use. For Github Copilot this file is normally called copilot-instructions.md . In this article, we’ll walk through how to create this file for a Playwright test automation project, how AI tools in Visual Studio Code use it, and how it can help your team generate cleaner, more maintainable automated tests with far less manual correction.
What Is copilot-instructions.md?
copilot-instructions.md is a Markdown instruction file that defines coding guidelines for AI assistants working within your repository. (A markdown file is a plain text document that uses special tags or syntax to add structure, formatting, or meaning to content so it can be correctly interpreted by software or displayed to users – see the Markdown Cheatsheet)
Typical instructions include:
- preferred frameworks and languages
- project architecture
- naming conventions
- testing patterns
- libraries to use or avoid
For test automation projects, this is extremely useful because you can enforce patterns like:
- Page Object Model usage
- selector strategies
- assertion conventions
- test naming standards
Where to Place the copilot-instructions.md file
Github Copilot expects the instruction file to be located in the .github folder at the root of your repository:
Placing the file here ensures that Copilot reads it automatically when generating code in the repository.
Example copilot-instructions.md file
The best way to understand what the copilot-instructions.md markdown file should contain is to examine an example such as the one below. As you look through it I’m sure you’ll be able to see how you could adapt and extend it to conform to your project’s structure and standards.
Note that there is not a fixed set of heading titles such as Technology Stack – you can simply create your own where necessary and appropriate.
# Copilot Instructions
This repository contains UI tests built using Playwright and TypeScript.
## Technology Stack
- Playwright Test
- TypeScript
- Node.js
## Architecture
Tests follow the Page Object Model (POM).
Project structure:
/tests - Playwright test files
/pages - Page Object classes
/utils - shared helpers
/fixtures - Playwright fixtures
## Test File Conventions
Test files should:
- use the `.spec.ts` extension
- use `test.describe()` to group tests
- include clear, descriptive test names
Example:
test.describe('Login', () => {
test('user can log in with valid credentials', async ({ page }) => {
});
});
## Page Object Usage
Tests must not interact with selectors directly.
Bad:
await page.locator('#login-button').click();
Good:
await loginPage.loginButton.click();
## Selector Strategy
Selectors should be used in the following priority order:
1. data-testid
2. role-based selectors
3. visible text
Avoid fragile CSS and XPath selectors when possible.
## Assertions
Use Playwright's built-in `expect` assertions.
Example:
await expect(page).toHaveURL('/dashboard');
Avoid manual waits such as:
await page.waitForTimeout()
Use locator or page assertions instead.
## Test Design
Tests must:
- be independent
- avoid shared state
- clean up created data when necessary
- be able to run in any order
Tests should be designed to run in parallel.Other headings that you might consider include:
- Playwright Best Practice
- Typescript Coding Standards
NOTE: in Visual Studio Code you can view the contents of a Markdown file in a more readable format by choosing to view it ‘preview’ mode:
Tips for Writing Effective Instructions
Be Specific
Like a lot of interactions with AI tools, the best results are often obtained by being highly specific. For example when defining best practice for creating element selectors, specifying
Use good selectorsis too vague. Instead, provide more descriptive and precise instructions:
Selectors should be used in the following priority order:
1. data-testid
2. role-based selectors, e.g. GetByRole()
3. visible textBe Concise
Instruction files should be clear and focused, not massive documentation files. Otherwise they will quickly become unmaintainable and people will stop using them.
Aim for roughly 50–200 lines of guidance.
Show examples
Examples dramatically improve AI output.
Whenever possible, include short code snippets that demonstrate your preferred approach.
Combine With Other Documentation
For larger projects, your instruction file can link to additional documentation.
Example:
Refer to docs/coding-standards.md for detailed coding rules.
Refer to docs/architecture.md for framework design.
This allows Github Copilot to benefit from both concise instructions and deeper documentation.
What about Claude?
Claude can also receive guidance for generating Playwright test automation code, however it doesn’t specifically use the copilot-instructions.md file. Instead Claude is model-agnostic regarding filenames – it just needs Markdown files containing clear instructions or project context.
File naming conventions are flexible, but common patterns include:
CLAUDE.md
AI.md
AGENTS.md
LLM_CONTEXT.md
docs/coding-standards.md
docs/architecture.mdFurther Research
One of the best ways to learn more about this feature is to ask an AI. A few prompts that might be useful as a starting point for your investigation are:
For a Playwright test automation project using Typescript, give me 10 examples of headings I might use in my copilot-instructions.md file to help guide Github Copilot's generation of Playwright codeFor a Playwright test automation project using Typescript, give me 3 different sets of guidance rules I might consider putting in my copilot-instructions.md file to help guide Copilot's generation of Playwright code, specifically for Page Object Models. The 3 sets should reflect different ways of writing and using POM classes.What is the modern consensus for Playwright element selector type priority, including Playwright built-in selectors, and output guidelines for a Github Copliot copilot-instructions.md fileBuild on these LLM prompts for more information and to explore the capabilities more.
Conclusion
When used alongside GitHub Copilot, this small documentation file can dramatically improve the quality and consistency of AI generated test code. Instead of generic Playwright examples, you start getting tests that match your framework, architecture, and coding style.
In addition, this copilot-instructions.md file should be regarded as a living document that quality assurance professionals keep up to date. Across a large organisation in particular, it can be a good way to standardise Playwright test automation best practice, and perhaps be owned by a test automation Community of Practice containing QA representatives from all the development teams.