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

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