conformance

Documentation

Overview

Package conformance turns docs/plans/inert-tier-rollout.md §3 (the inert contract) into executable, table-driven tests.

It is a library, not a test suite about itself: a future generated (or hand-wired) Tier 1 service imports this package, builds a Fixture that describes how to reach its operations at the wire level, and calls Run (or Check, for finer control) to assert the service satisfies §3.

Design

Check runs the whole contract against a Fixture and returns every violated clause as a Violation carrying a clause id tied to the plan section (e.g. "3.2/roundtrip-fidelity"). Run is the thin testing.T wrapper services call directly. Splitting the two means the "does the suite actually detect anything?" question — the naive stub in this package plus TestNaiveStub_ViolatesExpectedClauses in meta_test.go — can be answered honestly with Check, no fake *testing.T required.

A Fixture operates at the wire level: Encode turns a logical field map into a real *http.Request in the fixture's protocol (JSON body, form body, headers, target/action), and Decode turns the real HTTP response back into a logical field map (or a WireError). Encode/Decode are the only protocol-specific parts of a Fixture; everything Check asserts operates on the resulting map[string]any, so the same clause logic exercises every protocol family a Fixture is written for.

Index

• func Run(t *testing.T, f Fixture)
• type Class
  • func (c Class) String() string
• type ErrorCodes
• type Fixture
  • func NewNaiveJSONFixture() Fixture
  • func NewNaiveQueryFixture() Fixture
• type InputKind
• type ResourceOps
• type Violation
  • func Check(f Fixture) []Violation
  • func (v Violation) String() string
• type WireError

Functions

func Run

func Run(t *testing.T, f Fixture)

Run executes the whole §3 contract against f and fails t with one t.Errorf per violated clause. This is the entry point a real service's test calls; Check is what this package's own meta-test (and anything wanting the raw violation list) calls instead.

Types

type Class

type Class int

Class is an operation's §3.1 lifecycle classification.

const (
	ClassCreate Class = iota
	ClassRead
	ClassUpdate
	ClassDelete
	ClassList
	ClassVerb
)

func (Class) String

func (c Class) String() string

type ErrorCodes

type ErrorCodes struct {
	NotFound, AlreadyExists, InvalidParameter, InvalidToken                         string
	NotFoundStatus, AlreadyExistsStatus, InvalidParameterStatus, InvalidTokenStatus int
}

ErrorCodes are the modeled error code/HTTP-status pairs a Fixture's service declares for the four §3.3 error classes.

type Fixture

type Fixture struct {
	// Service is the service key (e.g. "organizations"), used by
	// §3.5/arn's ARN template check.
	Service string
	// Codec is the protocol family this Fixture exercises. Used for
	// diagnostics; Encode/Decode do the actual wire work.
	Codec codec.Codec
	// Handler dispatches a request the way the router would — a real
	// service Handler, or (for the naive stub) a synthetic one exercising
	// the same op.Typed / codec machinery real services use.
	Handler http.Handler
	// Resource names this Fixture's operations and field bindings.
	Resource ResourceOps
	// Errors are the modeled error codes this Fixture's service declares.
	Errors ErrorCodes
	// Input builds a logical field map for one InputKind/seed pair. seed
	// varies the identifying fields across calls so checks can create
	// multiple independent records.
	Input func(kind InputKind, seed int) map[string]any
	// Reset clears all state between checks so each one runs against a
	// clean store, independent of the others.
	Reset func()
	// Clock is the fixture's injectable time source (§3.5). May be nil for
	// a Fixture that skips the timestamp check (Resource.CreationTimeField
	// left empty has the same effect).
	Clock *clock.Mock
	// Encode turns a logical field map into a real, protocol-correct
	// *http.Request for op (an AWS operation name).
	Encode func(op string, fields map[string]any) *http.Request
	// Decode turns a real *http.Response back into a logical field map, or
	// a WireError when the response is an error envelope.
	Decode func(resp *http.Response) (fields map[string]any, wireErr *WireError)
}

Fixture describes one (service, protocol) pair under test at the wire level. One Fixture exercises one Codec; a service with more than one supported protocol family gets one Fixture per family.

func NewNaiveJSONFixture

func NewNaiveJSONFixture() Fixture

NewNaiveJSONFixture builds the naive stub Fixture for AWS JSON 1.1 — one of the two protocol families the meta-test (meta_test.go) exercises Check against. See naive_stub.go for what the stub gets right and wrong.

func NewNaiveQueryFixture

func NewNaiveQueryFixture() Fixture

