gopkg.in/errgo.v2 v2.1.0: errors.Because

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify gopkg.in/errgo.v2/fmt/errors.Because in pkg:golang/gopkg.in/errgo.v2@v2.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/gopkg.in/errgo.v2@v2.1.0
Demonstrate these symbols/APIs:
  - gopkg.in/errgo.v2/fmt/errors.Because

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:322790fc28057e52345893fe687d2c0822999e034de6aaa6db89e630357d3184","contract":["Because returns nil when underlying error, cause, and msg are zero","Because wraps nil underlying error with message and preserves cause","Because returns error with cause message when underlying error is nil and msg is empty","Because wraps non-nil underlying error prefixing message to underlying error text","Because associates specified cause retrievable via errors.Cause and Causer interface","Because records caller source code location retrievable via Locator interface and Details"],"goal":"verify gopkg.in/errgo.v2/fmt/errors.Because in pkg:golang/gopkg.in/errgo.v2@v2.1.0","kind":"HOW","packages":["pkg:golang/gopkg.in/errgo.v2@v2.1.0"],"schemaVersion":1,"symbols":["gopkg.in/errgo.v2/fmt/errors.Because"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/gopkg.in/errgo.v2@v2.1.0"],"schemaVersion":1,"subject":"pkg:golang/gopkg.in/errgo.v2@v2.1.0","symbols":["gopkg.in/errgo.v2/fmt/errors.Because"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require gopkg.in/errgo.v2 v2.1.0

github.com/kr/pretty v0.1.0 h1:L/CwN0zerZDmRFUapSPitk6f+Q3+0za1rQkzVuMiMFI=
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/errgo.v2 v2.1.0 h1:0vLT13EuvQ0hNvakwLuFZ/jYrLp5F3kcWHXdRggjCE8=
gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=

package main

import (
	"errors"
	"fmt"

	errgoErrors "gopkg.in/errgo.v2/fmt/errors"
)

var ErrDatabase = errors.New("database connection failed")

func fetchRecord(id string) error {
	underlying := fmt.Errorf("network timeout connecting to db")
	return errgoErrors.Because(underlying, ErrDatabase, fmt.Sprintf("cannot fetch record %s", id))
}

func main() {
	err := fetchRecord("rec-1001")
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		fmt.Printf("Cause: %v\n", errgoErrors.Cause(err))
		fmt.Printf("Details:\n%s\n", errgoErrors.Details(err))
	}
}

{
  "schemaVersion": 1,
  "goal": "verify gopkg.in/errgo.v2/fmt/errors.Because in pkg:golang/gopkg.in/errgo.v2@v2.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/gopkg.in/errgo.v2@v2.1.0"
  ],
  "symbols": [
    "gopkg.in/errgo.v2/fmt/errors.Because"
  ]
}

package main

import (
	"errors"
	"fmt"
	"os"
	"strings"

	errgoErrors "gopkg.in/errgo.v2/fmt/errors"
)

func main() {
	// 1. Because returns nil when underlying error, cause, and msg are zero
	if err := errgoErrors.Because(nil, nil, ""); err != nil {
		fmt.Fprintf(os.Stderr, "Assertion 1 failed: expected nil, got %v\n", err)
		os.Exit(1)
	}

	// 2. Because wraps nil underlying error with message and preserves cause
	rootCause := errors.New("underlying service unavailable")
	errWithCause := errgoErrors.Because(nil, rootCause, "request failed")
	if errWithCause == nil {
		fmt.Fprintln(os.Stderr, "Assertion 2 failed: expected non-nil error")
		os.Exit(1)
	}
	if errWithCause.Error() != "request failed" {
		fmt.Fprintf(os.Stderr, "Assertion 2 failed: got %q, want %q\n", errWithCause.Error(), "request failed")
		os.Exit(1)
	}
	if errgoErrors.Cause(errWithCause) != rootCause {
		fmt.Fprintf(os.Stderr, "Assertion 2 failed: cause mismatch\n")
		os.Exit(1)
	}

	// 3. Because returns error with cause message when underlying error is nil and msg is empty
	errDefaultMsg := errgoErrors.Because(nil, rootCause, "")
	if errDefaultMsg == nil {
		fmt.Fprintln(os.Stderr, "Assertion 3 failed: expected non-nil error")
		os.Exit(1)
	}
	if errDefaultMsg.Error() != rootCause.Error() {
		fmt.Fprintf(os.Stderr, "Assertion 3 failed: got %q, want %q\n", errDefaultMsg.Error(), rootCause.Error())
		os.Exit(1)
	}
	if errgoErrors.Cause(errDefaultMsg) != rootCause {
		fmt.Fprintf(os.Stderr, "Assertion 3 failed: cause mismatch\n")
		os.Exit(1)
	}

	// 4. Because wraps non-nil underlying error prefixing message to underlying error text
	underlyingErr := errors.New("connection reset by peer")
	errWrapped := errgoErrors.Because(underlyingErr, rootCause, "operation timed out")
	if errWrapped == nil {
		fmt.Fprintln(os.Stderr, "Assertion 4 failed: expected non-nil error")
		os.Exit(1)
	}
	expectedFormatted := "operation timed out: connection reset by peer"
	if errWrapped.Error() != expectedFormatted {
		fmt.Fprintf(os.Stderr, "Assertion 4 failed: got %q, want %q\n", errWrapped.Error(), expectedFormatted)
		os.Exit(1)
	}

	// 5. Because associates specified cause retrievable via errors.Cause and Causer interface
	causer, ok := errWrapped.(errgoErrors.Causer)
	if !ok {
		fmt.Fprintln(os.Stderr, "Assertion 5 failed: error does not implement Causer")
		os.Exit(1)
	}
	if causer.Cause() != rootCause {
		fmt.Fprintf(os.Stderr, "Assertion 5 failed: Causer.Cause() mismatch\n")
		os.Exit(1)
	}
	if errgoErrors.Cause(errWrapped) != rootCause {
		fmt.Fprintf(os.Stderr, "Assertion 5 failed: Cause() mismatch\n")
		os.Exit(1)
	}

	// 6. Because records caller source code location retrievable via Locator interface and Details
	locator, ok := errWrapped.(errgoErrors.Locator)
	if !ok {
		fmt.Fprintln(os.Stderr, "Assertion 6 failed: error does not implement Locator")
		os.Exit(1)
	}
	file, line := locator.Location()
	if file == "" || line <= 0 {
		fmt.Fprintf(os.Stderr, "Assertion 6 failed: invalid location file=%q line=%d\n", file, line)
		os.Exit(1)
	}
	details := errgoErrors.Details(errWrapped)
	if !strings.Contains(details, "operation timed out") || !strings.Contains(details, "connection reset by peer") {
		fmt.Fprintf(os.Stderr, "Assertion 6 failed: Details missing context: %s\n", details)
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed.")
}