Documentation
¶
Overview ¶
Package testutil provides a ready-to-use ctrlplane wired against in-memory backends so consumer projects can write tests without standing up a full deployment. Mirrors the shape of authsome's testutil package — same constructor pattern, same option style — so an engineer who's used one already knows the other.
Typical use:
cp := ctrlplanetest.NewServer(t)
tenant := cp.SeedTenant(t, "Acme", "org-acme", "free")
got, err := cp.CP.Admin.GetTenantByExternalID(cp.UserContext("u1"), "org-acme")
Tests that need an HTTP surface (e.g. cross-service e2e) can opt into one via WithHTTPAPI() — currently a no-op placeholder reserved for the iteration that mounts ctrlplane's API onto a forge router.
Index ¶
- Constants
- type ServerOption
- type TestServer
- func (ts *TestServer) AdminContext() context.Context
- func (ts *TestServer) Close()
- func (ts *TestServer) MustGetTenantByExternalID(t *testing.T, externalID string) *admin.Tenant
- func (ts *TestServer) SeedTenant(t *testing.T, name, externalID, plan string) *admin.Tenant
- func (ts *TestServer) SeedTenantWithQuota(t *testing.T, name, externalID, plan string, q admin.Quota) *admin.Tenant
- func (ts *TestServer) UserContext(subjectID string) context.Context
Constants ¶
const SystemAdminRole = "system:admin"
SystemAdminRole is the role string ctrlplane gates IsSystemAdmin on. Exposed so tests don't hard-code the magic string in two places.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ServerOption ¶
type ServerOption func(*serverConfig)
ServerOption configures the test server.
func WithAuthProvider ¶
func WithAuthProvider(p auth.Provider) ServerOption
WithAuthProvider replaces the default NoopProvider. Use when a test needs realistic auth claims to flow through ctrlplane's per-method auth.RequireClaims gate.
For the common case where a test wants to call admin-gated methods directly, prefer the AdminContext helper which injects claims into the request context — that path doesn't require the auth provider to do anything.
func WithHTTPAPI ¶
func WithHTTPAPI() ServerOption
WithHTTPAPI mounts the ctrlplane HTTP API on the test server's httptest.Server. Reserved for cross-service e2e tests; current implementation panics with a clear message until the wiring lands.
Marked as accepted-but-not-yet-implemented so consumer test code can write the call now and have it light up automatically when support arrives, rather than discovering the gap later.
func WithProvider ¶
func WithProvider(name string, p provider.Provider) ServerOption
WithProvider registers an infrastructure provider (Docker, K8s, or a fake). Tests that don't actually exercise instance lifecycle can skip this; ctrlplane will accept the lack of providers and simply reject Instances.Create calls.
type TestServer ¶
type TestServer struct {
CP *app.CtrlPlane
Store *memory.Store
Auth auth.Provider
// Server is non-nil only when the WithHTTPAPI option was passed.
// Reserved for cross-service e2e where studio (or another consumer)
// needs to talk to ctrlplane over HTTP rather than via direct
// method calls.
Server *httptest.Server
}
TestServer wraps a fully-wired ctrlplane backed by in-memory stores. All fields are exposed so tests can poke directly at the underlying services, store, and auth provider when the helpers don't cover a specific assertion.
func NewServer ¶
func NewServer(t *testing.T, opts ...ServerOption) *TestServer
NewServer constructs a CtrlPlane backed by an in-memory store and the in-memory event bus, with sensible defaults so most tests need zero options. A t.Cleanup hook closes the HTTP server when present.
func (*TestServer) AdminContext ¶
func (ts *TestServer) AdminContext() context.Context
AdminContext returns a context carrying ctrlplane Claims with the system-admin role. Tests use this to call admin-gated methods (CreateTenant, ListTenants, SetQuota, etc.) without going through the full Authsome→ctrlplane bridge stack.
The synthetic SubjectID identifies these calls as test-driven in any audit trail the store records.
func (*TestServer) Close ¶
func (ts *TestServer) Close()
Close releases resources. Safe to call multiple times.
func (*TestServer) MustGetTenantByExternalID ¶
MustGetTenantByExternalID is a panic-on-error wrapper around admin.Service.GetTenantByExternalID for tests that have already asserted the tenant exists and want a one-liner.
func (*TestServer) SeedTenant ¶
SeedTenant inserts a tenant directly via the store, bypassing the admin-service auth gate. Returns the inserted tenant for assertion.
externalID may be empty when the test doesn't exercise the org→tenant mapping path. plan defaults to "free" for the same reason — empty is treated as "I don't care".
func (*TestServer) SeedTenantWithQuota ¶
func (ts *TestServer) SeedTenantWithQuota(t *testing.T, name, externalID, plan string, q admin.Quota) *admin.Tenant
SeedTenantWithQuota seeds a tenant and applies a quota in one call. Saves the boilerplate of SeedTenant + ts.CP.Admin.SetQuota when a test needs both side-by-side.
func (*TestServer) UserContext ¶
func (ts *TestServer) UserContext(subjectID string) context.Context
UserContext returns a context carrying vanilla user Claims — authenticated, not admin. For methods that gate on auth.RequireClaims but not IsSystemAdmin (GetTenant, GetTenantByExternalID).
subjectID may be empty; the helper substitutes a stable test value so a missing argument doesn't silently produce empty audit rows.
Source Files