browserproof

package
v1.0.24 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 26, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package browserproof drives a headless browser over a built site served on loopback and reports whether the effect promised to a user is actually on the screen. It separates three verdicts that a passing test suite conflates: the artifact proved the behavior, the artifact refused it, or the environment could not judge. Only the first is proof, and it is never inferred from a green run, from a driver that says so, or from a status code alone.

Index

Constants

View Source 
const (
	MaxRoutes             = 8
	MaxPageBytes          = 4 << 20
	MaxNavigationDeadline = 30 * time.Second
)

Limits declared by AUR-423/AC-001. A request past any of them is refused as harness diagnosis instead of being trimmed silently.

View Source 
const (
	CodeTargetAbsent     = "BROWSERPROOF_TARGET_ABSENT"
	CodeUnreachableRoute = "BROWSERPROOF_UNREACHABLE_ROUTE"
	CodeEmptyRender      = "BROWSERPROOF_EMPTY_RENDER"
	CodeTextMismatch     = "BROWSERPROOF_TEXT_MISMATCH"

	CodeDriverMismatch         = "BROWSERPROOF_DRIVER_MISMATCH"
	CodeDriverAbsent           = "BROWSERPROOF_DRIVER_ABSENT"
	CodeDriverFault            = "BROWSERPROOF_DRIVER_FAULT"
	CodeSelectorAbsent         = "BROWSERPROOF_SELECTOR_ABSENT"
	CodeServerUnavailable      = "BROWSERPROOF_SERVER_UNAVAILABLE"
	CodeNavigationTimeout      = "BROWSERPROOF_NAVIGATION_TIMEOUT"
	CodeObservationUnsupported = "BROWSERPROOF_OBSERVATION_UNSUPPORTED"
	CodeJavaScriptUnsupported  = "BROWSERPROOF_JAVASCRIPT_UNSUPPORTED"
	CodeRequestInvalid         = "BROWSERPROOF_REQUEST_INVALID"
	CodeVerdictRejected        = "BROWSERPROOF_VERDICT_REJECTED"
)

Refusal codes. CodeTargetAbsent, CodeUnreachableRoute, CodeEmptyRender and CodeTextMismatch describe the artifact under test. Every other code describes the harness or its environment and is reported as an inconclusive diagnosis, never as a functional failure and never as proof.

View Source 
const (
	AssertionPass   = "pass"
	AssertionFail   = "fail"
	AssertionNotRun = "not-run"
)

Per-route assertion results.

View Source 
const DriverPathEnv = "AURUM_BROWSERPROOF_DRIVER"

DriverPathEnv names the pinned browser driver executable.

View Source 
const ExternalDriverKind = "external-headless-v1"

ExternalDriverKind is the driver kind a production lock pins: a real headless browser reached through an external executable, identified by its digest.

View Source 
const SchemaBrowserProofResultV1 = "BrowserProofResultV1"

SchemaBrowserProofResultV1 identifies the only verdict contract this package publishes. A verdict without it is not a browser proof.

View Source 
const SchemaDocsVerifyResultV1 = "DocsVerifyResultV1"

SchemaDocsVerifyResultV1 identifies the docs-verification verdict contract.

View Source 
const ScriptedDriverKind = "scripted-test-double"

ScriptedDriverKind marks observations produced by the in-process test double instead of a real browser. A lock that pins ExternalDriverKind refuses it, so the double can never stand in for a pinned browser in a production run.

Variables

View Source 
var (
	// ErrUnsubstantiatedProof rejects a verdict that claims proof without an
	// observed selector and the text extracted from it.
	ErrUnsubstantiatedProof = errors.New("browserproof: proved verdict without an observed selector and extracted text")

	// ErrEvidenceNotSanitized rejects raw markup smuggled into the verdict.
	ErrEvidenceNotSanitized = errors.New("browserproof: verdict carries raw markup")

	// ErrDriverAbsent reports a browser driver that is not installed. It is an
	// environment diagnosis, never a functional failure.
	ErrDriverAbsent = errors.New("browserproof: browser driver is absent")
)
View Source 
var ScriptedDriverDigest = func() string {
	sum := sha256.Sum256([]byte("browserproof.ScriptedDriver/v1"))
	return "sha256:" + hex.EncodeToString(sum[:])
}()

ScriptedDriverDigest pins the identity of the double. It is the digest of the double's protocol identity, not of a browser binary.

Functions

func DriverDigestOf 

func DriverDigestOf(path string) (string, error)

DriverDigestOf fingerprints a driver executable for the lock. It resolves the path the same way the run will, so the digest names the file that runs.

Types

type BrowserProof 

type BrowserProof struct {
	// contains filtered or unexported fields
}

BrowserProof runs assertions through a Driver against a locally served build.

func New 

func New(driver Driver) *BrowserProof

func (*BrowserProof) Run 

