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 and QE with a sixth sense for bugs. Avid learner and reader interested in decoding “dev-speak” to enable engineering teams to adopt automation and AI accelerated quality engineering. I believe good software starts with user-focused problem solving and that automation should provide information on regression bugs that PMs actually care about fixing.
Sign in
to comment
Better than a generic video, see YOUR test, live, ready to show you what matters most: quality at scale.
Explore MoT
Thu, 1 Oct
Previously known as TestBash, MoTaCon is the new name for our annual conference. It's where quality people gather.
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
