Automation-Ready Assertion Generation Prompt Template

This prompt is designed for SDETs and automation engineers who need to convert the expected results from a manual test case into a precise, non-flaky, and maintainable set of automation assertions. The core job-to-be-done is translating a human-readable description of correct behavior—often vague or implicit—into an explicit chain of code-level matchers, tolerance ranges, and negative checks that can be directly wired into a test script for frameworks like Playwright, Selenium, or Cypress. The ideal user is someone who understands both the application under test and the pitfalls of UI automation, such as timing issues, dynamic content, and selector brittleness. Required context includes the manual test step, the expected result, the type of UI element involved (e.g., text, input, visibility state), and the target automation framework.

You should not use this prompt when the expected result is fundamentally unverifiable through the UI layer alone, such as a backend state change with no visible side effect. It is also the wrong tool for generating entire test scripts from scratch; it focuses exclusively on the assertion block. Avoid using it for performance or load test assertions, which require statistical analysis over time rather than binary pass/fail checks. If the manual expected result is ambiguous or contains multiple conflicting conditions, resolve that ambiguity through human analysis first. Feeding an unclear expected result into this prompt will produce a brittle assertion chain that is likely to generate false positives or false negatives in CI.

To use this effectively, provide the prompt with a single, well-scoped expected result statement and specify the target assertion library (e.g., Playwright's expect, Chai, Jest). The output should be treated as a first draft that requires human review against the criteria of over-assertion (checking more than necessary), under-assertion (missing a critical condition), and ordering dependencies (assertions that fail if run in the wrong sequence). After generating the assertions, run them against a known-good application state and a deliberately broken state to validate their precision before committing them to your test suite.

This prompt template converts the 'Expected Result' column of a manual test case into a chain of programmatic assertions suitable for Playwright, Selenium, or Cypress. It forces the model to produce explicit matchers, tolerance ranges, and negative assertions rather than vague expect(page).toContain('success') statements. The template is designed to be copied directly into your test generation pipeline, with square-bracket placeholders replaced by your test management system or CI context.

textCopy
You are an SDET converting manual test case expected results into automation-ready assertion chains for [FRAMEWORK, e.g., Playwright, Selenium, Cypress].

## INPUT
Test Case ID: [TEST_CASE_ID]
Test Step Description: [STEP_DESCRIPTION]
Expected Result (manual): [EXPECTED_RESULT]
Application Under Test URL/Context: [APP_CONTEXT]
Known UI Element Selectors: [SELECTOR_MAP, e.g., data-testid attributes or CSS classes]

## CONSTRAINTS
- Produce assertions that are deterministic and not timing-dependent.
- Prefer `data-testid` selectors over CSS classes or XPath when available.
- Include explicit tolerance ranges for any numeric or datetime values.
- Add at least one negative assertion to confirm the absence of error states or stale content.
- Do not use `sleep()` or fixed-time waits. Use framework-native wait strategies tied to specific conditions.
- If the expected result is ambiguous, flag it as [NEEDS_CLARIFICATION] and explain what is missing.

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "test_case_id": "string",
  "assertions": [
    {
      "assertion_id": "string",
      "type": "positive | negative | visual | contract",
      "framework_code": "string (the actual assertion statement)",
      "matcher": "string (e.g., toEqual, toContainText, toHaveCount)",
      "target_selector": "string",
      "expected_value": "string | number | boolean | null",
      "tolerance": "string | null (e.g., '+/- 5%', 'within 2 seconds')",
      "wait_strategy": "string (e.g., 'waitForSelector', 'waitForResponse')",
      "failure_message": "string (custom error message if assertion fails)"
    }
  ],
  "ordering_notes": "string (explain assertion dependency order if any)",
  "clarifications_needed": ["string (list of ambiguous inputs that need human resolution)"]
}

## EXAMPLES
[EXAMPLES: Provide 1-2 few-shot examples of manual expected results and their corresponding assertion chains in the target framework.]

## RISK_LEVEL
[RISK_LEVEL: low | medium | high. If high, add a note that assertions must be reviewed by a senior SDET before merging.]

Generate the assertion chain now.

To adapt this template, replace the square-bracket placeholders with values from your test management system. The [SELECTOR_MAP] is critical: providing known stable selectors prevents the model from inventing brittle CSS paths. The [EXAMPLES] placeholder should contain 1-2 few-shot demonstrations of your team's preferred assertion style and framework conventions. If the [RISK_LEVEL] is high, the output should be routed through a human review step before the assertions are committed to the test repository. After generating the assertions, validate them against the eval criteria in the companion evaluation section of this playbook before integrating them into your CI pipeline.

The Automation-Ready Assertion Generation Prompt Template is designed to be integrated into a test authoring workflow, not used as a one-off chat interaction. In a production harness, this prompt typically sits between a manual test case parser and a script generation engine. The input to the prompt is a structured extraction of the 'Expected Result' field from a test management system (e.g., TestRail, Xray, or Azure DevOps), along with the UI element context and the automation framework target. The output—a JSON array of assertion objects—is then consumed by a downstream script assembler that maps each assertion to framework-specific code (e.g., expect(locator).toHaveText() in Playwright or assertThat(element).containsText() in Selenium). The harness should never directly execute model-generated assertions without validation, as a hallucinated matcher or incorrect selector can silently pass a test or cause a flaky failure that erodes trust in the automation suite.

A robust implementation wraps the LLM call in a validation layer that checks three things before the assertion reaches the script. First, schema conformance: the output must match the expected JSON structure with required fields like assertion_type, matcher, target_value, tolerance, and selector_context. A JSON Schema validator should reject any response missing these fields or containing unknown assertion types. Second, selector existence: if the prompt output references a data-testid or CSS selector, the harness should verify that selector exists in the page object model or a live DOM snapshot before generating code. Third, assertion logic review: for high-risk test areas (e.g., payment flows, authentication, data integrity checks), the harness should route the generated assertions to a human reviewer queue. The review UI should display the original manual expected result, the model's assertion chain, and a diff against any previously approved assertions for the same test case. This review step catches over-assertion (checking ten things when the manual test only specified two) and under-assertion (missing a critical side-effect like a database write or an audit log entry).

For retry and error handling, the harness should implement a two-stage recovery pattern. If the model output fails schema validation, the harness should retry the prompt once with the validation error appended as a [CONSTRAINTS] update, instructing the model to fix the specific structural issue. If the retry also fails, the harness should log the failure, flag the test case for manual assertion authoring, and not block the overall pipeline. For selector verification failures, the harness should invoke a fallback prompt that requests alternative selectors using the same [CONTEXT] block, then re-validate. Model choice matters here: a faster, cheaper model (e.g., Claude Haiku or GPT-4o-mini) is sufficient for straightforward assertions on stable UIs, but complex asynchronous flows or shadow DOM interactions benefit from a more capable model with stronger instruction-following. The harness should log every assertion generation attempt—including the prompt version, model, input context, raw output, validation result, and reviewer decision—so that assertion quality trends can be analyzed over time and flaky assertion patterns can be traced back to specific prompt behaviors.