---
title: "Turn a QA recipe into an executable agent-qa test"
description: "Adapt a library recipe to your real application, generate a canonical test ID, validate YAML, run the test and inspect UI and external evidence."
canonical_url: "https://vostride.com/agent-library/software-factory/turn-a-recipe-into-an-agent-qa-test.md"
md_url: "https://vostride.com/agent-library/software-factory/turn-a-recipe-into-an-agent-qa-test.md"
content_kind: "guide"
topic: "software-factory"
---

# Turn a QA recipe into an executable agent-qa test

Library recipes are test designs. They specify a risk, fixture state, actions and expected results; they are not ready-made tests for an unknown application. Start with an agent-qa workspace configured through the [agent quickstart](/docs/agent-qa/agent-quickstart.md).

## Resolve the application-specific inputs

Choose the real target name from configuration. Map the recipe's actors, records, screen labels and expected values to test-owned fixtures. Record any external preconditions, such as a prepared payment-provider response, controlled clock or second actor session. A browser instruction cannot create those capabilities merely by describing them.

Separate visible assertions from checks requiring database, API, device or file access. Implement those checks in supported application-specific [hooks](/docs/agent-qa/guides/hooks.md), an existing test harness, or an explicitly recorded manual step. If a required check is unavailable, report the verification gap.

## Scaffold a real test

Run these commands only after the runtime and target are configured. Choose a new file path; the scaffold command does not overwrite an existing test.

```bash
npx agent-qa create-test tests/recipe-check.yaml
```

Retain the generated canonical `test-id`. Set the test's `name`, `target` and `context` using the [test schema](/docs/agent-qa/configuration/test.md). Replace the scaffold's steps with the recipe's adapted visible actions and assertions. This is a steps fragment, not a complete test file:

```yaml
steps:
  - Open the invitation prepared for the test-owned invited account.
  - Verify the invitation names the expected workspace and invited email.
  - Accept the invitation and verify the workspace name in the application header.
  - Open the member list and verify that the invited account appears exactly once with the expected role.
```

Use secret references for credentials, and add actual registered hook IDs when the scenario needs setup or external assertions. Do not copy invented IDs or reuse a browser auth state for a test intended to verify login itself.

## Validate, execute and inspect

```bash
npx agent-qa validate tests/recipe-check.yaml
npx agent-qa run tests/recipe-check.yaml
```

Validation checks definition structure; it does not execute the application. Inspect the completed run, failed steps, screenshots and any external check results. Compare them with every expected result and false-pass trap in the recipe. A success message alone may leave persistence or account identity unverified.

Retain the application revision and original run identifier, then perform the recipe's cleanup on test-owned data. If the test cannot reach a required checkpoint, report it as blocked or incomplete rather than claiming the entire recipe passed.

[Browse the library](/agent-library.md) · [CLI reference](/docs/agent-qa/cli.md)