Documentation
¶
Overview ¶
Package conformance provides a differential test harness that replays HTTP scenarios against a Keygen CE-compatible server, records normalised golden transcripts from the live Keygen CE reference, and diffs live runs against them.
Index ¶
- Constants
- func AdminToken(tb testing.TB, target Target) string
- func Diff(a, b string) string
- func Ed25519Key(tb testing.TB, target Target) ed25519.PublicKey
- func Normalise(value any, runSuffix string) any
- func OTPFresh(secretVar, otpVar string) func(testing.TB, map[string]string)
- func OTPVar(secretVar, otpVar string) func(testing.TB, map[string]string)
- func TOTP(tb testing.TB, secretBase32 string) string
- func UserToken(tb testing.TB, target Target, userID string) string
- func WaitForEvent(tb testing.TB, target Target, vars map[string]string, ...)
- type Auth
- type AuthKind
- type HTTPTarget
- type HandlerTarget
- type Scenario
- type Step
- type StepTranscript
- type Target
- type Transcript
Constants ¶
const ( AccountID = "2c1d4f2e-9a3b-4c5d-8e7f-0a1b2c3d4e5f" AccountSlug = "example-com" AdminEmail = "admin@example.com" AdminPass = "adminadmin123" )
The reference deployment and our server are configured with the same single account and admin credentials.
const DefaultReferenceURL = "http://localhost:3900"
DefaultReferenceURL is where the Keygen CE reference server listens.
Variables ¶
This section is empty.
Functions ¶
func AdminToken ¶
AdminToken returns an admin token for the target via password authentication; targets that support it mint one at most once per run.
func Diff ¶
Diff renders a unified diff between the line sequences a and b, or an empty string when they are equal.
func Ed25519Key ¶
Ed25519Key fetches the target account's ed25519 public key from GET /v1/accounts/{id}: the account's meta carries base64-of-hex keys.
func Normalise ¶
Normalise rewrites volatile values in a decoded JSON transcript — UUIDs, token secrets, timestamps, long hex/base64 blobs (license keys, account public keys, signatures), and the run's random name suffix — into stable placeholders numbered by first appearance, so a golden recorded from the reference and a live transcript of our server become comparable. Object key order is irrelevant (maps walk in sorted key order); array order is preserved as-is.
func OTPFresh ¶
OTPFresh is OTPVar for a code the reference has not seen: it waits for the next 30-second step (the reference blocks OTP replays via last_verified_at, and an earlier step of the same scenario may have consumed the current code).
func OTPVar ¶
OTPVar returns a Prepare hook computing the current TOTP code for the secret captured under secretVar into otpVar.
func TOTP ¶
TOTP computes the current 6-digit code for a base32 secret, so scenarios can drive the reference's second-factor flows.
func WaitForEvent ¶
func WaitForEvent( tb testing.TB, target Target, vars map[string]string, idVar, endpointURL, event, marker string, )
WaitForEvent polls the webhook-events index until an event of the given name whose endpoint matches the endpointURL template and whose payload carries the marker template exists, then stores its id in vars[idVar]. The reference creates webhook events in a background worker, so the row can lag the request that produced it; the marker picks this scenario's own event out of the parallel scenarios' traffic.
Types ¶
type Auth ¶
type Auth struct {
Kind AuthKind
Var string // variable name for AuthTokenVar / AuthLicenseVar
BasicUser string
BasicPass string
}
Auth describes how a step authenticates.
type AuthKind ¶
type AuthKind uint8
AuthKind selects the authentication scheme of a step.
const ( // AuthNone sends no credentials; custom headers go via Step.Headers. AuthNone AuthKind = iota // AuthAdmin sends a Bearer admin token minted (and cached) per run. AuthAdmin // AuthTokenVar sends Bearer with a token captured in a variable. AuthTokenVar // AuthLicenseVar sends License with a key captured in a variable. AuthLicenseVar // AuthBasic sends HTTP Basic credentials verbatim. AuthBasic )
type HTTPTarget ¶
type HTTPTarget struct {
BaseURL string
Header http.Header
Client *http.Client
// contains filtered or unexported fields
}
HTTPTarget targets a running server over HTTP, optionally overriding request headers (the reference needs Host and X-Forwarded-Proto).
func NewReferenceTarget ¶
func NewReferenceTarget(baseURL string) *HTTPTarget
NewReferenceTarget returns the Keygen CE reference target: the server routes by Host header and expects TLS to have terminated in front of it.
func NewTarget ¶
func NewTarget(baseURL string) *HTTPTarget
NewTarget returns a target for a bare server URL.
type HandlerTarget ¶
type HandlerTarget struct {
Handler http.Handler
// AdminToken is the raw admin token the test seeded directly in
// the database; the harness authenticates with it without spending
// the password-login throttle budget.
AdminToken string
}
HandlerTarget targets an in-process http.Handler, so the server under test can be exercised without a socket.
type Scenario ¶
Scenario is a named, self-contained sequence of steps: it must create everything it needs and never depend on global resource counts.
type Step ¶
type Step struct {
Name string
Method string
Path string
Auth Auth
Body string // raw JSON body; empty means no body
Headers map[string]string // extra or overriding request headers
Capture map[string]string // variable name -> JSONPath-lite path into the body
// Prepare runs before the step and may compute variables the body or
// headers interpolate (e.g. a TOTP code from a captured secret).
Prepare func(tb testing.TB, vars map[string]string)
// Poll runs before the step and may call the target (admin
// authentication included) until an asynchronous effect exists —
// the reference broadcasts webhook events from a background worker,
// so the event a step shows may lag the action that produced it.
Poll func(tb testing.TB, target Target, vars map[string]string)
}
Step is one HTTP exchange within a scenario. Path, body and header values are {{var}}-interpolated from captures and the built-in "run" suffix.
type StepTranscript ¶
type StepTranscript struct {
Name string `json:"name"`
Status int `json:"status"`
Headers map[string]string `json:"headers"`
Present []string `json:"present,omitempty"`
Body any `json:"body"`
}
StepTranscript records the observable outcome of one step.
type Target ¶
type Target interface {
// NewRequest builds a request for a server-relative path, query included.
NewRequest(ctx context.Context, method string, path string, body io.Reader) (*http.Request, error)
// Do sends the request and returns the unprocessed response.
Do(req *http.Request) (*http.Response, error)
}
Target executes HTTP requests against one Keygen-compatible server. The two implementations cover a live server (reference or ours over HTTP) and, for later in-process boots, a plain http.Handler.
type Transcript ¶
type Transcript struct {
Scenario string `json:"scenario"`
Steps []StepTranscript `json:"steps"`
// Run is the per-run random suffix embedded in generated names. It is
// not part of the golden output but is needed to normalise one.
Run string `json:"-"`
}
Transcript records a whole scenario run.