Verification

Composal Verify runs focused browser journeys against a managed shadow environment or an HTTP(S) environment you already operate. A run is pinned to one code revision, environment revision, scenario-pack digest, release, and impact plan. The planner compares the Change with the paths owned by each journey, so a checkout-only change can select checkout expectations without sweeping unrelated product areas.

Run a verification

Create or register an environment, load the repository’s expectations, then plan a sweep from a Change. Use com verify --help for the complete environment, account, sweep, finding, and evidence command set.

com verify scenarios load \
  --org <organization> \
  --repo <repository> \
  --revision <exact-revision> \
  --idempotency-key expectations:<exact-revision>

The load returns an immutable scenario-pack ID. Give that ID and a ready environment revision to com verify sweeps plan, review the selected and excluded scenarios, then launch the accepted plan. Verify records steps, screenshots, video, console and network summaries, findings, and timing evidence for the run.

New Verify environments retain protected run evidence for 30 days by default. An explicitly configured environment policy can choose a shorter window.

Keep expectations with the product

Expectations as Code means the behavior people rely on is reviewed and versioned beside the code that implements it. Put one journey in each expectations/**/*.test.yaml file. Composal reads the files from an exact repository revision; it never reads whichever files happen to be in a runner’s working directory.

Use plain English for what the user does and what must be true. Also name the code paths that own the journey. Those when-changed patterns are how the planner stays focused.

spec-version: 1
id: amber-cedar-ledger
url: /cart
when-changed:
  - app/checkout/**
  - app/cart/**
expectation: The user can check out and the order total is 10% lower.
steps:
  - click: The "Checkout" button
  - type:
      text: SAVE10
      into: The promo code field
  - act: Apply the promo code
  - assert: The order total is 10% lower

The file name is for people; id is the stable identity used in plans and results. Keep the ID when renaming or moving the file.

Expectation YAML version 1

Every file is one YAML object. Unknown fields are rejected so misspellings cannot silently change a test.

A step contains exactly one of these forms:

• click: <target> clicks a visible control described in plain English.
• type: { text: <value>, into: <target> } enters non-secret test data into a visible field.
• act: <instruction> activates a visible control described in plain English, such as “Apply the promo code.”
• assert: <outcome> adds a visible acceptance check.

Describe what a user sees rather than CSS selectors or coordinates. The top-level expectation is always an acceptance check; assert steps add checks at important points in the journey.

Load an immutable version

Composal discovers only expectations/**/*.test.yaml. It sorts the paths, safely parses YAML without aliases or custom objects, validates every document, and rejects duplicate IDs. A file may be at most 64 KiB; one revision may contain at most 1,000 files and 4 MiB of expectation YAML.

The loaded pack records:

• the exact repository revision;
• the path and digest of every expectation file;
• a digest of the complete sorted set; and
• the compiled, immutable scenarios used by the planner and runners.

Changing a file, moving it, or loading a different revision creates a different version. Existing sweeps retain their original pack, so historical evidence remains explainable even after expectations evolve.

Agents can perform the same operation through the verify_scenarios MCP tool with action: load, source_revision, repository, and a stable idempotency_key. The API accepts the same fields with POST /api/v1/organizations/{organization}/verify/scenario_packs.

Keep data and scope safe

Do not put passwords, tokens, authenticator seeds, personal data, or production-only values in expectation files. Bind login credentials to a Verify persona through Test Accounts; runners receive only the values granted to that persona. Literal type.text values are for synthetic, non-secret test data.

when-changed is selection evidence, not permission to visit an arbitrary service. The selected environment, its admitted URLs, browser policy, credential grants, run budget, and cleanup policy still bound every attempt. An absolute url is usable only when that environment allows it.

Next, use Managed OpenTelemetry to connect scoped metrics and traces to a verification run.