testutil

Documentation

Overview

Package testutil provides the shared golden-file harness for the direct-emit hook providers under internal/hooks/<provider>. The goal is a permanent regression net for the shared builder package in internal/hooks/builder: any change that alters the emitted broker.RawEvent slice or the stored blob contents for any provider fails the golden comparison on every provider that exercises the affected code path.

Goldens are committed to each provider's testdata/direct_emit directory as one JSON file per case. The file holds the expected []broker.RawEvent and a content-addressed map of blob payloads that were stored during the run. A mismatch in either field is a test failure.

Regenerating goldens rewrites committed fixtures. Run `go test ./internal/hooks/... -update`, review the diff before committing, and describe the reason for the fixture change in the commit message.

The harness also guards against silent coverage loss by checking that the set of .golden.json files on disk matches the set of cases declared in code. Stale fixtures fail the run in both comparison and update modes; a regeneration run with an orphaned file will still write the valid fixtures but will mark the run as failed so the orphan shows up in the output. Delete the stale file and rerun to get a clean pass.

Index

• func RunGolden(t *testing.T, emitter hooks.DirectHookEmitter, dir string, cases []Case)
• type CASBlobPutter
  • func NewCASBlobPutter() *CASBlobPutter
  • func (c *CASBlobPutter) Put(_ context.Context, b []byte) (string, int64, error)
• type Case

Functions

func RunGolden

func RunGolden(t *testing.T, emitter hooks.DirectHookEmitter, dir string, cases []Case)

RunGolden iterates the cases against the provider, compares each result against the matching golden file, and either fails the test or rewrites the file depending on the -update flag.

dir is the directory relative to the provider test file that holds the golden files (typically "testdata/direct_emit"). The directory is created when -update is set, so a fresh provider can generate its initial goldens without manual setup.

Before running any case, RunGolden validates that the on-disk fixtures match the declared case names exactly. A stale .golden.json file from a removed or renamed case would otherwise silently reduce coverage: the removed case no longer runs, the stale file lingers, and the test suite keeps passing with fewer assertions than the maintainer thinks. This check makes the drift loud.

Types

type CASBlobPutter

type CASBlobPutter struct {
	Stored map[string][]byte
}

CASBlobPutter is a content-addressed fake BlobPutter. Each Put returns the hex SHA-256 of the payload, which means the same content always produces the same hash regardless of Put order or the number of stored blobs. That stability is what makes the golden files meaningful across refactors that might legitimately reorder blob writes inside a builder.

func NewCASBlobPutter

func NewCASBlobPutter() *CASBlobPutter

NewCASBlobPutter returns a CASBlobPutter with an initialized store.

func (*CASBlobPutter) Put

func (c *CASBlobPutter) Put(_ context.Context, b []byte) (string, int64, error)

Put records the payload under its content hash and returns the hash. Duplicate writes collapse to one entry.

type Case

type Case struct {
	// Name is the fixture label. Becomes the golden file name.
	Name string

	// Description is an optional free-form string recorded in the
	// golden file for readers scanning the fixtures. It does not
	// participate in comparison.
	Description string

	// Event is the hook event the provider processes. Constructed in
	// the test file rather than loaded from disk so the types are
	// checked at compile time and the fixtures read like code.
	Event *hooks.Event
}

Case describes one input-to-output mapping that the golden harness exercises. Name is both the human-readable label in test output and the basename of the golden file (Name + ".golden.json").