From 5d9227d1f69bdccbfddb2c62dc146fb4c4bdd363 Mon Sep 17 00:00:00 2001
From: Haihan Jiang <haihanj99@gmail.com>
Date: Mon, 25 May 2026 21:40:01 -0700
Subject: [PATCH] Document golden test update workflow

---
 README.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/README.md b/README.md
index d2c5b461..285bb67b 100644
--- a/README.md
+++ b/README.md
@@ -150,6 +150,29 @@ bazel build //cmd/wasm:libjsonnet.wasm
 ./tests.sh  # Also runs `go test ./...`
 ```
 
+### Adding and updating golden tests
+
+Most language behavior tests live in `testdata/` as pairs of Jsonnet input
+files and `.golden` expected-output files. To add a new core language test, add
+`testdata/<name>.jsonnet`, then regenerate and review the matching golden file:
+
+```bash
+go test . -run TestEval -update
+```
+
+Formatter and linter golden tests use the same update flag in their own
+packages:
+
+```bash
+go test ./formatter -run TestFormatter -update
+go test ./linter -run TestLinter -update
+```
+
+The formatter and linter update runs intentionally report a `Goldens_Updated`
+subtest failure so the list of changed files is visible in the test output.
+Always review the generated `.golden`, `.fmt.golden`, or `.linter.golden`
+changes before committing them, then run `go test ./...` or `./tests.sh`.
+
 ## Running Benchmarks
 
 ### Method 1