Documentation
¶
Overview ¶
Package nucleustest boots a nucleus application inside the test process (DX-22). Before it existed, every E2E suite re-invented the same scaffolding — `go build`, exec.Command, /healthz polling, duplicated start helpers — because Start() blocks and exposes no programmatic shutdown. The kit reduces that to one call:
func TestMyAPI(t *testing.T) {
srv := nucleustest.Start(t, nucleus.New().
FromConfigFile("testdata/nucleus.yml").
Mount(notes.Module()))
resp, err := srv.Client().Get(srv.URL("/notes"))
...
}
Start assigns a free loopback port, runs the full framework startup sequence (nucleus.RunContext) in a goroutine, waits for /healthz, and registers a t.Cleanup that shuts the application down gracefully and fails the test if the run returned an unexpected error. MintToken issues bearer tokens against the application's own jwt_secret for exercising protected routes.
runtime.go delivers the growth the package contract anticipated ("per-test databases, fixture loading"): access to the running application's managed resources, a per-test SQLite database, and applying the project's SQL migrations — closing the gap where a test could POST through the kit but had no way to assert against the database behind it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func TempSQLite ¶
func TempSQLite(tb testing.TB) map[string]app.DatabaseConfig
TempSQLite returns a Databases map whose default alias is a fresh SQLite file in a per-test temporary directory — the per-test database: every test gets its own isolated file, removed with the test's temp dir.
A file, deliberately not ":memory:": the framework pools connections and every pooled connection to ":memory:" opens its own empty database.
Types ¶
type Server ¶
type Server struct {
// BaseURL is the loopback origin the application listens on, e.g.
// "http://127.0.0.1:49521".
BaseURL string
// contains filtered or unexported fields
}
Server is a nucleus application running in-process for the duration of a test. Construct it with Start or StartApp; it stops automatically via t.Cleanup (or earlier, with an explicit Stop).
func Start ¶
func Start(tb testing.TB, b *nucleus.AppBuilder) *Server
Start builds the application from the builder and boots it in-process. The builder's configured port is replaced with a free loopback port so parallel tests never collide. Fails the test on any build or boot error.
func StartApp ¶
StartApp boots an already-constructed nucleus.App in-process. The direct-struct counterpart of Start.
func (*Server) DB ¶
DB returns the application's managed *sql.DB (the default alias) so a test can assert against the database behind the HTTP surface. Fails the test when no database is configured.
func (*Server) MigrateDir ¶
MigrateDir applies the project's SQL migrations (the .up.sql/.down.sql pairs `nucleus migrate up` runs) from dir against the application's default database, through the same Migrator — ledger and checksums included. Call it right after Start to give the test schema the exact shape production gets:
srv := nucleustest.Start(t, builder)
srv.MigrateDir("../../migrations")
Fails the test on any migration error.
func (*Server) MintToken ¶
MintToken issues a bearer token signed with the application's configured jwt_secret — the same material the framework's JWT middleware validates — so a test can exercise protected routes without standing up a login flow. Applications configured with jwt_keys (asymmetric keysets) should build their own auth.JWTManager via auth.NewJWTManagerFromKeys instead.
func (*Server) Runtime ¶
Runtime returns the nucleus.Runtime of the running application — the same handle modules receive in OnStart: managed *sql.DB, dialect-aware database handles, logger, authorizer, mailer, storage. Fails the test if the application has not captured it (it is available as soon as Start returns).
Source Files