celltest

Documentation

Overview

Package celltest provides test utilities for kernel/cell types. It follows the net/http → net/http/httptest pattern.

Auth metadata recording

TestMux implements cell.AuthRouteDeclarer: every auth.Mount call on a TestMux (or on a sub-mux produced by Route) records an cell.AuthRouteMeta in the root TestMux's authMetas slice. Tests that care about auth metadata inspect TestMux.DeclaredAuthMetas directly.

TestMux does NOT enforce Public/Policy semantics — it only records metadata. Tests that must assert 401/403 behavior should use the production Router wired with a fake verifier (runtime/http/router.WithAuthMiddleware) rather than TestMux.

Package celltest provides shared conformance harnesses for kernel/cell contracts. It is a normal package (imports testing) so every layer (cells/ internal, runtime/, adapters/) can hang the same single-source assertions off its own implementations.

Index

• func RunRepoReadinessConformance(t *testing.T, name string, healthy, broken healthz.RepoProber)
• type TestMux
  • func NewTestMux() *TestMux
  • func (m *TestMux) DeclareAuthMeta(meta cell.AuthRouteMeta) error
  • func (m *TestMux) DeclaredAuthMetas() []cell.AuthRouteMeta
  • func (m *TestMux) Group(fn func(cell.RouteMux))
  • func (m *TestMux) Handle(pattern string, handler http.Handler)
  • func (m *TestMux) Mount(pattern string, handler http.Handler)
  • func (m *TestMux) Prefix() string
  • func (m *TestMux) Route(pattern string, fn func(cell.RouteMux))
  • func (m *TestMux) With(_ ...func(http.Handler) http.Handler) cell.RouteMux

Functions

func RunRepoReadinessConformance

func RunRepoReadinessConformance(t *testing.T, name string, healthy, broken healthz.RepoProber)

RunRepoReadinessConformance is the single-source contract for healthz.RepoProber. Every RepoProber implementation MUST be wired through this harness (CELL-REPO-READYZ-PROBE-01 archtest enforces the auto-join). It encodes the *differentiated* property that the typed funnel alone cannot: a SQL-backed RepoReady must FAIL when the cell's own relation(s) are gone, even though a pool-level ping would still pass.

• healthy: must be non-nil (including typed-nil). The harness calls RepoReady(ctx) and asserts it returns nil.
• broken: RepoReady(ctx) != nil. SQL-backed implementations supply this from a real PG with the cell's table(s) dropped (integration tag). In-memory implementations have no differentiated failure domain; pass a literal nil or a nil-valued RepoProber to skip (recorded as a skipped sub-test). SQL-backed implementations MUST pass a non-nil broken prober.

Note: broken is checked with validation.IsNilInterface so both untyped nil and typed-nil interface values (e.g. (*Foo)(nil)) are treated as absent.

Types

type TestMux

type TestMux struct {
	*http.ServeMux
	// contains filtered or unexported fields
}

TestMux adapts http.ServeMux to cell.RouteMux for testing. It uses Go 1.22+ ServeMux pattern matching ("GET /path/{param}").

Route-composition model: sub-muxes created by Route share the root's underlying *http.ServeMux and register every pattern as a fully-qualified path (prefix + sub-relative pattern). This mirrors chi's Route semantics and avoids the stdlib StripPrefix + 307-redirect pitfall where a POST to "/api/v1/access/users" would redirect to "/api/v1/access/users/" and drop its body. All Handle calls on any sub ultimately register an absolute pattern on the root ServeMux.

Auth metadata: every auth.Mount call forwards the declared cell.AuthRouteMeta to the root TestMux via DeclareAuthMeta. Sub-muxes compose the mount prefix before forwarding so the root always sees the full path (e.g. "/api/v1/access/sessions/{id}").

func NewTestMux

func NewTestMux() *TestMux

NewTestMux creates a TestMux backed by a stdlib ServeMux.

func (*TestMux) DeclareAuthMeta

func (m *TestMux) DeclareAuthMeta(meta cell.AuthRouteMeta) error

DeclareAuthMeta records an auth route declaration. Sub-muxes compose their prefix with meta.Path before forwarding to root.

func (*TestMux) DeclaredAuthMetas

func (m *TestMux) DeclaredAuthMetas() []cell.AuthRouteMeta

DeclaredAuthMetas returns a copy of all auth metadata recorded on this root TestMux, in declaration order.

func (*TestMux) Group

func (m *TestMux) Group(fn func(cell.RouteMux))

Group calls fn with the same mux (no prefix change).

func (*TestMux) Handle

func (m *TestMux) Handle(pattern string, handler http.Handler)

Handle registers a handler for the given pattern. For sub-muxes, the configured prefix is composed into the pattern before registration so the root ServeMux sees an absolute path — matching chi's Route + Handle semantics and avoiding stdlib StripPrefix trailing-slash redirects.

For the collection-root case (relative pattern "/"), Handle registers both `prefix` and `prefix+"/"` so the root mux matches the resource regardless of whether the Contract author spelled the path with or without a trailing slash (/api/v1/config vs /api/v1/config/). This mirrors chi's redirect-free behavior.

func (*TestMux) Mount

func (m *TestMux) Mount(pattern string, handler http.Handler)

Mount attaches an http.Handler under the given prefix with stripping.

func (*TestMux) Prefix

func (m *TestMux) Prefix() string

Prefix returns the composed mount prefix for this test mux. Root muxes return ""; sub-muxes created by Route return the same prefix production chiRouterAdapter exposes, allowing auth.Mount to derive chi-relative registration paths from fully-qualified Contract.Path literals.

func (*TestMux) Route

func (m *TestMux) Route(pattern string, fn func(cell.RouteMux))

Route creates a sub-mux that shares the root ServeMux. Patterns registered on the sub are composed into absolute paths via the sub's prefix — no StripPrefix, no trailing-slash redirects.

func (*TestMux) With

func (m *TestMux) With(_ ...func(http.Handler) http.Handler) cell.RouteMux

With returns the same TestMux; stdlib ServeMux has no middleware chain.