behaviourfail

package
v0.57.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package behaviourfail classifies behaviour-suite failures as infrastructure (environment: setup, provisioning, rate limits, quotas) or scenario (the assertion itself) failures.

It is the leaf of the classification layout: producers whose errors are context-dependent (install drivers, e2etest bootstrap) mark errors with Mark, and consumers detect the mark with Is. The package imports only the standard library so every producer can import it without dependency cycles; the composite classifier that recognizes structural error types lives in pkg/behaviourtest/failclass.

Recorder accumulates classified failures for one suite run; the suite shares a single recorder across concurrent scenarios and renders a Report at completion.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Is

func Is(err error) bool

Is reports whether err is, or wraps, an InfraError — that is, whether a producer marked its cause as an infrastructure failure. It returns false for nil and unmarked errors.

func Mark

func Mark(err error, reason string) error

Mark wraps err as an infrastructure failure with the given reason, e.g. Mark(err, "setup: repo never visible"). It returns nil when err is nil, so marking can never invent a failure. The wrapped error's message is preserved and the cause stays reachable through errors.Is and errors.As; detect the mark with Is.

Types

type Class

type Class string

Class is the classification of a behaviour-suite failure: an environment condition (Infrastructure) or a product assertion failure (Scenario).

const (
	// Infrastructure marks a failure caused by the environment rather
	// than the system under test: setup, provisioning, rate limiting, or
	// quota exhaustion.
	Infrastructure Class = "infrastructure"

	// Scenario marks a failure of the scenario's own assertion — the
	// observed state did not match the expected state.
	Scenario Class = "scenario"

	// Success is the run-level class of a clean run: no failure was
	// recorded and the suite runner exited zero. It appears only as the
	// completion report's class, never as a per-failure record class,
	// which is why Recorder.Counts does not count it.
	Success Class = "success"
)

type FailureRecord

type FailureRecord struct {
	// Source labels where the failure originated: "scenario" for a
	// failed scenario, "bootstrap" for a suite-startup failure.
	Source string `json:"source"`

	// Scenario is the failing scenario's name, empty for bootstrap
	// failures that occur before any scenario runs.
	Scenario string `json:"scenario"`

	// Feature is the failing scenario's feature file as godog names it
	// (e.g. "features/triage/labels.feature"), empty for bootstrap
	// failures. A retried run reads it to rerun only the failed
	// scenarios.
	Feature string `json:"feature,omitempty"`

	// Class is the failure's classification.
	Class Class `json:"class"`

	// Message is the failure's redacted message. Callers must redact
	// before recording — this package is stdlib-only and cannot import
	// the suite's redaction utilities.
	Message string `json:"message"`
}

FailureRecord is one classified failure in a run's Report.

type InfraError

type InfraError struct {
	// Reason names the infrastructure failure mode that caused the mark,
	// e.g. "setup: repo never visible". It is included in the error
	// message for diagnosis; classification only needs the mark itself.
	Reason string
	// contains filtered or unexported fields
}

InfraError marks an error as an infrastructure failure. Producers create it with Mark; consumers detect it with Is or errors.As into a *InfraError to read Reason.

func (*InfraError) Error

func (e *InfraError) Error() string

Error returns the marked error's message: the infrastructure label, the reason, and the wrapped error's message.

func (*InfraError) Unwrap

func (e *InfraError) Unwrap() error

Unwrap returns the wrapped error so errors.Is and errors.As traverse the cause chain.

type Recorder

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

Recorder accumulates classified failures for one suite run. Scenario worlds share a single Recorder by pointer and scenarios run concurrently, so every method is concurrency-safe. Every method is also nil-receiver-safe: an uninitialized Recorder records nothing and reports zero counts, so hand-built Worlds keep working.

func (*Recorder) Counts

func (r *Recorder) Counts() (infrastructure, scenario int)

Counts returns the number of recorded infrastructure and scenario failures.

func (*Recorder) RecordFailure

func (r *Recorder) RecordFailure(source, scenario string, class Class, msg string)

RecordFailure appends one classified failure. msg must already be redacted; the recorder stores it verbatim.

func (*Recorder) RecordScenarioFailure

func (r *Recorder) RecordScenarioFailure(feature, scenario string, class Class, msg string)

RecordScenarioFailure appends one classified failure of a scenario (source "scenario") together with its feature file, so a retried run can rerun just that scenario. msg must already be redacted.

func (*Recorder) Report

func (r *Recorder) Report(runClass Class) Report

Report builds the completion report for a run classified as runClass. The run class is the caller's decision — the recorder observes failures, not the run outcome — so the runner derives it and the recorder contributes the counts and failure records. Pass Success for a clean run; the runner writes that report too, so a fresh marker always exists at completion and staleness stays detectable.

func (*Recorder) Snapshot

func (r *Recorder) Snapshot() []FailureRecord

Snapshot returns a copy of the recorded failures in recording order, or nil when nothing has been recorded.

type Report

type Report struct {
	// Class is the run classification reported for the whole run: a
	// failed run is Scenario when any recorded failure is
	// scenario-classified and Infrastructure when at least one failure
	// is recorded with none scenario-classified; a clean run reports
	// Success.
	Class Class `json:"class"`

	// InfrastructureFailures is the count of recorded infrastructure
	// failures.
	InfrastructureFailures int `json:"infrastructure_failures"`

	// ScenarioFailures is the count of recorded scenario failures.
	ScenarioFailures int `json:"scenario_failures"`

	// Failures lists every recorded failure in recording order. It is
	// never nil, so it marshals as an empty JSON array rather than null.
	Failures []FailureRecord `json:"failures"`
}

Report is the machine-readable failure-class report written when a suite run completes. The infra-retry wrapper script reads the class field to decide whether a failed run may be retried once.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL