> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Write expectations that can be checked

> Separate durable workflow identity from an exact saved definition.

A workflow describes a user behavior and the expected result. It is neither a Playwright script nor proof that anyone has tested it.

## Author the saved-view workflow

Under **Example Desk → Views**, create:

| Field | Example |
| - | - |
| Name | Save and reopen a view |
| Behavior | A user saves a filtered view, reloads and reopens it. |
| Expected result | The saved name and filter conditions return, and the matching items are shown. |
| Prerequisites | A dedicated test user can create views; synthetic items include matching and nonmatching cases. |
| Steps | Apply a filter; save the view; reload; reopen it; inspect filters and items. |

Write observable expectations. If filter order does not matter, avoid wording that accidentally requires it. Keep credentials and customer data out of prerequisites and steps.

## Understand the three identities

| Identity | What it means | What changes it |
| - | - | - |
| Workflow ID | The enduring product behavior | A different behavior gets its own workflow |
| Definition ID | An exact immutable saved expectation | A substantive saved expectation edit creates another definition |
| Suite ID | A repository-owned executable suite declaration | Keep stable through test-file or runner moves |

Editing expectations appends history; it does not rewrite earlier definitions. Identical content retains identifiers. The workflow's edit-lock version is distinct from the saved definition sequence. Moving a workflow to another area in the same product preserves its identity, history and direct link; moving across products is not supported.

## Read history before judging old evidence

Open the workflow's saved history to inspect the exact text used earlier. A later expectation change does not retroactively validate an earlier result. Runs should pin the workflow/definition pair; retrieving an unavailable pair must not silently substitute the latest text.

Reference videos are optional illustrations of saved expectations. Replacing or detaching a clip preserves the earlier saved association. See [reference videos](https://docs.bugspray.io/guides/reference-videos.md) for what a clip does and does not demonstrate.

## Give an agent bounded context

Use `list_product_workflows` to search, then `get_product_workflow` for full current expectations. For batch retrieval, `resolve_current_workflows` accepts 1–50 stable IDs within a product and returns summaries; `resolve_workflow_definitions` accepts 1–5 exact pairs and returns saved expectations. Archived, invalid and unavailable references are explicit states. They are not permission to invent substitute expectations.

See the running [MCP contract](https://docs.bugspray.io/reference/mcp.md) for schemas and supported tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.