Documentation
¶
Overview ¶
Package contracttest provides a reusable test harness for verifying that platform backends satisfy the behavioral contracts defined by the provider.Provider interface.
Each backend's test suite imports this package and calls Run with a backend-specific Harness. This ensures that list/pagination, error classification, retry behavior, webhook validation, and context cancellation are consistent across every platform the SDK supports.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunLabelsSuite ¶ added in v0.38.0
func RunLabelsSuite(t *testing.T, h LabelsHarness)
RunLabelsSuite executes the label-management contract suite. The mock server routes by HTTP method so platform-specific paths don't matter: GET returns ListResponse, POST returns 201 + MutateResponse, PATCH/PUT return 200 + MutateResponse, DELETE returns 204. The mock also records every request (method, path+query, decoded body) so the subtests can assert the wire behavior behind each operation: pagination parameters on list, the verb and body on create/update/delete, and that update does not clobber fields the caller left nil.
func VersionProxy ¶
VersionProxy returns a test server that responds to /api/v1/version with versionBody and reverse-proxies every other path to baseURL. Gitea/Forgejo SDKs require the version endpoint at client init; this wrapper lets the contract suite target those backends with a plain mock server.
Types ¶
type Harness ¶
type Harness struct {
// Name is the human-readable platform identifier (e.g. "GitHub").
Name string
// Platform is the provider.Platform constant for this backend.
Platform provider.Platform
// NewProvider builds a provider.Provider from the given config. The harness
// fills in BaseURL (and, for the retry subtest, RetryConfig) before calling,
// so the function should forward any supplied RetryConfig/Hooks rather than
// discarding them.
NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
// EmptyListResponse is the JSON body the mock returns for empty lists.
EmptyListResponse string
// NonEmptyListResponse is the JSON body the mock returns for a non-empty
// list, with at least one item that maps to a valid repo.
NonEmptyListResponse string
// Labels, when non-nil, auto-mounts the label-management suite inside
// Run. Run enforces both directions: a platform declaring
// Capabilities().Labels must provide this config, and a config must not
// be provided by a platform that does not declare the capability.
Labels *LabelsHarnessConfig
}
Harness bundles the inputs needed to run the contract suite against a backend.
type LabelsHarness ¶ added in v0.38.0
type LabelsHarness struct {
// Name is the human-readable platform identifier (e.g. "GitHub").
Name string
// Platform is the provider.Platform constant for this backend.
Platform provider.Platform
// NewProvider builds a provider.Provider; the harness fills in BaseURL.
// It must construct the provider the same way the platform's main
// harness does (including any VersionProxy wrapping for Gitea/Forgejo).
NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
// ListResponse is the JSON array the mock returns for GET requests
// (label listings and name→ID resolution lookups). Its first item must
// have name "bug" and color "#4cc917" so the suite can assert color
// normalization.
ListResponse string
// MutateResponse is the JSON object the mock returns for POST/PATCH
// requests. It must have name "bug" and color "#4cc917".
MutateResponse string
// IgnoresListPagination declares that the backend's list endpoint does
// not accept pagination parameters, so the suite skips its wire-level
// page/per-page assertion. Currently only GitCode sets this: its SDK's
// ListIssueLabels exposes no page/page-size parameters, so ListLabels
// silently drops ListLabelsOptions on the wire. That is a known contract
// gap, not something the other five backends share.
IgnoresListPagination bool
}
LabelsHarness bundles the inputs needed to run the label-management contract suite against a backend that implements provider.LabelManager.
type LabelsHarnessConfig ¶ added in v0.38.1
type LabelsHarnessConfig struct {
// ListResponse is the JSON array the mock returns for GET requests. Its
// first item must have name "bug" and color "#4cc917".
ListResponse string
// MutateResponse is the JSON object the mock returns for POST/PATCH/PUT
// requests. It must have name "bug" and color "#4cc917".
MutateResponse string
// IgnoresListPagination opts the backend out of the wire-level
// pagination assertion (see LabelsHarness.IgnoresListPagination).
IgnoresListPagination bool
}
LabelsHarnessConfig carries the fixtures a backend's main Harness needs to auto-mount the label-management suite via Harness.Labels. Name, Platform, and NewProvider are reused from the enclosing Harness.
Source Files