wasm

package
v0.53.0 Latest Latest
Warning

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

 Go to latest Published: Jul 5, 2026 License: Apache-2.0 Imports: 64 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

View Source 
const (
	// E2EWasmCompilerEnv selects the browser Go compiler for app tests.
	E2EWasmCompilerEnv = "E2E_WASM_COMPILER"
	// E2EWasmLegacyTinyGoEnv was the old boolean TinyGo selector.
	E2EWasmLegacyTinyGoEnv = "E2E_WASM_TINYGO"
	// E2EWasmWorkerModeEnv selects the browser worker topology for local tests.
	E2EWasmWorkerModeEnv = "E2E_WASM_WORKER_MODE"
	// E2EWasmTinyGoProfileEnv selects the local TinyGo build profile.
	E2EWasmTinyGoProfileEnv = "E2E_WASM_TINYGO_PROFILE"
	// E2EWasmTinyGoOptEnv overrides the local TinyGo optimization level.
	E2EWasmTinyGoOptEnv = "E2E_WASM_TINYGO_OPT"
	// E2EWasmTinyGoPanicEnv overrides the local TinyGo panic strategy.
	E2EWasmTinyGoPanicEnv = "E2E_WASM_TINYGO_PANIC"
	// E2EWasmTinyGoGCEnv overrides the local TinyGo garbage collector.
	E2EWasmTinyGoGCEnv = "E2E_WASM_TINYGO_GC"
	// E2EWasmTinyGoSchedulerEnv overrides the local TinyGo scheduler.
	E2EWasmTinyGoSchedulerEnv = "E2E_WASM_TINYGO_SCHEDULER"
	// E2EWasmTinyGoLLVMFeaturesEnv overrides the local TinyGo LLVM feature set.
	E2EWasmTinyGoLLVMFeaturesEnv = "E2E_WASM_TINYGO_LLVM_FEATURES"
	// E2EWasmTinyGoInterpTimeoutEnv overrides TinyGo's interp timeout locally.
	E2EWasmTinyGoInterpTimeoutEnv = "E2E_WASM_TINYGO_INTERP_TIMEOUT"
	// E2EWasmManifestBuildTimeoutEnv overrides the local startup Manifest build wait.
	E2EWasmManifestBuildTimeoutEnv = "E2E_WASM_MANIFEST_BUILD_TIMEOUT"
	// E2EWasmGoScriptRuntimeTraceEnv opts GoScript browser runs into
	// runtime-trace capture; off by default so routine GoScript e2e stays fast.
	E2EWasmGoScriptRuntimeTraceEnv = "E2E_WASM_GOSCRIPT_RUNTIME_TRACE"
	// E2EWasmDriveBenchEnv opts in the time-to-Drive startup bench; off by
	// default so routine e2e does not pay the bench measurement cost.
	E2EWasmDriveBenchEnv = "E2E_WASM_DRIVE_BENCH"
	// E2EWasmDriveBenchJSProfileEnv opts the Drive bench into same-window
	// Chromium JS CPU profile capture; off by default so routine e2e stays cheap.
	E2EWasmDriveBenchJSProfileEnv = "E2E_WASM_DRIVE_BENCH_JS_PROFILE"
)

Variables

This section is empty.

Functions

func ApplyE2EWasmTinyGoCompilerEnv added in v0.51.7 

func ApplyE2EWasmTinyGoCompilerEnv() error

ApplyE2EWasmTinyGoCompilerEnv applies the local TinyGo profile to Bldr's TinyGo compiler env before the startup Manifest builder runs.

func AssertBrowserStartupDone added in v0.51.7 

func AssertBrowserStartupDone(t testing.TB, h *Harness, page playwright.Page) map[string]any

func AssertQuickstartContentAfterProgress added in v0.51.7 

func AssertQuickstartContentAfterProgress(t testing.TB, result DriveReadyResult)

func AssertRootImportMap added in v0.51.7 

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

func AssertSetupBannerHidden added in v0.51.7 

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

