webtooltest

Documentation

Overview

Package webtooltest is test support for the webtool seam: the shared contract suite every Searcher/Fetcher backend must pass (CLAUDE.md: backend variability lives behind an interface with one shared suite, as providertest, sandboxtest and blobtest do for theirs), and the opt-in gate for the live tier that calls the real backends.

The .env handling deliberately mirrors internal/modeltest rather than importing it: modeltest's contract is scoped to the model endpoint — it reads MODEL_* keys only, by design — and widening that scope for another package's keys would trade two small parsers for one leaky contract. Same rules, restated: consent to spend money is the RUN_LIVE_WEB_TESTS environment variable, never the file; the environment always wins over the file, an empty environment value included; only the two web keys are ever read from the file; not opted in, the file is never opened. Opted in but unconfigured FAILS rather than skips — a safety net that skips itself when its credentials rot is not a safety net. Production code must never import this package.

Index

• Constants
• func LiveKey(t *testing.T, keyEnv string) string
• func RunFetcherContract(t *testing.T, b FetcherBackend)
• func RunSearcherContract(t *testing.T, b SearcherBackend)
• type FetcherBackend
• type SearcherBackend

Constants

const (
	TavilyKeyEnv = "TAVILY_API_KEY"
	JinaKeyEnv   = "JINA_API_KEY"
)

The backend credential keys, read from the environment or the repo-root .env. Exactly these two — nothing else ever reaches the file.

const LiveEnv = "RUN_LIVE_WEB_TESTS"

LiveEnv opts into the live web-backend tier: one real Tavily search and one real Jina fetch (cents at most). Any non-empty value opts in.

Functions

func LiveKey

func LiveKey(t *testing.T, keyEnv string) string

LiveKey gates a live test and returns one backend's key. Not opted in: the test skips and the credential file is never opened. Opted in with the key missing: the test FAILS — each backend's key is judged on its own, so a tier with only one backend configured fails exactly the tests that need the other.

func RunFetcherContract

func RunFetcherContract(t *testing.T, b FetcherBackend)

RunFetcherContract asserts the backend-agnostic invariants every Fetcher owes the executor.

func RunSearcherContract

func RunSearcherContract(t *testing.T, b SearcherBackend)

RunSearcherContract asserts the backend-agnostic invariants every Searcher owes the executor. Protocol specifics — paths, headers, request bodies — stay in each adapter's own tests.

Types

type FetcherBackend

type FetcherBackend struct {
	// New returns a Fetcher pointed at baseURL, authenticating with key.
	New func(baseURL, key string) webtool.Fetcher
	// Render renders page content into the backend's successful wire response.
	Render func(content string) (body, contentType string)
}

FetcherBackend describes one Fetcher implementation to the contract suite.

type SearcherBackend

type SearcherBackend struct {
	// New returns a Searcher pointed at baseURL, authenticating with key.
	New func(baseURL, key string) webtool.Searcher
	// Render renders hits into the backend's successful wire response.
	Render func(hits []webtool.SearchResult) (body, contentType string)
}

SearcherBackend describes one Searcher implementation to the contract suite.