contracttest

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

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, ParseWebhook (signature verification and normalization) against recorded payloads, and, for an adapter that reports them, the account's sending IPs.

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

View Source
const (
	ModeOK     = ""
	ModeOutage = "outage" // 5xx or connection errors on every call
	ModeAuth   = "auth"   // credentials rejected on every call
)

Modes the fake API simulates.

View Source
const RejectAddress = "rejected@contract.test"

RejectAddress is a recipient the fake API must reject permanently.

Variables

View Source
var Time = time.Date(2026, 10, 12, 13, 41, 2, 0, time.UTC)

Time is a fixed time for fixtures.

Functions

func CheckText

func CheckText(t *testing.T, what, english string, text i18n.Text)

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.

func Message

func Message(i int) providers.Message

Message returns a test message with the headers the sending pipeline sets.

func Run

func Run(t *testing.T, s Suite)

func UUID

func UUID(t *testing.T, s string) *uuid.UUID

UUID parses s or fails the test.

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

func NewEnv(t *testing.T, api func(env *Env) http.Handler) *Env

NewEnv starts the fake API (when api is not nil) for adapter-specific tests outside Run.

func (*Env) Mode

func (e *Env) Mode() string

Mode returns the simulated failure.

func (*Env) Requests

func (e *Env) Requests() []Recorded

Requests returns the requests received so far.

func (*Env) SetMode

func (e *Env) SetMode(m string)

SetMode sets the simulated failure.

type Recorded

type Recorded struct {
	Method string
	Path   string
	Header http.Header
	Body   []byte
}

Recorded is one request the fake API received.

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)
	// IdempotencyKey reads the idempotency key a recorded send request
	// carries ("" for none). An adapter whose provider recognizes a message
	// it already took (providers.IdempotentSender) must say where it is.
	IdempotencyKey func(r Recorded) string
	// SendingIPs is what an adapter that reports the account's sending IPs
	// (providers.IPReporter) must read from the fake API, in any order.
	SendingIPs *providers.SendingIPs
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL