Gost-DOM
A headless browser for Go

The Go-to solution for a TDD workflow.

Gost-DOM is a development tool to help building web applications in Go by providing a blazingly fast, completely reliable, feedback loop.

By simulating a browser envinronment in the test itself, including JavaScript execution¹, Gost-DOM allows you to write an automated test suite, and run them so fast enough that they become a useful feedback tool while implementing behaviour.

Gost-DOM is the headless browser that provides sub-second feedback with 100% predictable code execution.

To learn more, read Why Gost-DOM?

Why not use ...

The typical solution relies on browser automation (e.g., playwright). These have a significant overhead controlling a remote browser. In addition, developers often struggle with erratic tests due to unpredictable code execution.

As a result, these types of tests are typically written after the fact, when the system already works.

These tests didn't provide any value as a feedback tool during development.

Not a replacement

Gost-DOM allows verification of individual pieces of behaviour during development, but it's not a full browser, e.g., you cannot export screen shots.

In addition, there are sensible tests to write after features were developed, e.g., test a complete web-shop order flow from login to check-out. Using a real browser for these types of tests would be sensible; and verifying in all browsers you support.

Other Benefits of Gost-DOM

Gost-DOM has a few additional benefits over browser automation:

• Tests run in parallel due to complete isolation²
• No erratic behaviour; 100% predictable UI reactions.
• Blazingly fast.³ No out-of-process calls, not even thread boundaries for web API calls as web application code runs in the test thread.⁴
• Dependencies can be replaced in tests.
• Write tests at a higher level of abstraction, expressing the expected behaviour of a system, decoupled from implementation details.

Gost-DOM still uses HTTP request and responses for verification, testing the entire stack, including how middlewares affect the behaviour, verifying, and supporting refactoring of e.g., authentication logic.

Getting started

• Read Getting Started
• Familiarize yourself with the Feature list to know what is implemented.
• Join my discord server to chat with me, and stay up-to-date on progress.
• say hi! on the github discussions page.
• Read the contribution guide to see how you can help.

Also, check out the Shaman module which provides capabilities of querying the DOM at a higher level of abstraction, e.g., find an element with a specific label / accessibility name, allowing tests to be more expressive

[!NOTE]

This is 0.x version still, and breaking API changes do occur, but will be announced before release in the Gost-DOM discussions (do say Hi! 👋)

Looking for sponsors

This project is the spare time project for a single developer making good progress because of too much spare time; but that will not last.

If I could find enough sponsors, it could mean the difference between continued development, or death 😢

For companies wanting to sponsor, I can send formal invoices too. More information on the project's Sponsor page

Attribution / 3rd party included code.

Some web APIs are implemented by embedding polyfills from other open-source JavaScript libraries.

• XPath evaluator uses code from the jsdom project distributed under the MIT license.
• FastestSmallestTextEncoderDecoder distributed under the Creative Commons Zero v1.0 Universal license.

In addition, to verify compatibility with 3rd party JavaScript libraries, the test code in repository contains compiled versions of:

• HTMX distributed under the Zero-Clause BSD license.
• Datastar distributed under the MIT license.

Star History

---

Footnotes

1. Gost-DOM can use V8 - the same JavaScript engine that powers Chrome; but a native Go alternative also exists. ↩

2. Complete isolation depends on your code, e.g., if you don't replace database dependencies, tests are not isolated. ↩

3. Cliché, I know! But it is! ↩

4. This depends on how you configure Gost-DOM. ↩