std.test.assertGolden

assertGolden(path, actual) accepts two strings. Read the existing file as UTF-8 and compare the entire decoded text with actual. UTF-8 validity and text preservation follow UTF-8 decoding →. Equal text returns unit without printing.

Resolve the path using the same host path and read permission rules as filesystem text reads. For an ordinary installed CLI program, a relative path starts at the process working directory. The source file directory does not replace that directory.

Comparison preserves every scalar and line ending. CRLF and LF differ. A final newline, a byte order mark, Unicode spelling, and an empty file remain significant. Invalid UTF-8 is a read failure.

Evaluate the path expression and then the actual expression, once each, before reading the file. Open and read the expected text once. Release any opened resource before returning or reporting a read or comparison failure.

The assertion needs read access. It never creates a missing golden file, replaces its contents, or enables an update mode. Write a chosen expected result explicitly through the filesystem API.

Missing files, directories that cannot be read as text, permission denial, and invalid UTF-8 raise TPZ4007 at the assertion call. File failures identify the path and whether opening or reading failed. The host detail explains the cause and may vary by platform.

The file failure messages have these forms.

assertGolden failed: could not open `{path}`: {detail}
assertGolden failed: could not read `{path}`: {detail}

Unequal text raises TPZ4007 and stops the current test before its next statement. The message has this form.

assertGolden failed: `{path}` did not match actual output

Earlier argument effects remain visible after failure. Reading does not promise a snapshot across concurrent host writes. Keep the expected file unchanged while the assertion reads it.