AssertSetupBannerHidden verifies the setup banner does not render before the session has enough local storage to justify the onboarding nudge.

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 CompleteDriveIntroWizard added in v0.51.7 

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

CompleteDriveIntroWizard opens the raw files browser for both current Drive wrapper quickstarts and legacy wizard-indexed quickstarts.

func CompleteDriveIntroWizardIfPresent added in v0.51.7 

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

CompleteDriveIntroWizardIfPresent completes the first-run Drive intro when the current route opens it before the raw files browser.

func CompleteLocalSetupLockStep added in v0.51.3 

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

CompleteLocalSetupLockStep sets the local session lock mode to PIN and waits for the setup state to mark the lock step complete.

func CompleteLocalSetupPemStep added in v0.51.3 

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

CompleteLocalSetupPemStep downloads the local backup PEM and waits for the setup state to mark the backup step complete.

func ConfigureGoCompilerForManifest added in v0.52.0 

func ConfigureGoCompilerForManifest(
	manifestID string,
	mode bldr_plugin_compiler_go.GoCompiler,
) func(*bldr_project.ProjectConfig) error

ConfigureGoCompilerForManifest enables an alternate browser Go plugin compiler and removes dev-only config outside the seed compiler proof.

func ConfigureGoScriptBrowserStartup added in v0.51.8 

func ConfigureGoScriptBrowserStartup(conf *bldr_project.ProjectConfig) error

ConfigureGoScriptBrowserStartup makes the local GoScript e2e lane cover the same browser Go plugin startup surface as the staging GoScript release.

func ConfigureGoScriptForManifest added in v0.51.8 

func ConfigureGoScriptForManifest(manifestID string) func(*bldr_project.ProjectConfig) error

ConfigureGoScriptForManifest enables GoScript and removes dev-only config that pulls packages the browser lane should not compile.

func ConfigureTinyGoForManifest added in v0.51.7 

func ConfigureTinyGoForManifest(manifestID string) func(*bldr_project.ProjectConfig) error

ConfigureTinyGoForManifest enables TinyGo and removes dev-only config that pulls packages TinyGo cannot compile.

func E2EWasmDriveBenchEnabled added in v0.52.0 

func E2EWasmDriveBenchEnabled() bool

E2EWasmDriveBenchEnabled reports whether the time-to-Drive startup bench runs, gated by E2E_WASM_DRIVE_BENCH so routine e2e skips the measurement.

func E2EWasmDriveBenchJSProfileEnabled added in v0.52.0 

func E2EWasmDriveBenchJSProfileEnabled() bool

E2EWasmDriveBenchJSProfileEnabled reports whether the Drive bench should capture a same-window Chromium JS CPU profile.

func E2EWasmEnabled 

func E2EWasmEnabled() bool

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

func E2EWasmGoScriptRuntimeTraceEnabled added in v0.52.0 

func E2EWasmGoScriptRuntimeTraceEnabled() bool

E2EWasmGoScriptRuntimeTraceEnabled reports whether GoScript browser runs opt into runtime-trace capture via E2E_WASM_GOSCRIPT_RUNTIME_TRACE.

func E2EWasmSlowCompilerEnabled added in v0.51.8 

func E2EWasmSlowCompilerEnabled() bool

E2EWasmSlowCompilerEnabled reports whether app readiness should allow the longer browser boot budget used by alternate browser compilers.

func E2EWasmStartupBuildCacheEnabled added in v0.51.7 

func E2EWasmStartupBuildCacheEnabled() bool

E2EWasmStartupBuildCacheEnabled reports whether the harness should preserve world-backed startup Manifest build results between test process boots.

func E2EWasmTraceServiceEnabled added in v0.51.8 

func E2EWasmTraceServiceEnabled(compiler E2EWasmCompiler) bool

E2EWasmTraceServiceEnabled reports whether the trace service should be injected into the app harness config. Native Go always carries it; GoScript opts in via E2E_WASM_GOSCRIPT_RUNTIME_TRACE so routine GoScript e2e does not pay the trace-service compile cost; TinyGo never carries it.

func EnableGoCompilerForManifest added in v0.52.0 

func EnableGoCompilerForManifest(
	manifestID string,
	mode bldr_plugin_compiler_go.GoCompiler,
) func(*bldr_project.ProjectConfig) error

EnableGoCompilerForManifest enables a compiler mode for a Go plugin Manifest's web platform override.

func EnableGoScriptForManifest added in v0.51.8 

func EnableGoScriptForManifest(manifestID string) func(*bldr_project.ProjectConfig) error

EnableGoScriptForManifest enables GoScript for a Go plugin Manifest's web platform override.

func EnableQuickstartTimingLogs added in v0.51.3 

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

EnableQuickstartTimingLogs asks the browser quickstart flow to log each phase and publish phase timing for timeout diagnostics.

func EnableTinyGoForManifest added in v0.51.7 

func EnableTinyGoForManifest(manifestID string) func(*bldr_project.ProjectConfig) error

EnableTinyGoForManifest enables TinyGo for a Go plugin Manifest's web platform override. 

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 ResolveE2EWasmManifestBuildTimeout added in v0.51.8 

func ResolveE2EWasmManifestBuildTimeout(defaultTimeout time.Duration) (time.Duration, error)

ResolveE2EWasmManifestBuildTimeout resolves the startup Manifest build wait for local harness runs.

func ResolveE2EWasmStartupBuildCacheEnabled added in v0.51.8 

func ResolveE2EWasmStartupBuildCacheEnabled() (bool, error)

E2EWasmStartupBuildCacheEnabled reports whether the harness should preserve world-backed startup Manifest build results between test process boots.

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 UploadPathsViaPicker added in v0.51.7 

func UploadPathsViaPicker(t testing.TB, page playwright.Page, paths []string)

UploadPathsViaPicker uploads existing local files through the hidden UnixFS file picker input. Playwright transports path-backed files without the 50 MiB in-memory buffer ceiling used for InputFile.Buffer.

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 WaitForDriveEntry added in v0.51.7 

func WaitForDriveEntry(t testing.TB, page playwright.Page, name string)

WaitForDriveEntry waits for a named Drive row to render.

func WaitForDriveShell 

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

WaitForDriveShell waits for the drive viewer shell to render.

func WaitForEmptySpaceReady added in v0.52.0 

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

WaitForEmptySpaceReady waits for the static Space quickstart root route to render the empty Space affordance.

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 WaitForLocalSetupComplete added in v0.51.3 

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

WaitForLocalSetupComplete waits until both local onboarding cards show their completed state and the setup banner is no longer visible.

func WaitForLocalSetupPage added in v0.51.3 

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

WaitForLocalSetupPage waits for the local setup wizard to render.

func WaitForPinUnlockOverlay added in v0.51.7 

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

WaitForPinUnlockOverlay waits for the session PIN unlock gate.

func WaitForPlanPage added in v0.51.3 

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

WaitForPlanPage waits for the plan selection page to render.

func WaitForSessionLockMode added in v0.51.3 

func WaitForSessionLockMode(
	t testing.TB,
	h *Harness,
	session *TestSession,
	sessionIndex uint32,
	want session_core.SessionLockMode,
)

WaitForSessionLockMode waits for the mounted session to report the expected lock mode through the SDK lock-state stream.

func WaitForSetupBanner added in v0.51.3 

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

WaitForSetupBanner waits for the local setup banner 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 BrowserPeerObservation added in v0.51.5 

type BrowserPeerObservation struct {
	PeerID     peer.ID
	Sequence   uint64
	ObservedAt time.Time
}

BrowserPeerObservation describes one browser peer mount event seen by the devtool bus. A peer can reconnect with the same ID, so each observation has its own monotonic sequence number.

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 CrashReport added in v0.51.7 

