Documentation
¶
Index ¶
- type Backend
- type BackendKind
- type ContainerConfig
- type TestContainer
- func (c *TestContainer) APIBaseURL() string
- func (c *TestContainer) APIClient() (*instanceoapi.ClientWithResponses, error)
- func (c *TestContainer) APIClientNoKeepAlive() (*instanceoapi.ClientWithResponses, error)
- func (c *TestContainer) CDPAddr() string
- func (c *TestContainer) CDPURL() string
- func (c *TestContainer) ChromeDriverAddr() string
- func (c *TestContainer) ChromeDriverURL() string
- func (c *TestContainer) ChromeDriverWSURL(path string) string
- func (c *TestContainer) Exec(ctx context.Context, cmd []string) (int, string, error)
- func (c *TestContainer) ExitCh() <-chan error
- func (c *TestContainer) Start(ctx context.Context, cfg ContainerConfig) error
- func (c *TestContainer) Stop(ctx context.Context) error
- func (c *TestContainer) WaitChromeDriver(ctx context.Context) error
- func (c *TestContainer) WaitDevTools(ctx context.Context) error
- func (c *TestContainer) WaitReady(ctx context.Context) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend interface {
// Start provisions and boots the browser instance.
Start(ctx context.Context, cfg ContainerConfig) error
// Stop tears the instance down and releases its resources.
Stop(ctx context.Context) error
// SupportsHostAccess reports whether the backend can bridge the instance to
// a service the test stands up on its own host (ContainerConfig.HostAccess).
// The Docker backend can (host.docker.internal); a remote VM backend cannot.
// TestContainer.Start uses this to skip host-fixture tests on backends that
// can't satisfy them, rather than failing.
SupportsHostAccess() bool
// APIBaseURL returns the base URL for the instance's control-plane API
// server (container port 10001).
APIBaseURL() string
// CDPURL returns the WebSocket URL for the DevTools proxy (port 9222).
CDPURL() string
// CDPAddr returns the TCP host:port for the DevTools proxy (port 9222).
CDPAddr() string
// ChromeDriverURL returns the base HTTP URL for the ChromeDriver proxy
// (port 9224).
ChromeDriverURL() string
// APIClient returns an OpenAPI client bound to APIBaseURL.
APIClient() (*instanceoapi.ClientWithResponses, error)
// APIClientNoKeepAlive returns an OpenAPI client that disables HTTP
// connection reuse (useful after server restarts).
APIClientNoKeepAlive() (*instanceoapi.ClientWithResponses, error)
// WaitReady blocks until the instance's API server is serving.
WaitReady(ctx context.Context) error
// WaitDevTools blocks until the CDP endpoint accepts connections.
WaitDevTools(ctx context.Context) error
// WaitChromeDriver blocks until the ChromeDriver proxy reports ready.
WaitChromeDriver(ctx context.Context) error
// Exec runs a command inside the instance and returns the exit code and
// combined stdout+stderr output.
Exec(ctx context.Context, cmd []string) (int, string, error)
// ExitCh returns a channel that fires when the instance exits.
ExitCh() <-chan error
}
Backend is the abstraction every e2e browser-instance provider implements.
It captures the public surface that the test files consume via *TestContainer. Two implementations exist:
- dockerBackend: runs the image as a local Docker container via testcontainers-go (the historical behavior, still the default).
- hypemanBackend: starts the image as a remote VM on a running Hypeman dev server using the github.com/kernel/hypeman-go client library.
Keeping the surface identical means selecting a backend is a pure factory concern and requires no changes in individual tests.
type BackendKind ¶
type BackendKind string
BackendKind enumerates the supported e2e backends.
const ( BackendDocker BackendKind = "docker" BackendHypeman BackendKind = "hypeman" )
type ContainerConfig ¶
type ContainerConfig struct {
Env map[string]string
// HostAccess requests that the browser instance be able to reach a service
// the test stands up on its own host (loopback) — used by tests with a local
// fixture server (capmonster, persisted-login). How it's provided is a
// backend detail (the Docker backend maps host.docker.internal); backends
// that cannot bridge a remote instance to the test host reject it.
HostAccess bool
}
ContainerConfig holds optional configuration for instance startup.
It is shared by every backend so that the ~24 e2e_*_test.go files can keep calling Start with the same shape regardless of where the browser instance actually runs (a local Docker container or a remote Hypeman VM).
type TestContainer ¶
type TestContainer struct {
// Image is the OCI image reference under test.
Image string
// contains filtered or unexported fields
}
TestContainer is the handle every e2e test uses to drive a browser instance.
Historically this struct wrapped testcontainers-go directly. It is now a thin facade over a pluggable Backend (see backend.go), selected at construction time via the KI_E2E_BACKEND env var. The public method set is unchanged, so the ~24 e2e_*_test.go files that hold a *TestContainer continue to work without modification regardless of whether the instance runs as a local Docker container or a remote Hypeman VM.
func NewTestContainer ¶
func NewTestContainer(tb testing.TB, image string) *TestContainer
NewTestContainer creates a new test container handle backed by the configured backend. The actual instance is provisioned when Start() is called. Works with both *testing.T and *testing.B (any testing.TB).
func (*TestContainer) APIBaseURL ¶
func (c *TestContainer) APIBaseURL() string
APIBaseURL returns the URL for the instance's API server.
func (*TestContainer) APIClient ¶
func (c *TestContainer) APIClient() (*instanceoapi.ClientWithResponses, error)
APIClient creates an OpenAPI client for this instance's API.
func (*TestContainer) APIClientNoKeepAlive ¶
func (c *TestContainer) APIClientNoKeepAlive() (*instanceoapi.ClientWithResponses, error)
APIClientNoKeepAlive creates an API client that doesn't reuse connections. This is useful after server restarts where existing connections may be stale.
func (*TestContainer) CDPAddr ¶
func (c *TestContainer) CDPAddr() string
CDPAddr returns the TCP address for the instance's DevTools proxy.
func (*TestContainer) CDPURL ¶
func (c *TestContainer) CDPURL() string
CDPURL returns the WebSocket URL for the instance's DevTools proxy.
func (*TestContainer) ChromeDriverAddr ¶
func (c *TestContainer) ChromeDriverAddr() string
ChromeDriverAddr returns the host:port for the instance's ChromeDriver proxy, derived from ChromeDriverURL (without scheme). Useful for substring assertions on proxy-rewritten URLs.
func (*TestContainer) ChromeDriverURL ¶
func (c *TestContainer) ChromeDriverURL() string
ChromeDriverURL returns the base HTTP URL for the instance's ChromeDriver proxy.
func (*TestContainer) ChromeDriverWSURL ¶
func (c *TestContainer) ChromeDriverWSURL(path string) string
ChromeDriverWSURL returns the WebSocket URL (ws://host:port/path) for the instance's ChromeDriver proxy. path should include a leading slash.
func (*TestContainer) Exec ¶
Exec executes a command inside the instance and returns the exit code and combined output.
func (*TestContainer) ExitCh ¶
func (c *TestContainer) ExitCh() <-chan error
ExitCh returns a channel that receives when the instance exits.
func (*TestContainer) Start ¶
func (c *TestContainer) Start(ctx context.Context, cfg ContainerConfig) error
Start starts the instance with the given configuration.
If the test requests HostAccess but the selected backend can't bridge the instance to the test host (e.g. the hypeman backend, which runs a remote VM), the test is skipped rather than failed: such tests rely on a fixture served from the runner's loopback that a remote instance cannot reach. This keeps the hypeman CI job green while preserving coverage on the Docker backend.
func (*TestContainer) Stop ¶
func (c *TestContainer) Stop(ctx context.Context) error
Stop stops and removes the instance.
func (*TestContainer) WaitChromeDriver ¶
func (c *TestContainer) WaitChromeDriver(ctx context.Context) error
WaitChromeDriver waits for the ChromeDriver proxy (and upstream ChromeDriver) to be ready.
func (*TestContainer) WaitDevTools ¶
func (c *TestContainer) WaitDevTools(ctx context.Context) error
WaitDevTools waits for the CDP WebSocket endpoint to be ready.
Source Files