NewNaiveQueryFixture builds the naive stub Fixture for the AWS Query protocol (form-encoded request, XML response) — the second protocol family the meta-test exercises Check against, alongside JSON 1.1. Same business logic (naiveLogic) and the same bugs as naive_json.go; only the wire encoding differs, which is exactly the point — the clause ids and the set the naive stub violates must not depend on protocol family.

type InputKind

type InputKind int

InputKind selects which shape Fixture.Input should build. A single resource's Input function switches on Kind so one Fixture can drive every clause without a pile of one-off request builders.

const (
	// InputFull is a Create input carrying every field ResourceOps.RoundtripFields
	// names, used by the fidelity and update-merge checks.
	InputFull InputKind = iota
	// InputMinimal is a Create input carrying only the resource's required
	// fields — no optional fields, so ResourceOps.OutputOnlyFields must come
	// back absent or at their modeled default (§3.2/no-fabrication).
	InputMinimal
	// InputInvalid is a Create input missing a required field, used by
	// §3.3/invalid-parameter.
	InputInvalid
	// InputUpdate is an Update input naming an existing record (via
	// ResourceOps.IDField) plus a small patch of fields to merge, used by
	// §3.1/update-merge.
	InputUpdate
	// InputIdempotent is a Create input that omits ResourceOps.IDField (so
	// the service must derive the identifier itself) and sets
	// ResourceOps.IdempotencyField to a fixed value, used by §3.5/idempotency.
	InputIdempotent
)

type ResourceOps

type ResourceOps struct {
	// Create, Read, Update, Delete, List are the AWS operation names for
	// this resource's CRUD surface, dispatched through Fixture.Encode/Handler.
	Create, Read, Update, Delete, List string

	// Verb, if set, is a plain (non-CRUD) operation name expected to stay
	// Tier 0 — checked by §3.6/verb-default.
	Verb string

	// IDField is the field name — present in both Create/Update inputs and
	// every output — that addresses one record for Read/Update/Delete.
	IDField string
	// ArnField is the output field name carrying the resource's ARN.
	ArnField string
	// CreationTimeField and ModifiedTimeField are the output field names
	// carrying the two §3.5 timestamps. ModifiedTimeField may be empty for
	// a resource with no LastModifiedTime member.
	CreationTimeField string
	ModifiedTimeField string
	// RoundtripFields are every optional field a Create caller may send
	// that the output shape also carries — §3.2/roundtrip-fidelity asserts
	// each one comes back equal to what was sent.
	RoundtripFields []string
	// OutputOnlyFields are fields the caller never sends (derived / status
	// fields) — §3.2/no-fabrication asserts each one is either absent from
	// a minimal record's output or equal to Defaults[field].
	OutputOnlyFields []string
	// Defaults maps an OutputOnlyFields entry to its modeled default value,
	// when one is declared. A field with no entry here must be absent when
	// unset.
	Defaults map[string]any

	// ItemsField is the List response field holding the array of records.
	ItemsField string
	// TokenRequestField / TokenResponseField are the pagination
	// continuation-token member names on the List request and response
	// respectively (may differ, e.g. Marker vs NextMarker).
	TokenRequestField, TokenResponseField string
	// LimitField is the List request field capping page size (MaxResults,
	// PageSize, Limit, ...).
	LimitField string

	// IdempotencyField is the Create request field (ClientToken,
	// CallerReference, ...) checked by §3.5/idempotency. Empty means the
	// resource models no such field and the check is skipped.
	IdempotencyField string
}

ResourceOps names the operations and field bindings of one resource under test, in the vocabulary op.Typed / the generator's inert.Binding will eventually use (§4.3).

type Violation

type Violation struct {
	// Clause is a stable id of the form "<section>/<name>", e.g.
	// "3.2/roundtrip-fidelity", tied to the plan section that states the
	// rule. Never invent a clause id outside the set the check functions in
	// check.go emit — that stability is what lets a failure message name
	// the exact contract it broke.
	Clause string
	// Message explains what was observed, in enough detail to fix without
	// re-reading the check's source.
	Message string
}

Violation is one broken clause of docs/plans/inert-tier-rollout.md §3.

func Check

func Check(f Fixture) []Violation

Check runs the whole §3 contract against f and returns every violated clause. A Fixture that fully satisfies §3 returns nil.

func (Violation) String

func (v Violation) String() string

type WireError

type WireError struct {
	Code       string
	HTTPStatus int
}

WireError is a protocol-agnostic view of an error response, produced by Fixture.Decode. It intentionally carries only what §3.3 asserts on: the AWS error code and the HTTP status.