type CrashReport struct {
	GoFatalStackTrace []string
	PageErrors        []string
	RuntimeErrors     []string
	WorkerErrors      []string
	ExitedGoCount     int
}

CrashReport classifies browser and worker messages captured during a WASM E2E scenario.

func DrainCrashReport added in v0.51.7 

func DrainCrashReport(messages <-chan string) CrashReport

DrainCrashReport drains all currently buffered console messages into a report. It does not wait for future messages.

func (*CrashReport) AddMessage added in v0.51.7 

func (r *CrashReport) AddMessage(msg string)

AddMessage records one browser or worker diagnostic line.

func (CrashReport) HasCrash added in v0.51.7 

func (r CrashReport) HasCrash() bool

HasCrash returns true when a primary crash signal was captured.

func (CrashReport) HasExitedGoLoop added in v0.51.7 

func (r CrashReport) HasExitedGoLoop() bool

HasExitedGoLoop returns true once the same exited-Go symptom repeats enough times to be treated as recovery-loop evidence instead of a single close race.

type DriveReadyResult added in v0.51.7 

type DriveReadyResult struct {
	Body                      string
	Hash                      string
	ContentReadyMs            int
	QuickstartState           string
	QuickstartProgressReadyMs *int
	QuickstartContentReadyMs  *int
	QuickstartFinishedMs      *int
	QuickstartError           string
	QuickstartTiming          map[string]any
}

DriveReadyResult is the browser-observed evidence that the Drive quickstart reached content-ready, beyond merely rendering the file browser frame.

func WaitForDriveReady 

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

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

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 E2EWasmCompiler added in v0.51.8 

type E2EWasmCompiler string

E2EWasmCompiler selects the browser Go compiler used by e2e/wasm. 

const (
	// E2EWasmCompilerGo keeps the default Bldr browser Go compiler.
	E2EWasmCompilerGo E2EWasmCompiler = "go"
	// E2EWasmCompilerTinyGo selects TinyGo for spacewave-core.
	E2EWasmCompilerTinyGo E2EWasmCompiler = "tinygo"
	// E2EWasmCompilerGoScript selects GoScript for browser launcher/core.
	E2EWasmCompilerGoScript E2EWasmCompiler = "goscript"
)

func ResolveE2EWasmCompiler added in v0.51.8 

func ResolveE2EWasmCompiler() (E2EWasmCompiler, error)

ResolveE2EWasmCompiler resolves the browser Go compiler for local harness runs.

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 choose NewClean* or NewRetainedState* helpers at the call site.

func Boot 

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

Boot starts the full wasm app lifecycle: builds the devtool bus, syncs dist sources, loads and optionally mutates the project config, starts the 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) BrowserName added in v0.51.7 

func (h *Harness) BrowserName() string

BrowserName returns the Playwright browser type selected for this harness.

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 browser instance. The browser process is shared across all test sessions. NewClean* helpers create a fresh BrowserContext; NewRetainedState* helpers reuse the harness context.

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 deprecated 

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

NewBlankSession creates an isolated blank browser session.

Deprecated: use NewCleanBlankSession so call sites communicate that they require clean browser storage and a dedicated WASM process.

func (*Harness) NewCleanBlankSession added in v0.51.7 

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

NewCleanBlankSession creates a fresh BrowserContext and page, but does not load the app or connect SDK resources.

func (*Harness) NewCleanPageSession added in v0.51.7 

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

NewCleanPageSession creates a fresh BrowserContext, loads the app, and leaves SDK resources disconnected. Use this for browser-only tests that still require clean storage and a dedicated WASM process.

func (*Harness) NewCleanSession added in v0.51.7 

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

NewCleanSession creates a Resource SDK session with a fresh BrowserContext, clean browser storage, a dedicated WASM process, and SDK resource connections through the devtool bus. Use this when the test requires strict browser-state isolation.

func (*Harness) NewPageSession deprecated 

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

NewPageSession creates an isolated browser-only session.