func (b *BrowserProof) Run(ctx context.Context, req RunRequest) (BrowserProofResultV1, error)

Run serves the artifact on loopback, checks the driver against the lock, walks every declared route and asserts the selector and its text. It returns a non-nil error for every outcome that is not proof, so a caller that drops the verdict still cannot read a refusal as success.

func (*BrowserProof) VerifyDocs 

func (b *BrowserProof) VerifyDocs(ctx context.Context, req DocsVerifyRequest) (DocsVerifyResultV1, error)

VerifyDocs serves the published tree on loopback, opens the home page, follows a link of the index to a page that shows the expected content, and returns the corroborated verdict. Like Run, it returns a non-nil error for every outcome that is not proof.

type BrowserProofResultV1 

type BrowserProofResultV1 struct {
	Schema         string               `json:"schema"`
	Card           string               `json:"card,omitempty"`
	Outcome        Outcome              `json:"outcome"`
	Proved         bool                 `json:"proved"`
	Code           string               `json:"code,omitempty"`
	Detail         string               `json:"detail,omitempty"`
	ArtifactDigest string               `json:"artifact_digest"`
	DriverDigest   string               `json:"driver_digest"`
	DriverKind     string               `json:"driver_kind"`
	DriverRunsJS   bool                 `json:"driver_runs_javascript"`
	EntryRoute     string               `json:"entry_route"`
	DeadlineMs     int64                `json:"navigation_deadline_ms"`
	Routes         []RouteObservationV1 `json:"routes"`
}

BrowserProofResultV1 is the published verdict contract of this package.

func ParseResultV1 

func ParseResultV1(data []byte) (BrowserProofResultV1, error)

ParseResultV1 decodes a verdict and refuses anything it cannot substantiate, including unknown fields such as an embedded screenshot.

func (BrowserProofResultV1) Validate 

func (r BrowserProofResultV1) Validate() error

Validate rejects any verdict that does not carry the evidence it claims. A caller must run it before trusting Proved.

type DocsVerifyRequest 

type DocsVerifyRequest struct {
	// Card names the card or run this verdict is evidence for.
	Card string
	// SiteDir is the published HTML tree, served on loopback for the run.
	SiteDir string
	// PublishedURL is the public location the site is (or will be) published
	// under. It is recorded in the verdict; the navigation itself serves
	// SiteDir on loopback, because a proof run reaches no external network.
	PublishedURL string
	// IndexSelector and IndexText are what the home page must show.
	IndexSelector string
	IndexText     string
	// ContentSelector and ContentText are what a page reached through a link
	// of the index must show.
	ContentSelector    string
	ContentText        string
	DriverLock         DriverLock
	NavigationDeadline time.Duration
}

DocsVerifyRequest is one verification of one published documentation site.

type DocsVerifyResultV1 

type DocsVerifyResultV1 struct {
	Schema          string                `json:"schema"`
	Card            string                `json:"card,omitempty"`
	PublishedURL    string                `json:"published_url"`
	EntryRoute      string                `json:"entry_route"`
	FollowedLink    string                `json:"followed_link,omitempty"`
	FollowedRoute   string                `json:"followed_route,omitempty"`
	ExpectedContent string                `json:"expected_content"`
	Outcome         Outcome               `json:"outcome"`
	Proved          bool                  `json:"proved"`
	Code            string                `json:"code,omitempty"`
	Detail          string                `json:"detail,omitempty"`
	Proof           *BrowserProofResultV1 `json:"proof,omitempty"`
}

DocsVerifyResultV1 is the published verdict of a docs verification. A proved verdict always embeds the full BrowserProofResultV1 that backs it.

func ParseDocsVerifyResultV1 

func ParseDocsVerifyResultV1(data []byte) (DocsVerifyResultV1, error)

ParseDocsVerifyResultV1 decodes a docs verdict and refuses anything it cannot substantiate, including unknown fields.

func (DocsVerifyResultV1) Validate 

func (r DocsVerifyResultV1) Validate() error

Validate rejects any docs verdict that does not carry the evidence it claims. A caller must run it before trusting Proved.

type Driver 

type Driver interface {
	Fingerprint(ctx context.Context) (DriverFingerprint, error)
	Navigate(ctx context.Context, url, selector string) (PageObservation, error)
}

Driver is the headless browser seam. Implementations report observations; they never decide a verdict.

type DriverFingerprint 

type DriverFingerprint struct {
	Kind               string
	Digest             string
	ExecutesJavaScript bool
}

DriverFingerprint identifies the driver that produced an observation.

type DriverLock 

type DriverLock struct {
	Kind   string `json:"kind"`
	Digest string `json:"digest"`
}

DriverLock pins the browser that is allowed to produce a verdict.

type ExternalDriver 

type ExternalDriver struct {
	// contains filtered or unexported fields
}

