Documentation
¶
Overview ¶
Package testutil runs Popcorn Web applications from isolated copies of the registered runtime configuration.
Index ¶
- func Exchange(t pwtest.TestingT, handler http.Handler, request pwtest.Request) pwtest.Response
- type Config
- type Harness
- type IdPInfo
- type IdPOption
- func WithIdPBinding(bind func(*Config, IdPInfo)) IdPOption
- func WithIdPClient(redirectURIs ...string) IdPOption
- func WithIdPConfig(path string) IdPOption
- func WithIdPRoster(source string) IdPOption
- func WithIdPScopes(scopes ...string) IdPOption
- func WithIdPUsers(users ...devidp.User) IdPOption
- func WithLoginUser(subject string) IdPOption
- type RunOption
- type Server
- func (server *Server) AssertDB(t TestingT, files ...string)
- func (server *Server) Client() *http.Client
- func (server *Server) Close()
- func (server *Server) Context() context.Context
- func (server *Server) IdP() *devidp.Server
- func (server *Server) IdPInfo() IdPInfo
- func (server *Server) LoginAs(t TestingT, subject string)
- func (server *Server) Seed(t TestingT, files ...string)
- type TestingT
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Exchange ¶
Exchange runs one request through handler on a real net/http server and returns what it answered.
It is the net/http half of the backend-neutral seam. The fasthttp half has the same name and the same signature apart from the handler type, so a test written against it says the same thing on either transport and only the import line moves.
The server is real and the connection is not: an in-memory pipe carries it, so the test pays a full request parse and response serialization — which is where half the behaviour worth testing lives — without paying a socket. That is also what makes it a fair pair with the other half, which runs the same way.
Each call starts and keeps a server for the rest of the test; a test making several requests against one handler builds a Harness once instead.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config is an isolated copy of all registered framework and application configuration values. Its three operations are methods, so a test reads config.Update rather than naming this package twice on one line.
func (*Config) Get ¶ added in v0.5.1
Get returns one typed value from a copied configuration. It is the one entry with nothing to infer the type from, so the call site writes it: config.Get[pw.ServerConfig](). A nil configuration answers the zero value.
type Harness ¶ added in v0.5.2
type Harness struct {
// contains filtered or unexported fields
}
Harness is one running server and one client, shared by every exchange of a test.
Exchange starts a fresh server, listener and goroutine per call and keeps all of them alive until the test ends, so a test driving one handler with N requests held N listeners and paid N startups. A harness starts the server once, and its client reuses connections — which is also what lets a sequence of exchanges meet keep-alive the way a browser would.
func NewHarness ¶ added in v0.5.2
NewHarness starts a real net/http server for handler and returns the harness that drives it. The server is shut down by t.Cleanup.
type IdPInfo ¶
IdPInfo is what a test needs to point an application at the identity provider TestRun started for it.
type IdPOption ¶
type IdPOption func(*idpSettings) error
IdPOption configures the identity provider started by WithIdentityProvider.
func WithIdPBinding ¶
WithIdPBinding writes the issuer and generated client credentials into the copied configuration. It runs after customize, so it wins over a placeholder the test left there.
func WithIdPClient ¶
WithIdPClient registers a client whose redirect URIs are matched exactly. The default client accepts any loopback callback, which is what a test server on a reserved port needs.
func WithIdPConfig ¶
WithIdPConfig reads the roster from a devidp.toml file.
func WithIdPRoster ¶
WithIdPRoster reads the roster from devidp.toml content held in the test.
func WithIdPScopes ¶
WithIdPScopes adds scope tokens beyond openid, profile, and email.
func WithIdPUsers ¶
WithIdPUsers builds the roster from Go values.
func WithLoginUser ¶
WithLoginUser pre-selects the subject the provider signs in as, so authorization redirects straight back to the application with a code.
type RunOption ¶
type RunOption func(*runSettings) error
RunOption configures TestRun resources.
func WithIdentityProvider ¶
WithIdentityProvider starts a development OpenID Provider before the application server, so a test can drive an OIDC login without a browser and without external credentials.
Exactly one roster source is required: WithIdPConfig, WithIdPRoster, or WithIdPUsers.
func WithMigrations ¶
WithMigrations installs the migrated schema from a migration directory.
The schema is installed by replaying a snapshot rather than by running every migration, so the cost is paid once per test binary and an in-memory database works on both the host and the TinyGo execution path.
func WithMigrationsFS ¶
WithMigrationsFS installs the migrated schema from an embedded migration tree.
func WithSeed ¶
WithSeed loads dataset files into the copied database after the migration schema is installed and before the HTTP server starts.
Each name is a path relative to the seed directory; the .yaml extension may be omitted. Datasets are applied in the given order.
func WithSeedDir ¶
WithSeedDir overrides the dataset directory, which defaults to testdata/seed relative to the test package directory.
func WithTransaction ¶
WithTransaction runs every request of this test server inside one transaction that is rolled back when the test finishes, so tests sharing one database stay independent and may run in parallel. Framework transactions started by the application nest into it as savepoints, which requires a driver with savepoint support.
type Server ¶
type Server struct {
URL string
Port int
Config *Config
DB *sql.DB
// contains filtered or unexported fields
}
Server is a running application created by TestRun.
func TestRun ¶
func TestRun(t TestingT, handler http.Handler, customize func(*Config), options ...RunOption) *Server
TestRun copies every registered configuration, defaults the copied server port to -1, applies customize, initializes copied runtime resources, and starts the application. Port -1 selects an available loopback port.
func (*Server) AssertDB ¶
AssertDB compares the running server's database against expected datasets.
A mismatch is reported through Errorf with a plain-text per-table diff and the test continues.
Under WithTransaction it reads inside the test transaction, so writes made by requests are visible before any commit. Otherwise only committed state is visible, and a request whose transaction is still open has not been compared yet.
func (*Server) Close ¶
func (server *Server) Close()
Close stops the server, rolls back a WithTransaction transaction, and releases its copied runtime resources.
func (*Server) Context ¶
Context returns a context carrying the same runtime resources the server installs on requests, including the WithTransaction transaction. Use it to prepare or assert data inside the test transaction.
func (*Server) Seed ¶
Seed loads dataset files into the running server's database.
Use it to reset state between phases of one test. A failure stops the test.
Under WithTransaction it seeds inside the test transaction, so the rows are visible to requests and disappear with the rollback. Otherwise it seeds through the pool and the rows are committed.
Source Files