Deprecated: use NewCleanPageSession so call sites communicate that they require clean browser storage and a dedicated WASM process.

func (*Harness) NewRetainedStateBlankSession added in v0.51.7 

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

NewRetainedStateBlankSession creates a blank page on the package-level warm BrowserContext. Each call creates a fresh Page and registers cleanup for page-owned handles only; the retained context is released by Harness.Release. Use this only when the test can run against retained browser storage and the existing WASM process.

func (*Harness) NewRetainedStatePageSession added in v0.51.7 

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

NewRetainedStatePageSession creates a page-only session on the package-level warm BrowserContext and loads the app. Use this only when the test can run against retained browser storage and the existing WASM process.

func (*Harness) NewRetainedStateSession added in v0.51.7 

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

NewRetainedStateSession creates a Resource SDK session on the warm retained BrowserContext. This is an opt-in startup optimization helper; clean-session helpers keep strict BrowserContext, storage, and WASM process isolation.

func (*Harness) NewSession deprecated 

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

NewSession creates an isolated browser session for a single test.

Deprecated: use NewCleanSession so call sites communicate that they require clean browser storage and a dedicated WASM process.

func (*Harness) NewSharedPageSession deprecated added in v0.51.7 

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

NewSharedPageSession creates a page-only session on the package-level warm BrowserContext.

Deprecated: use NewRetainedStatePageSession so call sites explicitly acknowledge retained browser state.

func (*Harness) NewSharedSession deprecated added in v0.51.7 

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

NewSharedSession creates a Resource SDK session on the package-level warm BrowserContext.

Deprecated: use NewRetainedStateSession so call sites explicitly acknowledge retained browser state.

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 LocalOnboardingScenario added in v0.51.3 

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

LocalOnboardingScenario records the local session created by the quickstart flow and completed through the local onboarding UI.

func CreateLocalOnboardingScenario added in v0.51.3 

func CreateLocalOnboardingScenario(t testing.TB, h *Harness, session *TestSession) *LocalOnboardingScenario

CreateLocalOnboardingScenario creates a local drive, follows the setup banner through the plan and setup pages, downloads a backup PEM, and sets the session lock mode to PIN.

func (*LocalOnboardingScenario) GetSession added in v0.51.3 

func (s *LocalOnboardingScenario) GetSession() *TestSession

GetSession returns the owning test session.

func (*LocalOnboardingScenario) GetSessionIndex added in v0.51.3 

func (s *LocalOnboardingScenario) GetSessionIndex() uint32

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

func (*LocalOnboardingScenario) GetSpaceID added in v0.51.3 

func (s *LocalOnboardingScenario) GetSpaceID() string

GetSpaceID returns the created space identifier from the quickstart route.

type MultiSessionScenario added in v0.51.7 

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

MultiSessionScenario records two local sessions created inside one browser context for session switching and lock/unlock trajectories.

func CreateMultiSessionScenario added in v0.51.7 

func CreateMultiSessionScenario(t testing.TB, h *Harness, session *TestSession) *MultiSessionScenario

CreateMultiSessionScenario creates a PIN-backed local drive session and a second local session in the same browser context.

func (*MultiSessionScenario) ExitToSessionSelector added in v0.51.7 

func (s *MultiSessionScenario) ExitToSessionSelector(t testing.TB)

ExitToSessionSelector follows the same selector route used by local session switch and lock commands.

func (*MultiSessionScenario) GetFirstSessionIndex added in v0.51.7 

func (s *MultiSessionScenario) GetFirstSessionIndex() uint32

GetFirstSessionIndex returns the PIN-backed drive session index.

func (*MultiSessionScenario) GetFirstSpaceID added in v0.51.7 

func (s *MultiSessionScenario) GetFirstSpaceID() string

GetFirstSpaceID returns the drive Space created for the first session.

func (*MultiSessionScenario) GetSecondSessionIndex added in v0.51.7 

func (s *MultiSessionScenario) GetSecondSessionIndex() uint32

