Writing Good Specs

Writing Good Specs

How to write markdown the parser (and LLM) can turn into solid Playwright tests.

Deep: test-authoring.md · example prompts/examples/vm-create.md.

Structure that works

# Feature title

Short context paragraph (optional).

## Acceptance Criteria

1. Navigate to `/products`
2. Page shows heading `Products`
3. Click "Schedule Demo"
4. URL contains `/demo`

Rule-based parser (no LLM) needs

• A # Title heading
• A ## Acceptance Criteria section with bullets/numbers
• Concrete paths, button labels, and visible text

Vague criteria → template fallback that only hits / — Troubleshooting.

Phrasing tips

Good	Weak
Navigate to /gpu-passthrough	User opens the GPU page
Page shows heading GPU Passthrough	Content looks right
Click "Sign in"	Authenticate
URL contains /dashboard	Lands somewhere useful

Natural language (zyvor-qa create)

Same idea in one sentence — include route + exact UI text:

zyvor-qa create "Open /guestkit and assert heading Offline VM intelligence" --execute

After generate

cat tests/fixtures/requirements.json   # did the parser understand?
ls tests/generated/
# Promote keepers → tests/manual/

GitHub issues as specs

Label qa / user-story / feature-spec / enhancement and put AC in the issue body — GitHub Integration.

Related: Spec to Test · Natural Language Tests · Test Authoring