Test Builder

The Test Builder is an AI-assisted, conversational feature that generates production-ready Playwright tests from natural language descriptions. It respects your existing Page Object Model structure, reuses Custom Actions and Custom Asserts, and asks for clarification rather than guessing.

Key Principles

• Human-readable first — Every generated file is readable and maintainable by a human QA engineer
• Reuse before create — Existing POMs, Actions, and Asserts are detected and extended, never duplicated
• No magic spaghetti — Structured output, no inline locator chaos
• Golden Path over freedom — Consistent, predictable output
• Communication over guessing — AI stops and asks when uncertain

Modes

Auto Mode

Describe the test goal in plain language. The AI observes your app via Playwright MCP, identifies selectors, matches existing POMs and generates spec + POM extension or new file.

Example:

"Erstelle einen Login-Test bis zum Dashboard"

The AI will:

1. Scan your project for existing Page Objects, Actions, Asserts
2. Observe the target URL (up to 5 rounds)
3. Match selectors against preferred locator strategy (test-id → role → label → placeholder → text)
4. Extend existing LoginPage.ts if found, or create a new one
5. Show a Review with: explicitly built / bonus-auto / bonus-recommended / reused artifacts
6. Save on your confirmation

Guided Mode

Lead the AI step by step — useful when Auto mode can't fully observe a dynamic page.

Example chat:

> Navigiere zu /login
> Fülle Email mit testuser@example.com
> Klicke Submit-Button
> Prüfe, dass Dashboard sichtbar ist
> generieren

The AI records each step, then generates the full POM + spec when you say "generieren".

Clarification Rule

If the AI cannot proceed (too few locators, ambiguous intent, unclear POM target), it stops and asks instead of guessing. You will see a highlighted question card in the UI. After your answer, the AI continues.

Maximum clarification rounds: 2. After that, the session stops with a clear error.

Locator Priority

1. data-testid attribute
2. ARIA role (+ accessible name)
3. Label
4. Placeholder
5. Visible text
6. CSS selector (fallback only)

Generated Files

Kind	Example path	When
page	playwright/pages/LoginPage.ts	New POM or extension block
spec	playwright/tests/login.spec.ts	Always
action	playwright/actions/auth.actions.ts	When reusable action detected
assert	playwright/asserts/auth.asserts.ts	When reusable assertion detected

Review Summary

Before saving, the Review panel shows:

• Explizit umgesetzt — what you asked for
• Wiederverwendet — existing files that were reused or extended
• Automatisch hinzugefügt — small, obvious bonus assertions (URL check, visibility)
• Nur empfohlen — additional test ideas not auto-implemented

Limits

Constant	Value	Meaning
MAX_OBSERVE_ROUNDS	5	MCP tool calls before asking
MAX_CLARIFY_ROUNDS	2	User answers before error
MIN_LOCATORS_TO_PROCEED	3	Minimum confident locators needed