contracttest

Documentation

Overview

Package contracttest provides schema-driven contract validation helpers for use in contract_test.go files across GoCell cells.

It loads contract.yaml files, compiles referenced JSON Schemas, and validates JSON payloads against them. This replaces the previous t.Skip stubs with real schema enforcement.

Usage:

func TestHttpAuthUserCreateV1Serve(t *testing.T) {
    c := contracttest.LoadByID(t, contracttest.ContractsRoot(t), "http.auth.user.create.v1")
    c.ValidateRequest(t, []byte(`{"username":"alice","email":"a@b.com","password":"s"}`))
    c.ValidateResponse(t, []byte(`{"data":{"id":"u-1","username":"alice",...}}`))
    c.MustRejectRequest(t, []byte(`{"extra":"field"}`))
}

Index

• func ContractsRoot(t testing.TB) string
• func ExampleContractsRoot(t testing.TB, example string) string
• type Contract
  • func Load(t testing.TB, contractDir string) *Contract
  • func LoadByID(t testing.TB, contractsRoot string, contractID string) *Contract
  • func LoadFromString(t testing.TB, contractID, requestSchema, responseSchema string) *Contract
  • func (c *Contract) MustRejectHeaders(t testing.TB, jsonData []byte)
  • func (c *Contract) MustRejectPayload(t testing.TB, jsonData []byte)
  • func (c *Contract) MustRejectRequest(t testing.TB, jsonData []byte)
  • func (c *Contract) MustRejectResponse(t testing.TB, jsonData []byte)
  • func (c *Contract) ValidateErrorResponse(t testing.TB, status int, body []byte)
  • func (c *Contract) ValidateHTTPResponseRecorder(t testing.TB, recorder *httptest.ResponseRecorder)
  • func (c *Contract) ValidateHeaders(t testing.TB, jsonData []byte)
  • func (c *Contract) ValidatePayload(t testing.TB, jsonData []byte)
  • func (c *Contract) ValidateRequest(t testing.TB, jsonData []byte)
  • func (c *Contract) ValidateResponse(t testing.TB, jsonData []byte)
  • func (c *Contract) ValidateSchemaRef(t testing.TB, key string, jsonData []byte)
• type HTTPResponseEntry
• type HTTPTransport

Functions

func ContractsRoot

func ContractsRoot(t testing.TB) string

ContractsRoot returns the absolute path to the contracts/ directory, derived from the source location of this package.

func ExampleContractsRoot

func ExampleContractsRoot(t testing.TB, example string) string

ExampleContractsRoot returns the absolute path to an example's contracts/ directory. The example name is the directory under examples/.

Types

type Contract

type Contract struct {
	ID               string
	Kind             string
	OwnerCell        string
	ConsistencyLevel string
	Dir              string // absolute path to the contract version directory
	HTTP             *HTTPTransport
	// contains filtered or unexported fields
}

Contract holds a loaded contract with compiled JSON schemas.

func Load

func Load(t testing.TB, contractDir string) *Contract

Load reads contract.yaml from contractDir, compiles all referenced JSON Schemas, and returns a Contract ready for validation. It calls t.Fatal on any setup error.

func LoadByID

func LoadByID(t testing.TB, contractsRoot string, contractID string) *Contract

LoadByID resolves a contract ID to its directory path and loads it. The ID "http.auth.user.create.v1" is converted to the path contractsRoot/http/auth/user/create/v1/.

func LoadFromString

func LoadFromString(t testing.TB, contractID, requestSchema, responseSchema string) *Contract

LoadFromString builds a Contract from inline JSON schema strings, bypassing the fixture filesystem. Useful for unit tests that want to assert schema behavior without creating testdata files. Empty schema strings produce a nil schema (the corresponding Validate* call becomes a no-op).

func (*Contract) MustRejectHeaders

func (c *Contract) MustRejectHeaders(t testing.TB, jsonData []byte)