GetSecondSessionIndex returns the second local session index.

func (*MultiSessionScenario) GetSession added in v0.51.7 

func (s *MultiSessionScenario) GetSession() *TestSession

GetSession returns the browser context and Resource SDK owner.

func (*MultiSessionScenario) LockFirstSessionAtNestedRoute added in v0.51.7 

func (s *MultiSessionScenario) LockFirstSessionAtNestedRoute(t testing.TB)

LockFirstSessionAtNestedRoute locks the first session while the browser is on its nested drive route and waits for the PIN overlay.

func (*MultiSessionScenario) OpenFirstDrive added in v0.51.7 

func (s *MultiSessionScenario) OpenFirstDrive(t testing.TB)

OpenFirstDrive opens the first session's drive Space as a nested route.

func (*MultiSessionScenario) SwitchToSession added in v0.51.7 

func (s *MultiSessionScenario) SwitchToSession(t testing.TB, sessionIndex uint32)

SwitchToSession opens a session from the selector and waits for its route.

func (*MultiSessionScenario) UnlockVisiblePIN added in v0.51.7 

func (s *MultiSessionScenario) UnlockVisiblePIN(t testing.TB)

UnlockVisiblePIN unlocks the currently visible PIN overlay.

func (*MultiSessionScenario) WaitForLocalBadge added in v0.51.7 

func (s *MultiSessionScenario) WaitForLocalBadge(t testing.TB)

WaitForLocalBadge waits for the account bottom-bar badge to report LOCAL.

type Option 

type Option func(*options)

Option configures the Harness.

func WithBrowserName added in v0.51.7 

func WithBrowserName(name string) Option

WithBrowserName chooses the Playwright browser type used by LaunchBrowser. Supported values are "chromium", "firefox", and "webkit".

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 WithGoScriptBrowserStartup added in v0.51.8 

func WithGoScriptBrowserStartup() Option

WithGoScriptBrowserStartup enables the production-shaped browser GoScript startup surface used by staging: launcher plus core, without dev-only debug.

func WithGoScriptCore added in v0.51.8 

func WithGoScriptCore() Option

WithGoScriptCore enables GoScript for the browser spacewave-core Manifest.

func WithHeadless 

func WithHeadless(headless bool) Option

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

func WithManifestBuildTimeout added in v0.51.7 

func WithManifestBuildTimeout(timeout time.Duration) Option

WithManifestBuildTimeout controls how long Boot waits for startup Manifest builds before failing.

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).

func WithStartupBuildCache added in v0.51.7 

func WithStartupBuildCache(enabled bool) Option

WithStartupBuildCache controls whether Boot preserves the world-backed startup Manifest build cache across harness processes.

func WithTinyGoCore added in v0.51.7 

func WithTinyGoCore() Option

WithTinyGoCore enables TinyGo for the browser spacewave-core Manifest.

func WithWorkerMode added in v0.51.7 

func WithWorkerMode(mode WorkerMode) Option

WithWorkerMode chooses whether the browser runtime uses dedicated workers or SharedWorkers.

type PeerWaitTiming added in v0.51.5 

type PeerWaitTiming struct {
	StartedAt           time.Time
	CompletedAt         time.Time
	PeerID              peer.ID
	ObservationSequence uint64
	ObservationAge      time.Duration
	Err                 string
}

PeerWaitTiming records one wait for a browser peer mount observation.

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 sequencing peer observations and blocking until a browser 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) LatestSequence added in v0.51.6 

func (pw *PeerWatcher) LatestSequence() uint64

LatestSequence returns the latest peer observation sequence number. Callers can use it as a checkpoint before triggering a browser action.

func (*PeerWatcher) Release 

func (pw *PeerWatcher) Release()

Release removes the handler from the bus.

func (*PeerWatcher) WaitForDistinctPeerObservationAfter added in v0.52.0 

func (pw *PeerWatcher) WaitForDistinctPeerObservationAfter(
	ctx context.Context,
	afterSeq uint64,
	exclude ...peer.ID,
) (BrowserPeerObservation, error)

