feat: introduce generated_file_test

This is a new public API for checking in golden or snapshot files.
If you used the private golden_file_test previously, you need to rename actual to generated, golden to src, and golden_debug to src_dbg

Fixes #1893

Author: Alex Eagle

.github/BUILD.bazel

@@ -1,4 +1,4 @@
-load("@build_bazel_rules_nodejs//internal/golden_file_test:golden_file_test.bzl", "golden_file_test")
+load("@build_bazel_rules_nodejs//:index.bzl", "generated_file_test")
 load("@rules_codeowners//tools:codeowners.bzl", "generate_codeowners")
 
 generate_codeowners(
@@ -14,8 +14,8 @@ generate_codeowners(
     ],
 )
 
-golden_file_test(
+generated_file_test(
     name = "codeowners",
-    actual = "gen_codeowners",
-    golden = "CODEOWNERS",
+    src = "CODEOWNERS",
+    generated = "gen_codeowners",
 )

BUILD.bazel

@@ -38,6 +38,7 @@ bzl_library(
     visibility = ["//visibility:public"],
     deps = [
         "//internal/common:bzl",
+        "//internal/generated_file_test:bzl",
         "//internal/linker:bzl",
         "//internal/pkg_npm:bzl",
         "//internal/pkg_web:bzl",
@@ -78,7 +79,7 @@ pkg_npm(
         "//internal/common:package_contents",
         "//internal/copy_repository:package_contents",
         "//internal/coverage:package_contents",
-        "//internal/golden_file_test:package_contents",
+        "//internal/generated_file_test:package_contents",
         "//internal/js_library:package_contents",
         "//internal/linker:package_contents",
         "//internal/node:package_contents",

index.bzl

@@ -22,6 +22,7 @@ load("//internal/common:check_bazel_version.bzl", _check_bazel_version = "check_
 load("//internal/common:check_version.bzl", "check_version")
 load("//internal/common:copy_to_bin.bzl", _copy_to_bin = "copy_to_bin")
 load("//internal/common:params_file.bzl", _params_file = "params_file")
+load("//internal/generated_file_test:generated_file_test.bzl", _generated_file_test = "generated_file_test")
 load(
     "//internal/node:node.bzl",
     _nodejs_binary = "nodejs_binary",
@@ -42,6 +43,7 @@ npm_package_bin = _npm_bin
 pkg_web = _pkg_web
 copy_to_bin = _copy_to_bin
 params_file = _params_file
+generated_file_test = _generated_file_test
 # ANY RULES ADDED HERE SHOULD BE DOCUMENTED, see index.for_docs.bzl
 
 # Allows us to avoid a transitive dependency on bazel_skylib from leaking to users

index.for_docs.bzl

@@ -19,6 +19,7 @@ This differs from :index.bzl because we don't have wrapping macros that hide the
 load("//internal/common:check_bazel_version.bzl", _check_bazel_version = "check_bazel_version")
 load("//internal/common:copy_to_bin.bzl", _copy_to_bin = "copy_to_bin")
 load("//internal/common:params_file.bzl", _params_file = "params_file")
+load("//internal/generated_file_test:generated_file_test.bzl", _generated_file_test = "generated_file_test")
 load("//internal/node:node.bzl", _nodejs_binary = "nodejs_binary", _nodejs_test = "nodejs_test")
 load("//internal/node:node_repositories.bzl", _node_repositories = "node_repositories_rule")
 load("//internal/node:npm_package_bin.bzl", _npm_bin = "npm_package_bin")
@@ -37,4 +38,5 @@ npm_install = _npm_install
 yarn_install = _yarn_install
 npm_package_bin = _npm_bin
 pkg_web = _pkg_web
+generated_file_test = _generated_file_test
 # ANY RULES ADDED HERE SHOULD BE DOCUMENTED, run yarn stardoc to verify

internal/generated_file_test/BUILD.bazel

@@ -0,0 +1,16 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:public"])
+
+bzl_library(
+    name = "bzl",
+    srcs = glob(["*.bzl"]),
+    visibility = ["//visibility:public"],
+)
+
+exports_files(["bin.js"])
+
+filegroup(
+    name = "package_contents",
+    srcs = glob(["*"]),
+)

internal/generated_file_test/bin.js

@@ -0,0 +1,48 @@
+const fs = require('fs');
+const path = require('path');
+const runfiles = require(process.env['BAZEL_NODE_RUNFILES_HELPER']);
+
+function main(args) {
+  const [mode, golden_no_debug, golden_debug, actual] = args;
+  const actualPath = runfiles.resolveWorkspaceRelative(actual);
+  const debugBuild = /\/bazel-out\/[^/\s]*-dbg\//.test(actualPath);
+  const golden = debugBuild ? golden_debug : golden_no_debug;
+  const actualContents = fs.readFileSync(actualPath, 'utf-8').replace(/\r\n/g, '\n');
+  const goldenContents =
+      fs.readFileSync(runfiles.resolveWorkspaceRelative(golden), 'utf-8').replace(/\r\n/g, '\n');
+
+  if (actualContents === goldenContents) {
+    return 0;
+  }
+  if (mode === '--out') {
+    // Write to golden file
+    fs.writeFileSync(runfiles.resolveWorkspaceRelative(golden), actualContents);
+    console.error(`Replaced ${path.join(process.cwd(), golden)}`);
+    return 0;
+  }
+  if (mode === '--verify') {
+    const unidiff = require('unidiff');
+    // Generated does not match golden
+    const diff = unidiff.diffLines(goldenContents, actualContents);
+    let prettyDiff =
+        unidiff.formatLines(diff, {aname: `[workspace]/${golden}`, bname: `[bazel-out]/${actual}`});
+    if (prettyDiff.length > 5000) {
+      prettyDiff = prettyDiff.substr(0, 5000) + '/n...elided...';
+    }
+    console.error(`Generated output doesn't match:
+
+${prettyDiff}
+
+If the bazel-out content is correct, you can update the workspace file by running:
+
+          bazel run ${debugBuild ? '--compilation_mode=dbg ' : ''}${
+        process.env['TEST_TARGET'].replace(/_bin$/, '')}.update
+`);
+    return 1;
+  }
+  throw new Error('unknown mode', mode);
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}

internal/generated_file_test/generated_file_test.bzl

@@ -0,0 +1,42 @@
+"Convenience for testing that an output matches a file"
+
+load("@build_bazel_rules_nodejs//internal/node:node.bzl", "nodejs_binary", "nodejs_test")
+
+def generated_file_test(name, generated, src, src_dbg = None, **kwargs):
+    """Tests that a file generated by Bazel has identical content to a file in the workspace.
+
+    This is useful for testing, where a "snapshot" or "golden" file is checked in,
+    so that you can code review changes to the generated output.
+
+    Args:
+        name: Name of the rule.
+        generated: a Label of the output file generated by another rule
+        src: Label of the source file in the workspace
+        src_dbg: if the build uses `--compilation_mode dbg` then some rules will produce different output.
+            In this case you can specify what the dbg version of the output should look like
+        **kwargs: extra arguments passed to the underlying nodejs_test or nodejs_binary
+    """
+    data = [src, generated, "@npm//unidiff"]
+
+    if src_dbg:
+        data.append(src_dbg)
+    else:
+        src_dbg = src
+
+    loc = "$(rootpath %s)"
+    nodejs_test(
+        name = name,
+        entry_point = "@build_bazel_rules_nodejs//internal/generated_file_test:bin.js",
+        templated_args = ["--verify", loc % src, loc % src_dbg, loc % generated],
+        data = data,
+        **kwargs
+    )
+
+    nodejs_binary(
+        name = name + ".update",
+        testonly = True,
+        entry_point = "@build_bazel_rules_nodejs//internal/generated_file_test:bin.js",
+        templated_args = ["--out", loc % src, loc % src_dbg, loc % generated],
+        data = data,
+        **kwargs
+    )