ExternalDriver drives a headless browser through a pinned executable. An absent or unreadable executable is reported as ErrDriverAbsent, so a missing browser can never be mistaken for a passing assertion.

func NewExternalDriver 

func NewExternalDriver(path string) *ExternalDriver

func NewExternalDriverFromEnv 

func NewExternalDriverFromEnv() *ExternalDriver

NewExternalDriverFromEnv reads the pinned driver path from DriverPathEnv.

func (*ExternalDriver) Fingerprint 

func (d *ExternalDriver) Fingerprint(context.Context) (DriverFingerprint, error)

func (*ExternalDriver) Navigate 

func (d *ExternalDriver) Navigate(ctx context.Context, url, selector string) (PageObservation, error)

type ForgeMode 

type ForgeMode int

ForgeMode makes the double report observations the served artifact does not support. It exists so tests can prove the harness refuses driver-reported success that the local server ledger does not corroborate. 

const (
	ForgeNone ForgeMode = iota
	// ForgeClaimSuccess navigates for real and then reports success regardless
	// of what came back.
	ForgeClaimSuccess
	// ForgeWithoutFetch reports success without navigating at all.
	ForgeWithoutFetch
)

type Outcome 

type Outcome string

Outcome separates a verdict about the artifact from a verdict about the harness. Only OutcomeProved may be read as evidence that a feature works. 

const (
	OutcomeProved       Outcome = "proved"
	OutcomeRefused      Outcome = "refused"
	OutcomeInconclusive Outcome = "inconclusive"
)

type PageObservation 

type PageObservation struct {
	Status             int
	Bytes              int64
	SelectorFound      bool
	Text               string
	BodyTextLength     int
	Links              []string
	RequiresJavaScript bool
	StableAfter        time.Duration
}

PageObservation is everything a driver may report about one navigation.

type ProofError 

type ProofError struct {
	Card    string
	Code    string
	Outcome Outcome
	Detail  string
}

ProofError is returned by Run for every outcome that is not proof, so a caller that ignores the verdict still cannot read a refusal as success.

func (*ProofError) Error 

func (e *ProofError) Error() string

type RouteAssertion 

type RouteAssertion struct {
	Route        string
	Selector     string
	ExpectedText string
}

RouteAssertion declares what a user must be able to see on one route.

type RouteObservationV1 

type RouteObservationV1 struct {
	Route         string `json:"route"`
	Status        int    `json:"status"`
	Selector      string `json:"selector"`
	ExpectedText  string `json:"expected_text"`
	ObservedText  string `json:"observed_text"`
	SelectorFound bool   `json:"selector_found"`
	Reachable     bool   `json:"reachable"`
	Assertion     string `json:"assertion"`
	Code          string `json:"code,omitempty"`
	ServedBytes   int64  `json:"served_bytes"`
	ServedDigest  string `json:"served_digest,omitempty"`
	StableAfterMs int64  `json:"stable_after_ms"`
}

RouteObservationV1 is what the browser reported for one declared route. It carries the selector, the extracted text and the per-assertion result, and it never carries raw HTML or a screenshot.

type RunRequest 

type RunRequest struct {
	Card               string
	SiteDir            string
	EntryRoute         string
	Assertions         []RouteAssertion
	DriverLock         DriverLock
	NavigationDeadline time.Duration
}

RunRequest is one proof run over one built artifact.

type ScriptedDriver 

type ScriptedDriver struct {
	Forge      ForgeMode
	ForgedText string
	Delay      time.Duration
	// contains filtered or unexported fields
}

ScriptedDriver is the test double for the browser seam. It fetches over loopback only and resolves selectors without a scripting engine, which it declares through its fingerprint.

func NewScriptedDriver 

func NewScriptedDriver() *ScriptedDriver

func (*ScriptedDriver) Fingerprint 

func (d *ScriptedDriver) Fingerprint(context.Context) (DriverFingerprint, error)

func (*ScriptedDriver) Navigate 

func (d *ScriptedDriver) Navigate(ctx context.Context, url, selector string) (PageObservation, error)

Source Files

View all Source files

Directories

Path Synopsis
Command docsverify is the executable shape of the promise `aurumcode docs verify --url <published-url>` (AUR-429): after publishing, open the home page, follow a link of the index and confirm the expected content is there, instead of trusting that the file was uploaded.
 Command docsverify is the executable shape of the promise `aurumcode docs verify --url <published-url>` (AUR-429): after publishing, open the home page, follow a link of the index and confirm the expected content is there, instead of trusting that the file was uploaded.
Package sitepublish renders a generated documentation tree (the Jekyll markdown cmd/regenerate-docs writes) as the HTML tree a static host would serve, so an offline verification can navigate it.
 Package sitepublish renders a generated documentation tree (the Jekyll markdown cmd/regenerate-docs writes) as the HTML tree a static host would serve, so an offline verification can navigate it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.