Documentation
¶
Overview ¶
Package e2e provides reusable go-rod browser helpers for E2E testing.
Projects import this package in their e2e/ test files. The package itself carries no //go:build tag — build-tag isolation happens in the consuming project.
Index ¶
- func AssertElementContainsText(t *testing.T, page *rod.Page, selector, text string)
- func AssertElementCount(t *testing.T, page *rod.Page, selector string, expected int)
- func AssertElementExists(t *testing.T, page *rod.Page, selector string)
- func AssertElementHasClass(t *testing.T, page *rod.Page, selector, class string)
- func AssertElementNotExists(t *testing.T, page *rod.Page, selector string)
- func AssertElementNotVisible(t *testing.T, page *rod.Page, selector string)
- func AssertURL(t *testing.T, page *rod.Page, expected string)
- func AssertURLContains(t *testing.T, page *rod.Page, substring string)
- func Click(t *testing.T, page *rod.Page, selector string)
- func ClickAndWaitHTMX(t *testing.T, page *rod.Page, selector string, timeout time.Duration)
- func ElementAttribute(t *testing.T, page *rod.Page, selector, attr string) string
- func ElementCount(t *testing.T, page *rod.Page, selector string) int
- func ElementExists(t *testing.T, page *rod.Page, selector string) bool
- func ElementNotExists(t *testing.T, page *rod.Page, selector string) bool
- func ElementText(t *testing.T, page *rod.Page, selector string) string
- func Input(t *testing.T, page *rod.Page, selector, value string)
- func NewPage(t *testing.T, browser *rod.Browser, url string) *rod.Page
- func SavePageHTML(t *testing.T, page *rod.Page, name string)
- func SaveScreenshot(t *testing.T, page *rod.Page, name string)
- func SelectOption(t *testing.T, page *rod.Page, selector, value string)
- func SetupBrowser(t *testing.T, opts ...Option) *rod.Browser
- func WaitForElement(t *testing.T, page *rod.Page, selector string, timeout time.Duration) *rod.Element
- func WaitForElementRemoved(t *testing.T, page *rod.Page, selector string, timeout time.Duration)
- func WaitForHTMXIdle(t *testing.T, page *rod.Page, timeout time.Duration)
- func WaitForHTMXSwap(t *testing.T, page *rod.Page, selector string, timeout time.Duration)
- func WaitForURLChange(t *testing.T, page *rod.Page, currentURL string, timeout time.Duration)
- type Config
- type Option
- func WithArtifactDir(path string) Option
- func WithBrowserPath(path string) Option
- func WithGPU(b bool) Option
- func WithHTMLDumpOnFailure(b bool) Option
- func WithHeadless(b bool) Option
- func WithNoSandbox(b bool) Option
- func WithScreenshotOnFailure(b bool) Option
- func WithSlowMotion(d time.Duration) Option
- func WithTimeout(d time.Duration) Option
- func WithWindowSize(w, h int) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AssertElementContainsText ¶
AssertElementContainsText verifies that the text content of selector contains the given substring.
func AssertElementCount ¶
AssertElementCount verifies that exactly expected elements match selector.
func AssertElementExists ¶
AssertElementExists verifies that selector matches an element on the page.
func AssertElementHasClass ¶
AssertElementHasClass verifies that the element matching selector has the given CSS class.
func AssertElementNotExists ¶
AssertElementNotExists verifies that selector does not match any element on the page.
func AssertElementNotVisible ¶
AssertElementNotVisible verifies that selector either does not exist or is not visible on the page.
func AssertURLContains ¶
AssertURLContains verifies that the page URL contains substring.
func ClickAndWaitHTMX ¶
ClickAndWaitHTMX clicks the element matching selector and waits for all HTMX requests to settle.
func ElementAttribute ¶
ElementAttribute returns the value of attr on the element matching selector. Returns an empty string if the attribute is not set. Fatals if the element is not found.
func ElementCount ¶
ElementCount returns the number of elements matching selector on the page.
func ElementExists ¶
ElementExists returns true if selector matches an element on the page.
func ElementNotExists ¶
ElementNotExists returns true if selector does not match any element on the page. Uses a short timeout to avoid waiting the full config timeout for an element that is expected to be absent.
func ElementText ¶
ElementText returns the text content of the element matching selector. Fatals if the element is not found.
func NewPage ¶
NewPage creates a new browser tab navigated to url and waits for load. On test failure the page's screenshot and HTML are captured automatically (controlled by Config). The page is closed via t.Cleanup.
func SavePageHTML ¶
SavePageHTML saves the page's HTML source to a file. It logs warnings on failure but never fails the test.
func SaveScreenshot ¶
SaveScreenshot saves a PNG screenshot of the page. It logs warnings on failure but never fails the test.
func SelectOption ¶
SelectOption selects an <option> by value inside a <select> matching selector.
func SetupBrowser ¶
SetupBrowser launches a Chromium instance configured via opts and env vars. It registers a t.Cleanup to close the browser when the test finishes.
func WaitForElement ¶
func WaitForElement(t *testing.T, page *rod.Page, selector string, timeout time.Duration) *rod.Element
WaitForElement polls for selector to appear within timeout, failing the test if not found.
func WaitForElementRemoved ¶
WaitForElementRemoved waits until no element matches selector, or timeout elapses. Useful for waiting for loading spinners or deleted rows to disappear.
func WaitForHTMXIdle ¶
WaitForHTMXIdle waits until no elements carry the htmx-request class, indicating all in-flight HTMX requests have settled. If htmx is not loaded on the page the function returns immediately.
func WaitForHTMXSwap ¶
WaitForHTMXSwap waits until the HTML content of the element matching selector changes from its initial value, indicating an HTMX swap occurred.
Types ¶
type Config ¶
type Config struct {
Headless bool // default: true, env: E2E_HEADLESS
NoSandbox bool // default: true, env: E2E_NO_SANDBOX
SlowMotion time.Duration // default: 0, env: E2E_SLOW_MOTION
Timeout time.Duration // default: 10s, env: E2E_TIMEOUT
ArtifactDir string // default: "testdata/e2e-artifacts", env: E2E_ARTIFACT_DIR
ScreenshotOnFailure bool // default: true, env: E2E_SCREENSHOT_ON_FAIL
HTMLDumpOnFailure bool // default: true, env: E2E_HTML_DUMP_ON_FAIL
GPU bool // default: false, env: E2E_GPU (false passes --disable-gpu)
BrowserPath string // default: "", env: E2E_BROWSER_PATH (empty = rod's managed Chromium)
WindowWidth int // default: 0, env: E2E_WINDOW_SIZE as "WxH" (0 = Chrome default)
WindowHeight int
}
Config controls browser lifecycle, timeouts, and artifact capture.
type Option ¶
type Option func(*Config)
Option configures a Config value.
func WithArtifactDir ¶
WithArtifactDir sets the directory for screenshots and HTML dumps.
func WithBrowserPath ¶ added in v0.36.0
WithBrowserPath uses the Chrome/Chromium binary at path instead of rod's auto-downloaded one.
func WithGPU ¶ added in v0.36.0
WithGPU enables GPU acceleration. Off by default (--disable-gpu), which is what headless CI wants; turn on for headed local runs.
func WithHTMLDumpOnFailure ¶
WithHTMLDumpOnFailure enables or disables automatic HTML dumps on test failure.
func WithHeadless ¶
WithHeadless sets whether the browser runs in headless mode.
func WithNoSandbox ¶
WithNoSandbox controls the Chrome --no-sandbox flag. Defaults to true for CI environments. Set to false when running with a proper sandbox available.
func WithScreenshotOnFailure ¶
WithScreenshotOnFailure enables or disables automatic screenshots on test failure.
func WithSlowMotion ¶
WithSlowMotion adds a delay between browser actions for debugging.
func WithTimeout ¶
WithTimeout sets the default timeout for browser operations.
func WithWindowSize ¶ added in v0.36.0
WithWindowSize sets the browser window size in pixels. Zero leaves Chrome's default.
Source Files