github.com/google/go-cmp v0.5.0: cmp.AllowUnexported

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 github.com/google/go-cmp/cmp.AllowUnexported in pkg:golang/github.com/google/go-cmp@v0.5.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/google/go-cmp@v0.5.0
Demonstrate these symbols/APIs:
  - github.com/google/go-cmp/cmp.AllowUnexported

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:10293c552d70a96f322c30060b6db163e44b74e38b81b7e798e9eda27432aa51","contract":["cmp.Equal panics on structs with unexported fields when cmp.AllowUnexported is omitted","cmp.AllowUnexported(T{}) enables cmp.Equal to inspect unexported fields of struct T","cmp.Diff with cmp.AllowUnexported reports differences in unexported struct fields","cmp.AllowUnexported is not recursive: nested structs with unexported fields require listing each struct type","cmp.AllowUnexported panics if given a non-struct value or a pointer to a struct"],"goal":"verify github.com/google/go-cmp/cmp.AllowUnexported in pkg:golang/github.com/google/go-cmp@v0.5.0","kind":"HOW","packages":["pkg:golang/github.com/google/go-cmp@v0.5.0"],"schemaVersion":1,"symbols":["github.com/google/go-cmp/cmp.AllowUnexported"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/google/go-cmp@v0.5.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/google/go-cmp@v0.5.0","symbols":["github.com/google/go-cmp/cmp.AllowUnexported"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.22

require github.com/google/go-cmp v0.5.0

github.com/google/go-cmp v0.5.0 h1:/QaMHBdZ26BB3SSst0Iwl10Epc+xhTquomWX0oZEB6w=
github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

package sample

import (
	"fmt"

	"github.com/google/go-cmp/cmp"
)

// Parcel holds an exported identifier and an unexported weight in grams.
type Parcel struct {
	Code   string
	weight int
}

// NewParcel constructs a Parcel with both exported and unexported fields set.
func NewParcel(code string, weight int) Parcel {
	return Parcel{
		Code:   code,
		weight: weight,
	}
}

// Crate holds an exported bay number and an unexported nested Parcel.
type Crate struct {
	Bay    int
	parcel Parcel
}

// NewCrate constructs a Crate containing an unexported Parcel.
func NewCrate(bay int, parcel Parcel) Crate {
	return Crate{
		Bay:    bay,
		parcel: parcel,
	}
}

// EqualParcels compares two Parcel values using cmp.AllowUnexported.
func EqualParcels(a, b Parcel) bool {
	return cmp.Equal(a, b, cmp.AllowUnexported(Parcel{}))
}

// DiffParcels returns the cmp.Diff output between two Parcel values using cmp.AllowUnexported.
func DiffParcels(a, b Parcel) string {
	return cmp.Diff(a, b, cmp.AllowUnexported(Parcel{}))
}

// EqualCrates compares two Crate values allowing unexported fields on both Crate and Parcel.
func EqualCrates(a, b Crate) bool {
	return cmp.Equal(a, b, cmp.AllowUnexported(Crate{}, Parcel{}))
}

// EqualWithoutOption attempts cmp.Equal on two Parcel values without AllowUnexported and returns any panic message.
func EqualWithoutOption(a, b Parcel) (panicText string) {
	defer func() {
		if r := recover(); r != nil {
			panicText = fmt.Sprint(r)
		}
	}()
	cmp.Equal(a, b)
	return ""
}

// SafeAllowUnexported calls cmp.AllowUnexported with arbitrary arguments and returns any panic message.
func SafeAllowUnexported(types ...interface{}) (opt cmp.Option, panicText string) {
	defer func() {
		if r := recover(); r != nil {
			panicText = fmt.Sprint(r)
		}
	}()
	opt = cmp.AllowUnexported(types...)
	return opt, ""
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/google/go-cmp/cmp.AllowUnexported in pkg:golang/github.com/google/go-cmp@v0.5.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/google/go-cmp@v0.5.0"
  ],
  "symbols": [
    "github.com/google/go-cmp/cmp.AllowUnexported"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	"example.com/sample"
	"github.com/google/go-cmp/cmp"
)

func main() {
	if err := verifyContract(); err != nil {
		fmt.Fprintf(os.Stderr, "contract failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("contract verified")
}

func verifyContract() error {
	p1 := sample.NewParcel("PKG-100", 250)
	p2 := sample.NewParcel("PKG-100", 250)
	p3 := sample.NewParcel("PKG-100", 500)

	// 1. cmp.Equal panics on structs with unexported fields when cmp.AllowUnexported is omitted
	panicMsg := sample.EqualWithoutOption(p1, p2)
	if !strings.Contains(panicMsg, "cannot handle unexported field") {
		return fmt.Errorf("expected unexported-field panic without AllowUnexported, got %q", panicMsg)
	}

	// 2. cmp.AllowUnexported(T{}) enables cmp.Equal to inspect unexported fields of struct T
	if !sample.EqualParcels(p1, p2) {
		return fmt.Errorf("expected identical Parcel values to compare equal with AllowUnexported")
	}
	if sample.EqualParcels(p1, p3) {
		return fmt.Errorf("expected Parcel values with different unexported weights to compare unequal")
	}

	// 3. cmp.Diff with cmp.AllowUnexported reports differences in unexported struct fields
	if diff := sample.DiffParcels(p1, p2); diff != "" {
		return fmt.Errorf("expected empty diff for equal Parcel values, got %q", diff)
	}
	diffUnequal := sample.DiffParcels(p1, p3)
	if !strings.Contains(diffUnequal, "250") || !strings.Contains(diffUnequal, "500") {
		return fmt.Errorf("expected diff to contain unexported weight values 250 and 500, got %q", diffUnequal)
	}

	// 4. cmp.AllowUnexported is not recursive: nested structs with unexported fields require listing each struct type
	c1 := sample.NewCrate(1, p1)
	c2 := sample.NewCrate(1, p2)
	c3 := sample.NewCrate(1, p3)
	if !sample.EqualCrates(c1, c2) {
		return fmt.Errorf("expected identical Crate values to compare equal when both Crate and Parcel are allowed")
	}
	if sample.EqualCrates(c1, c3) {
		return fmt.Errorf("expected Crate values with differing nested Parcel weights to compare unequal")
	}
	outerOnlyPanicked := func() (msg string) {
		defer func() {
			if r := recover(); r != nil {
				msg = fmt.Sprint(r)
			}
		}()
		cmp.Equal(c1, c2, cmp.AllowUnexported(sample.Crate{}))
		return ""
	}()
	if !strings.Contains(outerOnlyPanicked, "cannot handle unexported field") {
		return fmt.Errorf("expected panic when only outer struct is passed to AllowUnexported, got %q", outerOnlyPanicked)
	}

	// 5. cmp.AllowUnexported panics if given a non-struct value or a pointer to a struct
	if _, ptrPanic := sample.SafeAllowUnexported(&sample.Parcel{}); !strings.Contains(ptrPanic, "invalid struct type") {
		return fmt.Errorf("expected invalid struct type panic for struct pointer, got %q", ptrPanic)
	}
	if _, intPanic := sample.SafeAllowUnexported(123); !strings.Contains(intPanic, "invalid struct type") {
		return fmt.Errorf("expected invalid struct type panic for non-struct value, got %q", intPanic)
	}

	return nil
}