README
¶
Gost-DOM
A headless browser for Go
The Go-to solution for a TDD workflow.
As a developer
In order to work effeciently with code
I want a fast feedback loop for all of my code.
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[^1], 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[^2]
- No erratic behaviour; 100% predictable UI reactions.
- Blazingly fast.[^3] No out-of-process calls, not even thread boundaries for web API calls as web application code runs in the test thread.[^4]
- 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:
Star History
[^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.
Documentation
¶
Overview ¶
Package browser is the main entry point for Gost, helping create a window initialized with a script enging, connected to a server.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Browser ¶
type Browser struct {
Client http.Client
ScriptHost ScriptHost
Logger log.Logger
Clock *clock.Clock
// contains filtered or unexported fields
}
Browser contains an initialized browser with a script engine. Create new windows by calling Browser.Open.
Browser values should be closed by calling Browser.Close, or passing a context:
func TestBrowserWithClose(t *testing.T) {
handler := NewRootHttpHandler()
b := browser.New(browser.WithHandler(handler))
t.Cleanup(func() { b.Close() })
win, err := b.Open("http://example.com")
// ...
}
Passing a context:
func TestBrowserWithContext(t *testing.T) {
handler := NewRootHttpHandler()
b := browser.New(
browser.WithHandler(handler),
browser.WithContext(t.Context(),
)
win, err := b.Open("http://example.com")
// ...
}
func New ¶
func New(options ...BrowserOption) *Browser
New initialises a new Browser. Options can be one of
func (*Browser) Close ¶
func (b *Browser) Close()
Close "closes" a browser, releasing resources. This will close any initialized script hosts and contexts. Has two purposes.
- Reuse a template engine, reducing engine initialization overhead.
- Release memory for non-Go engines, e.g., V8
The relevance depends mostly on the script engine. For a pure Go engine, resources would be garbage collections. And the ability to reuse a preconfigured engine depends on engine capabilities.
Note: If a browser is initialized by passing a context.Context to the WithContext option, it will be closed if the context is cancelled.
func (*Browser) NewWindow ¶ added in v0.5.1
func (b *Browser) NewWindow() Window
NewWindow creates a new window. Panics if the browser has been closed
func (*Browser) Open ¶
Open will open a new html.Window, loading the specified location. If the server does not respons with a 200 status code, an error is returned.
See html.NewWindowReader about the return value, and when the window returns.
type BrowserOption ¶ added in v0.5.1
type BrowserOption func(*browserConfig)
func WithContext ¶ added in v0.8.0
func WithContext(ctx context.Context) BrowserOption
WithContext passes a context.Context than can trigger cancellation, e.g.:
- Close any open HTTP connections and disconnect from the server.
- Release resources, and reuse script hosts.
See also: Browser.Close
func WithHandler ¶ added in v0.5.1
func WithHandler(h http.Handler) BrowserOption
WithHandler configures the browser's http.Client to use an http.Roundtripper that bypasses the TCP stack and calls directly into the specified handler as a normal function call.
Note: There is a current limitation that NO requests from the browser will be sent when using this. So sites will not work if they
- Depend on content from CDN
- Depend on an external service, e.g., an identity provider.
That is a limitation that was the result of prioritising more important, and higher risk features.
func WithLogger ¶ added in v0.5.1
func WithLogger(l *slog.Logger) BrowserOption
func WithScriptEngine ¶ added in v0.9.2
func WithScriptEngine(engine html.ScriptEngine) BrowserOption
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
browser
module
|
|
|
Package dom provides the fundamental DOM implementation for Gost-DOM.
|
Package dom provides the fundamental DOM implementation for Gost-DOM. |
|
event
Package event contains core browser event behavior
|
Package event contains core browser event behavior |
|
Package html works on top of the DOM to implement specific HTML elements.
|
Package html works on top of the DOM to implement specific HTML elements. |
|
input
|
|
|
controller
Package controller can simulate user interaction
|
Package controller can simulate user interaction |
|
key
Package key represents keys on the keyboard that the user might type.
|
Package key represents keys on the keyboard that the user might type. |
|
internal
|
|
|
cache
Package cache provides the ability to cache expensive resources
|
Package cache provides the ability to cache expensive resources |
|
clock
Package clock provides a simulated time for Gost-DOM.
|
Package clock provides a simulated time for Gost-DOM. |
|
constants
Package constants is a collection of values that are used many times in the implementation, but has no relevance to users of the library, e.g., a link to where you can file an issue when you encounter a not-implemented feature; or a feature that is not fully implemented, e.g.
|
Package constants is a collection of values that are used many times in the implementation, but has no relevance to users of the library, e.g., a link to where you can file an issue when you encounter a not-implemented feature; or a feature that is not fully implemented, e.g. |
|
gosthttp
Package gosthttp provides functionality to bypass the TCP stack.
|
Package gosthttp provides functionality to bypass the TCP stack. |
|
interfaces
Package interfaces contains go interfaces generated from IDL specs
|
Package interfaces contains go interfaces generated from IDL specs |
|
interfaces/html-interfaces
Package htmlinterfaces contains internal code representing the IDL interfaces in the HTML DOM API
[HTML DOM API]: https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API
|
Package htmlinterfaces contains internal code representing the IDL interfaces in the HTML DOM API [HTML DOM API]: https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API |
|
interfaces/url-interfaces
Package urlinterfaces contains internal code representing the IDL interfaces in the URL API
[URL API]: https://developer.mozilla.org/en-US/docs/Web/API/URL_API
|
Package urlinterfaces contains internal code representing the IDL interfaces in the URL API [URL API]: https://developer.mozilla.org/en-US/docs/Web/API/URL_API |
|
log
Package log contains functions used internally for logging to a default logger implementing slog.Logger.
|
Package log contains functions used internally for logging to a default logger implementing slog.Logger. |
|
monads/result
package result provides monadic result binding
|
package result provides monadic result binding |
|
promise
Package promise provides a Go way to represent the concept of a Promise.
|
Package promise provides a Go way to represent the concept of a Promise. |
|
test/integration/test-app-main
command
|
|
|
testing/gomega-matchers
Package gomegamatchers just exposes gomega matchers for easier importing.
|
Package gomegamatchers just exposes gomega matchers for easier importing. |
|
testing/htmltest
Package htmltest contains test helpers when working with the html package
|
Package htmltest contains test helpers when working with the html package |
|
types
Package types defines fundamental web types such as ByteString
|
Package types defines fundamental web types such as ByteString |
|
uievents
Package uievents creates and dispatches [UI Events].
|
Package uievents creates and dispatches [UI Events]. |
|
Package logger provides the basic functionality of supplying a custom logger.
|
Package logger provides the basic functionality of supplying a custom logger. |
|
scripting
|
|
|
internal/js
Package js provides an abstraction on top of script engines.
|
Package js provides an abstraction on top of script engines. |
|
internal/mathml
Package mathml implements (part of) the MathML-Core web API
|
Package mathml implements (part of) the MathML-Core web API |
|
internal/scripttests
Package scripttests contains a specification of the behaviour of client-side scripting.
|
Package scripttests contains a specification of the behaviour of client-side scripting. |
|
internal/testing/jsassert
Package jsassert is a failed attempt to write assertions in JavaScript
|
Package jsassert is a failed attempt to write assertions in JavaScript |
|
sobekengine
The sobekhost package provides functionality to execute client-scripts in gost-dom.
|
The sobekhost package provides functionality to execute client-scripts in gost-dom. |
|
v8engine
The v8engine packages provides functionality to execute client-side scripts in gost-dom.
|
The v8engine packages provides functionality to execute client-side scripts in gost-dom. |
|
testing
|
|
|
gomega-matchers
Package matchers contains custom matches for use with the [Gomega] assertion library.
|
Package matchers contains custom matches for use with the [Gomega] assertion library. |
|
Package url contains types defined in the url web IDL spec.
|
Package url contains types defined in the url web IDL spec. |