Documentation
¶
Overview ¶
Package contracttest is the shared test suite every sending-provider adapter must pass (TECH_STACK note 10): registration and capabilities, the texts people read about the adapter (in every app language), Send (success, permanent rejection, outage, rejected credentials) against a fake of the provider's API, and ParseWebhook (signature verification and normalization) against recorded payloads.
An adapter's test calls Run with a Suite:
func TestContract(t *testing.T) {
contracttest.Run(t, contracttest.Suite{Adapter: "postmark", API: fakeAPI, New: newForTest, Webhooks: cases})
}
The fake API reads Env.Mode ("", ModeOutage, ModeAuth) and the recipient address (RejectAddress) to choose its answer, and the suite records every request it receives.
Index ¶
- Constants
- Variables
- func CheckText(t *testing.T, what, english string, text i18n.Text)
- func CheckTexts(t *testing.T, d providers.Descriptor)
- func Message(i int) providers.Message
- func Run(t *testing.T, s Suite)
- func UUID(t *testing.T, s string) *uuid.UUID
- type Env
- type Recorded
- type Suite
- type Webhook
Constants ¶
const ( ModeOK = "" ModeOutage = "outage" // 5xx or connection errors on every call ModeAuth = "auth" // credentials rejected on every call )
Modes the fake API simulates.
const RejectAddress = "rejected@contract.test"
RejectAddress is a recipient the fake API must reject permanently.
Variables ¶
var Time = time.Date(2026, 10, 12, 13, 41, 2, 0, time.UTC)
Time is a fixed time for fixtures.
Functions ¶
func CheckText ¶
CheckText checks one text an adapter returned with its message (an account standing, a tracking detail, a provisioning row): the message must exist and say what the English says.
func CheckTexts ¶
func CheckTexts(t *testing.T, d providers.Descriptor)
CheckTexts checks the texts of a descriptor (docs/adapters.md, "Text for people"): each message must say what the English it was kept with says, and a built-in adapter of a kind the catalog shows (api, smtp, self_hosted, http) names its catalog, gives every text a message from it and has the catalog translated into every app language. A community adapter's texts are English; the messages ReputeCast adds to them are checked the same way.
Types ¶
type Env ¶
type Env struct {
// URL is the fake API's base URL (empty when the suite has no API).
URL string
// contains filtered or unexported fields
}
Env is shared between the suite and the fake API.
func NewEnv ¶
NewEnv starts the fake API (when api is not nil) for adapter-specific tests outside Run.
type Suite ¶
type Suite struct {
Adapter string
// API is the fake provider API; nil when the adapter doesn't use HTTP (SMTP).
API func(env *Env) http.Handler
// New builds the adapter pointed at env (env.URL is the fake API).
New func(t *testing.T, env *Env) providers.Provider
// SendReady reports whether Send can be exercised (for example Mailpit
// is running); a false result skips the Send tests with the reason.
SendReady func(t *testing.T) (bool, string)
// Delivered checks that the messages reached the provider with their
// headers; it gets the messages sent and the requests recorded.
Delivered func(t *testing.T, env *Env, msgs []providers.Message, results []providers.SendResult)
// SkipFailureModes skips the outage/auth send tests (SMTP against Mailpit
// can't simulate them; its dial errors are tested separately).
SkipFailureModes bool
Webhooks []Webhook
// Tamper breaks a valid signed request; the default flips a body byte.
Tamper func(r *http.Request, body []byte) (*http.Request, []byte)
}
Suite describes one adapter.
type Webhook ¶
type Webhook struct {
Name string
// Request returns a correctly signed request and its body.
Request func(t *testing.T, env *Env) (*http.Request, []byte)
// Want are the expected events (compared on type, recipient, provider
// message id, message id, original type and code, bounce class).
Want []providers.Event
}
Webhook is one recorded provider event.