wasm

package
v0.51.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 7, 2026 License: Apache-2.0 Imports: 54 Imported by: 0

Documentation

Overview

Package wasm provides a Go test harness that boots the real bldr start:web:wasm lifecycle and exposes the running app for e2e testing.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildExternalList 

func BuildExternalList() []string

BuildExternalList returns the list of packages to externalize so the browser resolves them via the app's import map.

func BuildResolverPlugin 

func BuildResolverPlugin(alphaRoot, vendorDir string) esbuild.Plugin

BuildResolverPlugin creates an esbuild plugin that resolves TypeScript path aliases (@go/*, @s4wave/*, @aptre/*) to the appropriate source and vendor directories.

alphaRoot is the root of the alpha source tree (sdk/, core/, app/, web/). vendorDir is the Go vendor directory containing @go/* and @aptre/* deps.

func CompileOneScript 

func CompileOneScript(path, outPath string, plugin esbuild.Plugin, external []string) error

CompileOneScript bundles a single TS file to an ESM module.

func E2EWasmEnabled 

func E2EWasmEnabled() bool

E2EWasmEnabled reports whether the heavy e2e/wasm suites should run. 

func NavigateHash(t testing.TB, h *Harness, page playwright.Page, hash string)

NavigateHash changes the client-side hash route without reloading the page.

func RelayCrossConnect 

func RelayCrossConnect(
	ctx context.Context,
	strmA, strmB e2e_wasm_session.SRPCSignalRelayService_SignalRelayClient,
) <-chan error

RelayCrossConnect forwards signaling messages between two SignalRelay streams bidirectionally. It runs two goroutines that forward A.Recv to B.Send and B.Recv to A.Send until the context is canceled or an error occurs.

The returned channel receives the first error from either goroutine. The caller should cancel the context to stop the cross-connect.

func ResolveWithTsFallback 

func ResolveWithTsFallback(resolved string) (esbuild.OnResolveResult, error)

ResolveWithTsFallback resolves a path, trying .ts extension if .js was requested.

func TraceArtifactPath 

func TraceArtifactPath(t testing.TB) string

TraceArtifactPath returns a deterministic artifact path beside the test file. The path is derived from the test name and a suffix: 

<test-package-dir>/testdata/<TestName>.trace

func UploadViaDnd added in v0.51.2 

func UploadViaDnd(t testing.TB, page playwright.Page, files []playwright.InputFile)

UploadViaDnd uploads files by dispatching a native file drop onto UnixFS.

func UploadViaPicker added in v0.51.2 

func UploadViaPicker(t testing.TB, page playwright.Page, files []playwright.InputFile)

UploadViaPicker uploads files through the hidden UnixFS file picker input.

func WaitForApp 

func WaitForApp(t testing.TB, page playwright.Page)

WaitForApp waits for the real app runtime, not the prerendered shell, to be connected to the Resource SDK.

func WaitForDriveReady 

func WaitForDriveReady(t testing.TB, h *Harness, page playwright.Page)

WaitForDriveReady waits for the drive viewer to render its demo content.

func WaitForDriveShell 

func WaitForDriveShell(t testing.TB, page playwright.Page)

WaitForDriveShell waits for the drive viewer shell to render.

func WaitForForgeReady 

func WaitForForgeReady(t testing.TB, h *Harness, page playwright.Page)

WaitForForgeReady waits for the forge dashboard to render with entity counts.

func WaitForForgeViewer 

func WaitForForgeViewer(t testing.TB, page playwright.Page)

WaitForForgeViewer waits for a forge viewer shell to render.

func WriteTraceArtifact 

func WriteTraceArtifact(path string, data []byte) error

WriteTraceArtifact writes trace bytes to the given path, creating parent directories as needed.

Types

type CompiledScripts 

type CompiledScripts map[string]string

CompiledScripts maps base filenames to their served URL paths. e.g. "navigate-hash.ts" -> "/e2e/navigate-hash.mjs"

func CompileTestScripts 

func CompileTestScripts(dir, outDir string) (CompiledScripts, error)

CompileTestScripts discovers *.ts files in dir, compiles each to an ESM module via esbuild, writes the output to outDir, and returns a map of base filename to served URL path.

Uses gitroot.FindRepoRoot() to locate the alpha repo root and vendor directory. For cross-repo usage where the alpha source is vendored, use CompileTestScriptsFor instead.

func CompileTestScriptsFor 

func CompileTestScriptsFor(dir, outDir, alphaRoot, vendorDir string) (CompiledScripts, error)

CompileTestScriptsFor discovers *.ts files in dir, compiles each to an ESM module via esbuild, writes the output to outDir, and returns a map of base filename to served URL path.

alphaRoot is the root of the alpha source tree (for @s4wave/* aliases). vendorDir is the Go vendor directory (for @go/* and @aptre/* aliases). For alpha itself, alphaRoot is the repo root and vendorDir is repo/vendor. For downstream repos that vendor alpha, alphaRoot is the vendored alpha path and vendorDir is the downstream repo's vendor directory.

type DriveScenario 

type DriveScenario struct {
	// contains filtered or unexported fields
}

DriveScenario records the owned drive created by the quickstart flow.

func CreateDriveScenario 

func CreateDriveScenario(t testing.TB, h *Harness, session *TestSession) *DriveScenario

CreateDriveScenario creates a drive in a fresh harness session.

func (*DriveScenario) GetSession 

func (s *DriveScenario) GetSession() *TestSession

GetSession returns the owning test session.

func (*DriveScenario) GetSessionIndex 

func (s *DriveScenario) GetSessionIndex() uint32

GetSessionIndex returns the 1-based session index from the quickstart route.

func (*DriveScenario) GetSpaceID 

func (s *DriveScenario) GetSpaceID() string

GetSpaceID returns the created space identifier from the quickstart route.

type ForgeScenario 

type ForgeScenario struct {
	// contains filtered or unexported fields
}

ForgeScenario records the forge environment created by the quickstart flow.

func CreateForgeScenario 

func CreateForgeScenario(t testing.TB, h *Harness, session *TestSession) *ForgeScenario

CreateForgeScenario creates a forge environment in a fresh harness session.

func (*ForgeScenario) GetSession 

func (s *ForgeScenario) GetSession() *TestSession

GetSession returns the owning test session.

func (*ForgeScenario) GetSessionIndex 

func (s *ForgeScenario) GetSessionIndex() uint32

GetSessionIndex returns the 1-based session index from the quickstart route.

func (*ForgeScenario) GetSpaceID 

func (s *ForgeScenario) GetSpaceID() string

GetSpaceID returns the created space identifier from the quickstart route.

type Harness 

type Harness struct {
	// contains filtered or unexported fields
}

Harness boots and manages the bldr start:web:wasm lifecycle for e2e testing. One harness is intended per test package. The harness boots the devtool bus, compiles plugins, and starts the HTTP server once. Individual tests create isolated browser sessions via NewSession.

func Boot 

func Boot(ctx context.Context, le *logrus.Entry, opts ...Option) (_ *Harness, retErr error)

project controller (which compiles plugin manifests), builds the web entrypoint and runtime.wasm, and serves the app over HTTP.

The returned Harness must be released with Release when done.

func (*Harness) BaseURL 

func (h *Harness) BaseURL() string

BaseURL returns the HTTP base URL of the running app (e.g. http://127.0.0.1:12345).

func (*Harness) Browser 

func (h *Harness) Browser() playwright.Browser

Browser returns the raw Playwright Browser handle, or nil if not launched.

func (*Harness) Cleanup 

func (h *Harness) Cleanup(t testing.TB)

Cleanup registers Release as a test cleanup function so the harness is torn down when the test or subtest finishes.

func (*Harness) CompileScripts 

func (h *Harness) CompileScripts(dir string) error

CompileScripts discovers and compiles *.ts files in the given directory into ESM modules served at /e2e/*.mjs. The compiled modules externalize shared web packages (react, @aptre/bldr, etc.) so the browser resolves them via the app's import map, sharing module instances with the running app.

func (*Harness) Context 

func (h *Harness) Context() context.Context

Context returns the harness lifecycle context.

func (*Harness) GetDevtoolBus 

func (h *Harness) GetDevtoolBus() *devtool.DevtoolBus

GetDevtoolBus returns the underlying DevtoolBus for advanced access.

func (*Harness) GetProjectConfig 

func (h *Harness) GetProjectConfig() *bldr_project.ProjectConfig

GetProjectConfig returns the resolved project config.

func (*Harness) LaunchBrowser 

func (h *Harness) LaunchBrowser() error

LaunchBrowser starts a Playwright-managed Chromium instance. The browser process is shared across all test sessions; each test creates its own BrowserContext via Harness.NewSession.

Call this after Boot returns. Headless mode is the default; pass WithHeadless(false) at Boot time to see the browser.

func (*Harness) LookupSessionByPage 

func (h *Harness) LookupSessionByPage(page playwright.Page) *TestSession

LookupSessionByPage returns the test session associated with a page.

func (*Harness) NewBlankSession 

func (h *Harness) NewBlankSession(t testing.TB) *TestSession

NewBlankSession creates an isolated browser session with a fresh browser context and page, but does not load the app or connect SDK resources.

func (*Harness) NewPageSession 

func (h *Harness) NewPageSession(t testing.TB) *TestSession

NewPageSession creates an isolated browser session with only a browser context and page, without connecting SDK resources. Use this for tests that only need browser interaction (e.g. heap profiling, screenshot tests).

func (*Harness) NewSession 

func (h *Harness) NewSession(t testing.TB) *TestSession

NewSession creates an isolated browser session for a single test. A fresh BrowserContext with clean storage is created, the app is loaded, and resources are connected through the devtool bus. The session is released automatically when the test finishes via t.Cleanup.

func (*Harness) Port 

func (h *Harness) Port() int

Port returns the TCP port the HTTP server is listening on.

func (*Harness) Release 

func (h *Harness) Release()

Release tears down the harness: closes the shared browser process, cancels the context, waits for the HTTP server goroutine to exit, and releases all controllers and the devtool bus. Individual test sessions are released via their own cleanup (t.Cleanup).

func (*Harness) Script 

func (h *Harness) Script(name string) string

Script returns a JS expression that dynamically imports the named test script and calls its default export with the provided args. The expression is compatible with Playwright's Page.Evaluate(expr, args).

Panics if the script is not found, which immediately surfaces missing scripts in tests.

func (*Harness) ScriptOutDir 

func (h *Harness) ScriptOutDir() string

ScriptOutDir returns the output directory for compiled test scripts. Files written here are served at /e2e/*.mjs by the devtool HTTP server.

func (*Harness) Scripts 

func (h *Harness) Scripts() CompiledScripts

Scripts returns the compiled test scripts. Returns nil if CompileScripts has not been called.

func (*Harness) SetScripts 

func (h *Harness) SetScripts(scripts CompiledScripts)

SetScripts sets the compiled test script map, for use by downstream repos that compile scripts with a custom resolver via CompileTestScriptsFor.

type Option 

type Option func(*options)

Option configures the Harness.

func WithConfigMutator 

func WithConfigMutator(fn func(*bldr_project.ProjectConfig) error) Option

WithConfigMutator registers a function that mutates the loaded project config before the project controller starts. Use this to inject test-only controller wiring such as trace service entries.

func WithHeadless 

func WithHeadless(headless bool) Option

WithHeadless controls whether the browser runs headless (default true).

func WithRepoRoot 

func WithRepoRoot(root string) Option

WithRepoRoot overrides automatic repo root discovery.

func WithSessionHarness 

func WithSessionHarness() Option

WithSessionHarness injects the session harness controller into the plugin WASM processes for test orchestration (peer info, signaling relay, link establishment).

type PeerWatcher 

type PeerWatcher struct {
	// contains filtered or unexported fields
}

PeerWatcher tracks browser peers discovered via HandleMountedStream directives on the devtool bus. It supports multi-session tests by tracking seen peers and blocking until a previously unseen peer connects.

func NewPeerWatcher 

func NewPeerWatcher(b bus.Bus) (*PeerWatcher, error)

NewPeerWatcher registers a HandleMountedStream handler on the bus filtering for HostProtocolID and returns a PeerWatcher that tracks discovered peers.

func (*PeerWatcher) HandleDirective 

func (pw *PeerWatcher) HandleDirective(_ context.Context, di directive.Instance) ([]directive.Resolver, error)

HandleDirective implements directive.Handler. It filters for HandleMountedStream directives on HostProtocolID and sends peer IDs to the pending channel. A peer can reconnect with the same ID after an early startup failure, so these events must not be deduplicated across the whole package run.

func (*PeerWatcher) Release 

func (pw *PeerWatcher) Release()

Release removes the handler from the bus.

func (*PeerWatcher) WaitForNewPeer 

func (pw *PeerWatcher) WaitForNewPeer(ctx context.Context) (peer.ID, error)

WaitForNewPeer blocks until a browser peer mount event arrives and returns the most recent pending peer ID. Stale peer mount events can remain queued across subtest cleanup, so callers want the newest peer observation rather than the oldest buffered event.

type TestSession 

type TestSession struct {
	// contains filtered or unexported fields
}

TestSession holds an isolated browser context and resource connections for a single test. Each test creates its own session via Harness.NewSession so browser state (localStorage, cookies, WASM process, workers) is isolated.

func (*TestSession) BrowserClient 

func (s *TestSession) BrowserClient() srpc.Client

BrowserClient returns the SRPC client connected to the browser peer, or nil if resources are not connected.

func (*TestSession) BrowserContext 

func (s *TestSession) BrowserContext() playwright.BrowserContext

BrowserContext returns the Playwright BrowserContext for this session.

func (*TestSession) CaptureTrace 

func (s *TestSession) CaptureTrace(ctx context.Context, label string, fn func(ctx context.Context) error) ([]byte, error)

CaptureTrace starts a trace, runs fn, stops the trace, and returns the raw bytes. This brackets only the profiled interaction.

func (*TestSession) ConnectResources 

func (s *TestSession) ConnectResources(ctx context.Context) error

ConnectResources connects the session Resource SDK client through the devtool/browser RPC link.

func (*TestSession) LoadApp 

func (s *TestSession) LoadApp() error

LoadApp loads the app base URL into the session page.

func (*TestSession) MountSessionByIdx 

func (s *TestSession) MountSessionByIdx(ctx context.Context, idx uint32) (*s4wave_session.Session, error)

MountSessionByIdx mounts a session by its 1-based index and returns the Session SDK wrapper. The caller must call Release on the returned Session.

func (*TestSession) Page 

func (s *TestSession) Page() playwright.Page

Page returns the Playwright Page for this session.

func (*TestSession) Release 

func (s *TestSession) Release()

Release tears down the session's browser context and resource connections.

func (*TestSession) ResourceClient 

func (s *TestSession) ResourceClient() *resource_client.Client

ResourceClient returns the Resource SDK client, or nil if not connected.

func (*TestSession) Root 

func (s *TestSession) Root() *s4wave_root.Root

Root returns the Root resource wrapper, or nil if not connected.

func (*TestSession) StartTrace 

func (s *TestSession) StartTrace(ctx context.Context, label string) error

StartTrace starts runtime trace capture in the browser plugin process.

func (*TestSession) StopTrace 

func (s *TestSession) StopTrace(ctx context.Context) ([]byte, error)

StopTrace stops runtime trace capture and returns the raw trace bytes.

func (*TestSession) Workers 

func (s *TestSession) Workers() []playwright.Worker

Workers returns a snapshot of the tracked page workers.

Source Files

View all Source files

Directories

Path Synopsis
Package memlab provides heap snapshot capture via Chrome DevTools Protocol and analysis via @memlab/heap-analysis for memory leak detection in e2e tests.
 Package memlab provides heap snapshot capture via Chrome DevTools Protocol and analysis via @memlab/heap-analysis for memory leak detection in e2e tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.