WasmTest

WebAssembly testing helper for Go

WasmTest is a Go library that simplifies running WebAssembly (WASM) tests for Go code targeting js/wasm in a browser environment. It wraps the popular wasmbrowsertest tool, automating its installation and providing a clean API for execution with progress monitoring via callbacks. This makes it easier to integrate WASM testing into your Go projects, CI pipelines, or custom tools (e.g., TUIs).

Built for developers writing Go code that interacts with the browser DOM, JavaScript, or performs computations in WASM, WasmTest handles the boilerplate of compiling tests to WASM, serving them, and capturing output/errors from the browser.

Installation

Add WasmTest to your Go module:
```
go get github.com/cdvelop/wasmtest
```
Import in your code:
```
import "github.com/cdvelop/wasmtest"
```
WasmTest automatically ensures the underlying wasmbrowsertest binary (or go_js_wasm_exec) is installed via go install github.com/agnivade/wasmbrowsertest@latest when you create an instance with New. No manual setup needed, though you can call ensureWasmBrowserTestInstalled explicitly if desired.

The binary will be placed in $GOPATH/bin or $GOBIN. Ensure this directory is in your $PATH.

This library does not add additional indirect dependencies to your module's go.mod.

Basic Usage

Simplified API (Recommended)

For most use cases, use the ultra-simple RunTests function.

Below is the actual demo test used in this repository (RunTestsDemo_test.go). It shows the minimal call pattern the library expects. The repository also contains a ./example folder with the WebAssembly test code — see ./example/dom_test.go for the source files and test harness.

package wasmtest_test

import (
	. "github.com/cdvelop/wasmtest"
	"testing"
	"time"
)

// RunTestsDemo tests the simplified RunTests API by running tests in the example directory
func RunTestsDemo(t *testing.T) {
	// Test the simplified RunTests API - ultra simple!
	if err := RunTests("./example", func(a ...any) { t.Log(a) }, 10*time.Minute); err != nil {
		t.Errorf("RunTests failed: %v", err)
	}
}

RunTests(args ...any): Runs WebAssembly tests with optional arguments by type: string (directory), func(...any) (logger), time.Duration (timeout). Defaults: dir="wasm_tests", logger=fmt.Println, timeout=3*time.Minute

Advanced Usage

For more control, use the lower-level API:

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/cdvelop/wasmtest"
)

func main() {
	// Simple logger (variadic like fmt.Println)
	logger := func(msgs ...any) {
		log.Println(msgs...)
	}

	// Create Wasmtest instance (auto-installs wasmbrowsertest in background)
	w := wasmtest.New(logger)

	// Progress callback: receives messages like ["out", "test output"], ["err", "error msg"], ["exit", "ok"|"error"]
	progress := func(msgs ...any) {
		if len(msgs) >= 2 && msgs[0] == "out" {
			fmt.Println("Test output:", msgs[1])
		} else if len(msgs) >= 2 && msgs[0] == "exit" {
			if msgs[1] == "ok" {
				fmt.Println("Tests passed!")
			} else {
				fmt.Printf("Tests failed: %v\n", msgs[1:])
				os.Exit(1)
			}
		}
	}

	// Run WASM tests (assumes current dir has go.test files)
	// Set GOOS=js GOARCH=wasm in env for cross-compilation
	if err := w.Execute(progress); err != nil {
		log.Fatal("Execution failed:", err)
	}
}

New(logger): Initializes and starts background installation of wasmbrowsertest (non-blocking).
Execute(progressFunc): Compiles and runs tests in browser, streaming progress via the callback. Blocks until completion.
Progress messages: ["out", data], ["err", data], ["exit", "ok"|"error" [, details]].
Use w.Name() and w.Label() for tool identification (e.g., in TUIs).

For full API details, see wasmtest.go.

Advanced Usage

See docs/advanced.md for CPU profiling, running non-test code, coverage, CI integration (Travis/Github Actions), browser support, and custom progress handling.

Troubleshooting

See docs/troubleshooting.md for installation issues, environment variable limits, skipped tests, and headless mode problems.

For underlying tool details, see docs/wasmbrowsertest.md.

Contributing

License

MIT.