Write an agents.md file that improves AI-created test output and can be used for review before PR
26 Mar 2026
Writing an agents.md that outlines Playwright standards isn’t just documentation for its own sake—it directly improves how reliably and efficiently your automated agents (or test authors) behave.
The real benefits show up in consistency, speed, and fewer subtle bugs.
1. Consistent test behavior across agents
Without standards, different agents (or engineers) will:
Without standards, different agents (or engineers) will:
- select elements inconsistently
- structure tests in conflicting ways
An agents.md gives a single source of truth, so all Playwright usage follows the same patterns—making tests predictable and easier to debug.
2. Faster onboarding (for humans and AI agents)
New contributors—or AI agents writing tests—don’t need to guess:
New contributors—or AI agents writing tests—don’t need to guess:
- how to structure tests
- naming conventions
- how to handle auth, fixtures, retries, etc.
They can just follow the doc and produce “correct” output immediately.
3. Higher-quality code generation from agents
If you’re using AI agents to generate Playwright tests, this is huge:
If you’re using AI agents to generate Playwright tests, this is huge:
- The agent has clear constraints
- You reduce “creative but wrong” solutions
- Outputs become reusable instead of throwaway
Basically, it turns the agent from “sometimes helpful” into “consistently usable.”
5. Easier maintenance and refactoring
When tests follow the same patterns:
When tests follow the same patterns:
- bulk updates are easier (e.g., changing selector strategy)
- shared utilities actually get reused
- debugging patterns are familiar
Without standards, every test becomes a snowflake.
6. Encodes best practices once
Instead of repeating feedback in PRs like:
Instead of repeating feedback in PRs like:
- “don’t use hard waits”
- “use data-testid”
- “wrap this in a helper”
You encode that once in agents.md, and both humans and agents follow it automatically.
What makes a good agents.md for Playwright?
The value comes from being opinionated and specific, not generic. For example:
- ✅ “Always use getByTestId for selectors”
- ✅ “Use fixtures for authentication”
- ❌ “Write clean tests” (too vague)
Bottom line
An agents.md is less about documentation and more about control over behavior:
- It standardizes how tests are written
- It reduces flakiness and review overhead
- It dramatically improves AI-generated code quality
If you're using Playwright with agents, it's one of the highest-leverage things you can add.
Emily O'Connor
Principal Quality Engineer
She/Her
Technical leader with a sixth sense for bugs. Avid learner, passionate about translating "dev-speak" to enable teams adopt automation and AI-accelerated quality engineering. I believe great software starts with user-focused problem solving, and automation should surface the bugs that PMs actually care about fixing.
Sign in
to comment
With servers in >250 cities around the world, check your site for localization problems, broken GDPR banners, etc.
Explore MoT
See where AI genuinely helps, where it doesn’t, and how testers can stay firmly in control
Boost your career in software testing with the MoT Software Testing Essentials Certificate. Learn essential skills, from basic testing techniques to advanced risk analysis, crafted by industry experts.
Debrief the week in Quality via a community radio show hosted by Simon Tomes and members of the community
