Documentation
¶
Overview ¶
Package webtest is a supertest-flavoured HTTP client + a react-testing-library-flavoured DOM query surface for testing hex web apps end-to-end.
Two use modes:
Direct Go tests — build a Client, chain request/assert calls:
client := webtest.New(t, app) client.Get("/dashboard"). StatusIs(200). See("Welcome, Alice"). Find(".user-card").HasClass("active"). Find("button").Count(3)
BDD/Gherkin — wire the standard step vocabulary via hex/webtest/bdd.Register, then write scenarios in .feature files.
The client boots the app once (via httptest.NewServer wrapping the Echo instance the web provider registers under "http"), then runs real requests through the real network stack. Fast enough for a tight feedback loop; realistic enough that middleware, routing, cookies, and redirects all behave the same as production.
Server-side rendering (Go templates, Jade, Markdown) is fully covered. JavaScript behaviour (Alpine, HTMX transitions on the browser side) is NOT executed — for that, a follow-up will add chromedp/rod bindings. HTMX-triggered server routes DO get exercised, since HTMX is just a normal HTTP request with special headers; use Client.Header("HX-Request", "true") to simulate the header the client would send.
Index ¶
- type Client
- func (c *Client) Body() string
- func (c *Client) BodyContains(substring string) *Client
- func (c *Client) Delete(path string) *Client
- func (c *Client) Doc() *goquery.Document
- func (c *Client) Find(sel string) *Selection
- func (c *Client) Get(path string) *Client
- func (c *Client) Header(name, value string) *Client
- func (c *Client) HeaderIs(name, value string) *Client
- func (c *Client) LocationIs(path string) *Client
- func (c *Client) Post(path string, body io.Reader, contentType string) *Client
- func (c *Client) PostForm(path string, form url.Values) *Client
- func (c *Client) PostJSON(path string, body any) *Client
- func (c *Client) Put(path string, body io.Reader, contentType string) *Client
- func (c *Client) See(text string) *Client
- func (c *Client) Status() int
- func (c *Client) StatusIs(expected int) *Client
- func (c *Client) URL() string
- type Selection
- func (s *Selection) Attr(name string) string
- func (s *Selection) Count(n int) *Selection
- func (s *Selection) DoesNotExist() *Selection
- func (s *Selection) Exists() *Selection
- func (s *Selection) Find(sel string) *Selection
- func (s *Selection) First() *Selection
- func (s *Selection) HasAttribute(name string) *Selection
- func (s *Selection) HasAttributeValue(name, want string) *Selection
- func (s *Selection) HasClass(class string) *Selection
- func (s *Selection) HasExactText(want string) *Selection
- func (s *Selection) HasText(substring string) *Selection
- func (s *Selection) Nth(n int) *Selection
- func (s *Selection) Text() string
- func (s *Selection) Underlying() *goquery.Selection
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a stateful HTTP client bound to an in-process hex app. After every request the response body is parsed as HTML (via goquery) so assertions like Find(".selector") work without a second network round-trip.
Client is NOT goroutine-safe — one Client per test scenario.
func New ¶
New starts a test HTTP server wrapping the app's Echo instance (resolved from the container under "http") and returns a Client bound to it. The server is torn down via t.Cleanup.
func (*Client) BodyContains ¶
BodyContains asserts the response body contains substring.
func (*Client) Doc ¶
Doc lazily parses the last body as HTML and returns the *goquery document. Escape hatch for callers who want the full goquery API.
func (*Client) Get ¶
Get performs a GET at path (relative to the test server root). Returns c for chaining.
func (*Client) Header ¶
Header sets a default header applied to every subsequent request. Multiple calls with the same name append values.
func (*Client) LocationIs ¶
LocationIs asserts the Location header equals path (for redirects).
func (*Client) Post ¶
Post performs a POST with a raw body. contentType is stored in the Content-Type header; pass an empty string to skip.
func (*Client) Put ¶
Put performs a PUT with the given body. Empty contentType is treated as text/plain.
func (*Client) Status ¶
Status returns the last response's HTTP status code. Fails the test if no request has been sent yet.
type Selection ¶
type Selection struct {
// contains filtered or unexported fields
}
Selection is a chainable assertion wrapper around a goquery selection. Modeled after react-testing-library's queries and Laravel's TestResponse assertions.
Every assertion method returns the same Selection so calls chain:
client.Find(".user-card").
HasClass("active").
HasText("Alice").
Count(3)
func (*Selection) Attr ¶
Attr returns the value of attribute name on the first matched element. If missing, returns "" and reports the miss (does not fail).
func (*Selection) Count ¶
Count asserts the selection contains exactly n elements. Zero asserts absence; use Exists / DoesNotExist for readability.
func (*Selection) DoesNotExist ¶
DoesNotExist asserts no elements matched the selector.
func (*Selection) Find ¶
Find scopes a further selection inside the currently selected elements — same semantics as CSS descendant combinator.
func (*Selection) HasAttribute ¶
HasAttribute asserts the selected element has attribute name (any value).
func (*Selection) HasAttributeValue ¶
HasAttributeValue asserts the attribute name equals want.
func (*Selection) HasExactText ¶
HasExactText asserts the selected element's text (trimmed) is exactly equal to want.
func (*Selection) HasText ¶
HasText asserts the selected elements' combined text content contains substring. Whitespace is not normalised — pass exactly what you expect (with mindful spacing).
func (*Selection) Underlying ¶
Underlying returns the wrapped *goquery.Selection. Escape hatch when callers need the full goquery API.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package bdd wires the hex/webtest client into a hex/bdd suite as a set of standard Gherkin step definitions, giving apps a react-testing-library-flavoured browser-test vocabulary in .feature files:
|
Package bdd wires the hex/webtest client into a hex/bdd suite as a set of standard Gherkin step definitions, giving apps a react-testing-library-flavoured browser-test vocabulary in .feature files: |