conformance

package
v0.0.18 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 25 Imported by: 0

README

Conformance suite

Differential tests: scenarios run against a live Keygen CE reference server and against a running backplane-lic; normalised transcripts must match.

  • make conformance-record — run the scenarios against the reference (LIC_CONFORMANCE_REFERENCE, default http://localhost:3900) and write testdata/<scenario>.golden.json.
  • make conformance — run the scenarios against our server (LIC_CONFORMANCE_TARGET, e.g. http://localhost:8080) and diff every step against its golden. Skips when the variable is unset.

Each scenario is a self-contained list of steps (scenarios_test.go): method, path, auth (none / admin token / token or license from a captured var / basic), JSON body and headers — all {{var}}-interpolated — plus captures (data.id style paths). Embed the built-in {{run}} suffix in generated names/fingerprints/emails; the normaliser masks it, UUIDs, token secrets, timestamps and long hex/base64 blobs, keeping statuses, selected headers, error codes and all other values byte-comparable. Response signatures are verified with the account's ed25519 key fetched from GET /v1/accounts/{id}.

To add a scenario: append one to scenarios() in scenarios_test.go (create whatever it needs, never rely on global counts), then make conformance-record and check the new golden into git.

The harness lives in harness.go (Target interface; HandlerTarget wraps an in-process http.Handler for socketless boots), normalise.go, signature.go and diff.go.

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

View Source
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.

View Source
const DefaultReferenceURL = "http://localhost:3900"

DefaultReferenceURL is where the Keygen CE reference server listens.

Variables

This section is empty.

Functions

func AdminToken

func AdminToken(tb testing.TB, target Target) string

AdminToken returns an admin token for the target via password authentication; targets that support it mint one at most once per run.

func Diff

func Diff(a, b string) string

Diff renders a unified diff between the line sequences a and b, or an empty string when they are equal.

func Ed25519Key

func Ed25519Key(tb testing.TB, target Target) ed25519.PublicKey

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

func Normalise(value any, runSuffix string) any

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

func OTPFresh(secretVar, otpVar string) func(testing.TB, map[string]string)

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

func OTPVar(secretVar, otpVar string) func(testing.TB, map[string]string)

OTPVar returns a Prepare hook computing the current TOTP code for the secret captured under secretVar into otpVar.

func TOTP

func TOTP(tb testing.TB, secretBase32 string) string

TOTP computes the current 6-digit code for a base32 secret, so scenarios can drive the reference's second-factor flows.

func UserToken

func UserToken(tb testing.TB, target Target, userID string) string

UserToken mints a user-bearer fixture through the real API on both servers.

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.

func (*HTTPTarget) Do

func (tgt *HTTPTarget) Do(req *http.Request) (*http.Response, error)

Do implements Target.

func (*HTTPTarget) NewRequest

func (tgt *HTTPTarget) NewRequest(
	ctx context.Context,
	method string,
	path string,
	body io.Reader,
) (*http.Request, error)

NewRequest implements Target.

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.

func (*HandlerTarget) Do

func (h *HandlerTarget) Do(req *http.Request) (*http.Response, error)

Do implements Target.

func (*HandlerTarget) NewRequest

func (h *HandlerTarget) NewRequest(
	ctx context.Context,
	method string,
	path string,
	body io.Reader,
) (*http.Request, error)

NewRequest implements Target.

type Scenario

type Scenario struct {
	Name  string
	Steps []Step
}

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.

func Run

func Run(tb testing.TB, target Target, scenario Scenario, signer ed25519.PublicKey) Transcript

Run executes the scenario's steps sequentially against target and returns the transcript. When signer is non-nil, every response carrying a Keygen-Signature header is verified with it.

Jump to

Keyboard shortcuts

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