MustRejectHeaders asserts that jsonData is rejected by the headers schema.

Note: per ADR-202605031600, event headers schemas are lenient by default. See MustRejectResponse for the full lenient-schema caveat.

func (*Contract) MustRejectPayload

func (c *Contract) MustRejectPayload(t testing.TB, jsonData []byte)

MustRejectPayload asserts that jsonData is rejected by the payload schema.

Note: per ADR-202605031600, event payload schemas are lenient by default; metadata-only payloads add `unevaluatedProperties: false` to forbid extra fields. See MustRejectResponse for the full lenient-schema caveat.

func (*Contract) MustRejectRequest

func (c *Contract) MustRejectRequest(t testing.TB, jsonData []byte)

MustRejectRequest asserts that jsonData is rejected by the request schema. This proves the schema is not trivially permissive.

Rejection sources: missing `required` fields, type/pattern/enum mismatch, or extra fields under `additionalProperties: false` / `unevaluatedProperties: false`. Request schemas are strict (FMT-20), so extra fields are rejected.

func (*Contract) MustRejectResponse

func (c *Contract) MustRejectResponse(t testing.TB, jsonData []byte)

MustRejectResponse asserts that jsonData is rejected by the response schema.

Note: per ADR-202605031600, response schemas are lenient by default — extra fields are accepted unless the schema explicitly declares `additionalProperties: false` or `unevaluatedProperties: false`. To prove extra-field rejection, the schema must declare a closed-shape constraint (typical for error envelopes and metadata-only payloads). For lenient response schemas, MustRejectResponse only catches missing required fields, type/pattern/enum mismatch, and similar non-additive violations.

func (*Contract) ValidateErrorResponse

func (c *Contract) ValidateErrorResponse(t testing.TB, status int, body []byte)

ValidateErrorResponse validates body against the JSON Schema declared for the given HTTP status code in the contract's endpoints.http.responses map. It calls t.Errorf if:

• the contract has no endpoints.http metadata
• no response entry is declared for status
• body fails schema validation

func (*Contract) ValidateHTTPResponseRecorder

func (c *Contract) ValidateHTTPResponseRecorder(t testing.TB, recorder *httptest.ResponseRecorder)

ValidateHTTPResponseRecorder validates an HTTP provider response against the migrated transport metadata and, when applicable, the response schema.

func (*Contract) ValidateHeaders

func (c *Contract) ValidateHeaders(t testing.TB, jsonData []byte)

ValidateHeaders validates jsonData against the headers schema.

func (*Contract) ValidatePayload

func (c *Contract) ValidatePayload(t testing.TB, jsonData []byte)

ValidatePayload validates jsonData against the payload schema.

func (*Contract) ValidateRequest

func (c *Contract) ValidateRequest(t testing.TB, jsonData []byte)

ValidateRequest validates jsonData against the request schema. No-op if the contract has no request schema.

func (*Contract) ValidateResponse

func (c *Contract) ValidateResponse(t testing.TB, jsonData []byte)

ValidateResponse validates jsonData against the response schema.

func (*Contract) ValidateSchemaRef

func (c *Contract) ValidateSchemaRef(t testing.TB, key string, jsonData []byte)

ValidateSchemaRef validates jsonData against the schema referenced by the given key name. This covers both well-known refs (request, response, payload, headers) and extra refs declared in schemaRefs. Unknown keys fail the test so schemaRef typos cannot pass silently.

type HTTPResponseEntry

type HTTPResponseEntry = metadata.HTTPResponseMeta

HTTPResponseEntry describes a declared error response for a specific HTTP status code. It is an alias of metadata.HTTPResponseMeta to preserve the public API.

type HTTPTransport

type HTTPTransport = metadata.HTTPTransportMeta

HTTPTransport holds optional transport metadata for migrated HTTP contracts. It is an alias of metadata.HTTPTransportMeta to preserve the public API.