> ## 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.

# Connect expectations to test suites

> Declare intended coverage without turning declarations into test results.

A suite is a repository-owned unit of executable testing. Bugspray imports declarations from a committed manifest into an immutable inventory for an exact candidate commit.

For Example Desk, a `saved-view-roundtrip` suite might intend to check “Save and reopen a view.” A separate navigation suite might also reference that workflow. One suite can cover several workflows and several suites can reference one workflow.

```mermaid theme={null}
flowchart LR
  W[Stable workflow ID] --> D[Exact saved definition]
  S[Repository suite ID] --> W
  M[Candidate manifest] --> S
  P[Exact PR plan] --> M
  P --> D
  R[CI receipt] --> P
  R --> E[Verified environment identity]
```

## Read the inventory correctly

The manifest carries stable suite IDs, names, intent, workflow IDs, GitHub Actions locators and fixture/environment requirements. It carries **no authorized shell commands**. Trusted CI owns commands, smoke membership, dependencies, fallback and execution policy.

Registration does not verify that a test exists at its locator, that declared coverage is complete or that a test passed. The inventory resolves current catalog summaries and keeps archived/missing references visible. Historical runs must record exact definition IDs separately.

## Inspect a candidate

Open **Test suites** (`/suite-inventory`) and select a recorded candidate. Inspect the complete commit, manifest path and digest before reading suite details. Refresh checks status and live PR-head freshness; it does not run tests or import missing data.

`ready`, `missing`, `invalid`, `provider_unavailable` and `superseded` describe import state. Freshness can be `current`, `superseded` or `unverified`. Missing configuration or an absent event can leave a candidate pending; an empty inventory is not adequate validation.

## Keep identities stable

Keep a suite ID when its file or job moves. Never reuse a retired ID for a different suite. Changing manifest bytes, path or candidate creates a distinct snapshot. Old inventory remains tied to its original exact binding.

[Register a manifest](https://docs.bugspray.io/guides/register-suites.md), then read how [PR plans and evidence](https://docs.bugspray.io/guides/pr-validation.md) use it.


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