WaitForDistinctPeerObservationAfter blocks until an observation in arrival order arrives whose sequence is greater than afterSeq and whose peer is not in exclude. A peer can reconnect with the same ID, so a test attributing a second browser must skip the first browser's reconnect events rather than take the newest pending observation.

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.

func (*PeerWatcher) WaitForPeerObservation added in v0.51.5 

func (pw *PeerWatcher) WaitForPeerObservation(ctx context.Context) (BrowserPeerObservation, error)

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

func (*PeerWatcher) WaitForPeerObservationAfter added in v0.51.6 

func (pw *PeerWatcher) WaitForPeerObservationAfter(
	ctx context.Context,
	afterSeq uint64,
) (BrowserPeerObservation, error)

WaitForPeerObservationAfter blocks until a browser peer mount event with a sequence greater than afterSeq arrives.

type ResourceConnectionAttemptTiming added in v0.51.5 

type ResourceConnectionAttemptTiming struct {
	StartedAt   time.Time
	CompletedAt time.Time
	PeerID      peer.ID
	Err         string
}

ResourceConnectionAttemptTiming records one Resource SDK connection attempt against a browser peer.

type ResourceConnectionTiming added in v0.51.5 

type ResourceConnectionTiming struct {
	StartedAt   time.Time
	CompletedAt time.Time
	Err         string

	PeerWaits      []PeerWaitTiming
	Attempts       []ResourceConnectionAttemptTiming
	StartupReloads int
}

ResourceConnectionTiming records the devtool-to-browser resource connection lifecycle for one TestSession.

func (ResourceConnectionTiming) Elapsed added in v0.51.5 

func (t ResourceConnectionTiming) Elapsed() time.Duration

Elapsed returns the total measured resource connection duration.

type TestSession 

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

TestSession holds one browser page and optional resource connections for a single test. Clean-session helpers allocate a fresh BrowserContext; retained state helpers reuse the harness-owned warm BrowserContext.

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 route 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) ReplacePageInCurrentContext added in v0.51.7 

func (s *TestSession) ReplacePageInCurrentContext() error

ReplacePageInCurrentContext closes the current page and opens a fresh page in the same BrowserContext. Clean sessions keep their isolated context; retained sessions keep the retained warm context.

func (*TestSession) ReplacePageInRetainedContext deprecated added in v0.51.6 

func (s *TestSession) ReplacePageInRetainedContext() error

ReplacePageInRetainedContext closes the current page and opens a fresh page in the same BrowserContext.

Deprecated: use ReplacePageInCurrentContext so clean-session call sites do not imply that they opted into shared retained state.

func (*TestSession) ResourceClient 

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

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

func (*TestSession) ResourceConnectionTiming added in v0.51.5 

func (s *TestSession) ResourceConnectionTiming() ResourceConnectionTiming

ResourceConnectionTiming returns a snapshot of the latest resource connection timing for the session.

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) WatchConsole added in v0.51.3 

func (s *TestSession) WatchConsole() (<-chan string, func())

WatchConsole returns browser and worker console messages emitted after it is called.

func (*TestSession) Workers 

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

Workers returns a snapshot of the tracked page workers.

type WorkerMode added in v0.51.7 

type WorkerMode string

WorkerMode selects the browser worker topology used by the harness. 

const (
	// WorkerModeDedicated forces dedicated workers for local debugging.
	WorkerModeDedicated WorkerMode = "dedicated"
	// WorkerModeShared keeps SharedWorker topology when the browser supports it.
	WorkerModeShared WorkerMode = "shared"
)

func ResolveE2EWasmWorkerMode added in v0.51.7 

func ResolveE2EWasmWorkerMode(explicit WorkerMode) (WorkerMode, error)

ResolveE2EWasmWorkerMode resolves the local worker topology.

Source Files

View all Source files

Directories

Path Synopsis
internal
configjson
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.