Document use of tests for resourcedocsgen tool

[guineveresaenger]

#5931 added tests for resourcedocgen. 🎉

For the developer, the setup of these tests includes some context that is not immediately obvious.

Since we do not have a standardized way to do tests, it's really important that tests have:

• Setup instructions
• Documentation on what to avoid when writing new tests
• How to re-generate the golden files

[iwahbe]

For the developer, the setup of these tests includes some context that is not immediately obvious.

I'm not sure what you mean by "setup". The caveat for using that function is called out at the function declaration, as is how to regenerate:

registry/tools/resourcedocsgen/internal/tests/util/fs.go

Lines 31 to 43 in 12b3c52

	// AssertDirEqual asserts that each file located under root is byte-for-byte identical
	// with it's test representation.
	//
	// To update files under test, use:
	//
	// go test ./... -update
	//
	// WARNING: Multiple AssertDirEqual should not run in the same go test. If you need to
	// call AssertDirEqual more then once in a test, place each in a subtest:
	//
	// t.Run("docs", func(t *testing.T) { util.AssertDirEqual(t, baseDocsOutDir) })
	// t.Run("tree", func(t *testing.T) { util.AssertDirEqual(t, basePackageTreeJSONOutDir) })
	func AssertDirEqual(t *testing.T, root string) {

That's only relevant when writing new tests using this function. When running tests, you just need to run the test like any other Go test:

$ cd tools/resourcedocsgen && go test ./...

We can call out how to run tests and -update in the README.md.