Skip to content
ContractSpec
Start here

Core guide · Operations · 3 min read

Test the promise at the boundary

Choose checks that establish meaningful behavior, including denied effects and real consumer imports.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Give each test one question

An operation has several boundaries, and one green check cannot answer every question about them. Separate declaration validity, business behavior, adapter behavior and external consumption so failures tell you where to look.

For a first integration, keep the matrix small. Choose the success case your tutorial promises and the failure that demonstrates its most important protection.

1 / 4

0 points in your packet

Give each test one question

An operation has several boundaries, and one green check cannot answer every question about them. Separate declaration validity, business behavior, adapter behavior and external consumption so failures tell you where to look.

For a first integration, keep the matrix small. Choose the success case your tutorial promises and the failure that demonstrates its most important protection.

CheckQuestion it answersUseful assertion
Contract/schemaDoes the declared shape behave as intended?Required values accepted or rejected
HandlerDoes the business rule hold?Expected state transition and outcome
RegistryDoes configured execution enforce the boundary?Denied request leaves handler count at zero
TransportDoes the actual API/tool expose it correctly?Wire result and context mapping
ConsumerCan users install and import this version?Clean external project succeeds

Test denied effects explicitly

Use a handler with a visible disposable effect, such as a local counter or fake outbox. Supply otherwise valid input so the request reaches the guard you are testing. Missing approval should leave that effect untouched.

Invoke the adapter used by your users, not only a private helper. For an API-plus-MCP claim, exercise both real entry points and inspect their canonical failure information.

Test the risks of your implementation

A schema can validate input while a handler still produces the wrong state. Add tests for business invariants, resource ownership and the failure paths of any provider you bind. Verify idempotency or retry behavior where your application depends on it.

An invalid output is detected after handler execution. If an effect must be atomic with a record of the result, test the host's transaction or outbox implementation rather than assuming output validation supplies rollback.

Report the scope of the result

Repository tests use the repository's dependency graph. Packed-artifact checks test built tarballs. An anonymous registry consumer verifies that an external user can fetch and execute the published version. Keep these results separate.

For documentation, record the source or package version and exact scenario. A metadata smoke test is useful for an example catalogue, but it should not be described as a successful end-to-end workflow.

Choose the check that answers the question.

One green check cannot establish every boundary. Connect the intended claim with the smallest observation that can support it.

What do you need to establish?

A CLAIM TO EXAMINE

Observe a denied call through the real entry point.

The operation explicitly requires approval, and the request otherwise has valid input.

What it supports

A disposable counter or fake outbox can reveal whether the handler was entered.

What it leaves open

A hidden button or mocked always-allow verifier cannot establish the guard.

What would help you decide

Omit the required receipt, inspect the adapter’s canonical failure and verify the effect remains untouched in your actual test.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.