Documentation
¶
Overview ¶
Package forgetest provides test infrastructure utilities for forge-generated applications. It includes helpers for isolated PostgreSQL test databases, HTTP test servers, and Datastar SSE form submission testing.
Index ¶
- func AppURL(srv *httptest.Server, path string) string
- func GetDatastar(t *testing.T, srv *httptest.Server, path string) *http.Response
- func NewApp(t *testing.T, handler http.Handler) *httptest.Server
- func NewTestDB(t *testing.T, opts ...func(*TestDBConfig)) *sql.DB
- func NewTestPool(t *testing.T, opts ...func(*TestDBConfig)) *pgxpool.Pool
- func PostDatastar(t *testing.T, srv *httptest.Server, path string, signals any) *http.Response
- func WithAtlasBin(path string) func(*TestDBConfig)
- func WithDatabaseURL(databaseURL string) func(*TestDBConfig)
- func WithMigrationDir(path string) func(*TestDBConfig)
- type SSEEvent
- type TestDBConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppURL ¶
AppURL returns the base URL of the test server combined with the given path. This is a convenience helper for building request URLs in tests.
url := forgetest.AppURL(srv, "/api/v1/users")
func GetDatastar ¶
GetDatastar sends a GET request with Accept: text/event-stream to the test server. This simulates a Datastar client requesting a streaming SSE endpoint.
resp := forgetest.GetDatastar(t, srv, "/users/1") events := forgetest.ReadSSEEvents(t, resp)
func NewApp ¶
NewApp creates an httptest.Server wrapping the given handler and registers automatic cleanup to close the server when the test completes.
The handler should be the fully-assembled application router. NewApp is intentionally thin so that forgetest stays generic across any forge app.
srv := forgetest.NewApp(t, myRouter) pool := forgetest.NewTestPool(t)
func NewTestDB ¶
func NewTestDB(t *testing.T, opts ...func(*TestDBConfig)) *sql.DB
NewTestDB creates an isolated PostgreSQL test schema per test using pgtestdb. The schema is created from a template using Atlas migrations. Each test gets its own database that is automatically dropped when the test completes.
Option functions can override any TestDBConfig field:
db := forgetest.NewTestDB(t, forgetest.WithDatabaseURL(os.Getenv("DATABASE_URL")))
func NewTestPool ¶
func NewTestPool(t *testing.T, opts ...func(*TestDBConfig)) *pgxpool.Pool
NewTestPool creates an isolated PostgreSQL test schema per test and returns a *pgxpool.Pool for use with the project's pgxpool-based code.
Most forge integration tests should use NewTestPool rather than NewTestDB.
Option functions can override any TestDBConfig field:
pool := forgetest.NewTestPool(t, forgetest.WithDatabaseURL(os.Getenv("DATABASE_URL")))
func PostDatastar ¶
PostDatastar sends a Datastar SSE form submission to the test server. It marshals signals to JSON, sets Content-Type: application/json and Accept: text/event-stream, then performs the POST.
The response body is registered for cleanup. Callers can call ReadSSEEvents on the response to inspect the returned Datastar events.
resp := forgetest.PostDatastar(t, srv, "/users", map[string]any{"name": "Alice"})
events := forgetest.ReadSSEEvents(t, resp)
func WithAtlasBin ¶
func WithAtlasBin(path string) func(*TestDBConfig)
WithAtlasBin returns an option function that overrides the atlas binary path.
func WithDatabaseURL ¶
func WithDatabaseURL(databaseURL string) func(*TestDBConfig)
WithDatabaseURL returns an option function that parses a DATABASE_URL and sets the Host, Port, User, Password, Database, and Options fields.
func WithMigrationDir ¶
func WithMigrationDir(path string) func(*TestDBConfig)
WithMigrationDir returns an option function that overrides the migrations directory.
Types ¶
type SSEEvent ¶
type SSEEvent struct {
// Type is the event name from the "event:" line (e.g. "datastar-merge-fragments").
Type string
// Data is the payload from the "data:" line.
Data string
}
SSEEvent represents a single server-sent event with a type and data payload.
func ReadSSEEvents ¶
ReadSSEEvents reads a response body and parses it as server-sent events. It returns a slice of SSEEvent, one per "event:" block in the response.
SSE format parsed:
event: datastar-merge-fragments data: <div id="main">...</div>
Blank lines separate events. Lines without "event:" or "data:" prefixes are ignored.
type TestDBConfig ¶
type TestDBConfig struct {
Host string // default: "localhost"
Port string // default: "5432"
User string // default: "postgres"
Password string // default: "postgres"
Database string // default: "postgres"
Options string // default: "sslmode=disable"
MigrationDir string // path to migrations/ directory
AtlasBin string // path to atlas binary (e.g. .forge/bin/atlas)
}
TestDBConfig holds connection and migration configuration for test databases.
func DefaultTestDBConfig ¶
func DefaultTestDBConfig() TestDBConfig
DefaultTestDBConfig returns a TestDBConfig using localhost PostgreSQL defaults. The MigrationDir and AtlasBin are resolved relative to the repository root using runtime.Caller so they work regardless of which package calls NewTestDB.
Source Files