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 (c *Contract) MustRejectHeaders(t testing.TB, jsonData []byte)
- func (c *Contract) MustRejectPathParam(t testing.TB, name, value string)
- func (c *Contract) MustRejectPayload(t testing.TB, jsonData []byte)
- func (c *Contract) MustRejectQueryParam(t testing.TB, name, value string)
- 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) ValidatePathParam(t testing.TB, name, value string)
- func (c *Contract) ValidatePayload(t testing.TB, jsonData []byte)
- func (c *Contract) ValidateQueryParam(t testing.TB, name, value string)
- 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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContractsRoot ¶
ContractsRoot returns the absolute path to the contracts/ directory, derived from the source location of this package.
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 ¶
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 ¶
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 ¶
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 ¶
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) MustRejectPathParam ¶
MustRejectPathParam asserts that value is rejected by the path param schema for name. Calls t.Errorf if name is not declared in pathParams or value is accepted by schema.
See paramValueToJSON for the value-to-JSON conversion semantics.
func (*Contract) MustRejectPayload ¶
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) MustRejectQueryParam ¶
MustRejectQueryParam asserts that value is rejected by the query param schema for name. Calls t.Errorf if name is not declared in queryParams or value is accepted by schema.
See paramValueToJSON for the value-to-JSON conversion semantics.
func (*Contract) MustRejectRequest ¶
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 ¶
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 ¶
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 ¶
ValidateHeaders validates jsonData against the headers schema.
func (*Contract) ValidatePathParam ¶
ValidatePathParam validates value against the path param schema for name. Calls t.Errorf if name is not declared in pathParams or value violates schema.
See paramValueToJSON for the value-to-JSON conversion semantics.
func (*Contract) ValidatePayload ¶
ValidatePayload validates jsonData against the payload schema.
func (*Contract) ValidateQueryParam ¶
ValidateQueryParam validates value against the query param schema for name. Calls t.Errorf if name is not declared in queryParams or value violates schema.
See paramValueToJSON for the value-to-JSON conversion semantics.
func (*Contract) ValidateRequest ¶
ValidateRequest validates jsonData against the request schema. No-op if the contract has no request schema.
func (*Contract) ValidateResponse ¶
ValidateResponse validates jsonData against the response schema.
func (*Contract) ValidateSchemaRef ¶
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
fixtureload
Package fixtureload encapsulates contract schema/fixture file reads.
|
Package fixtureload encapsulates contract schema/fixture file reads. |