Getting started

[stroiman]

Some parts of this code is growing more mature; the general API seems to have settled well around function New(...BrowserOption). I generally passing the root HTTP handler as input to bypass the TCP stack for reduced overhead (see caveat in the bottom)

func TestWebApplication(t *testing.T) {
    h := CreateRootHandler() // optionally mocking out services
    b := browser.New(
        browser.WithHandler(h),
    )
    defer b.Close() // Release V8 instances, and reuse V8 isolates
    win, err := b.Open("http://example.com/")
}

One could imagine many useful helper functions; but I don't want to add simple functions usable only in some cases, that can easily be created as a helper function in your own test code

func OpenWindow(t testing.TB, handler http.Handler, url string) html.Window {
    // You could optionally pass more options, e.g. log levels. Debug logs _a lot_, including all JS calls into the DOM.
    b := browser.New(
        browser.WithHandler(h),
        browser.WithLogger(loggerFromTestingT(t)),
        // Automatically disconnect http connections on cancellation
        browser.WithContext(t.Context()),
    )
    // Strictly not necessary when passing the test context. The browser will automatically close
    // when the context cancels. But this will run in the test goroutine, where context cancellation
    // runs in a new gorouting. The latter can attempt to write to the test log after the test completes.
    t.Cleanup(func() { b.Close() })
    
    w, err := b.Open(url)
    if err != nil {
        t.Fatalf("Error opening window: %v", err)
    }
    return w
}

WithLogger accepts an *slog.Logger - Go's standard for structured logging, passing log records to an slog.Handler interface. Gost-DOM has a Handler implementation that directs log output to the testing.TB.Log function. JavaScript console output will be directed to the logger at appropriate levels. console.error will result in an slog.LevelError log record.

By default the log helper will also mark a test as failed, calling TB.Fail(), if an error is logged. As a consequence, JavaScript error logs will cause the test to fail. I find this useful, as error logs typically indicate the code isn't behaving as I expect. I want to be notified, this is a potential false positive. In some cases, e.g., when tampering with cookies in CSRF test code, I can always change the default.

Caveat: when using WithHandler(), NO outgoing HTTP requests will be sent, so referencing JavaScript from e.g., a CDN will not work. The fix isn't complicated, just haven't been a priority, as my personal philosophy is to have a test suite independent of external dependencies.