feat(bazel): introduce rule for running integration tests with Bazel

Introduces a rule for running integration tests with Bazel. This is
reworked version conceptually matching mostly with the existing rule
in the framework repository. The rule has been reworked to be
TypeScript-based and to be more maintainable/future-proof by following
best-practices as done in all other tools under `dev-infra/`.

The tool also has an additional feature, allowing tools to be wired
up/aliased within Starlark. This makes it a lot easier to write commands
for the integration tests as the rather inconvenient Bazel make location
expansion would not be needed. The location expansion also is brittle
enough to break later in the test execution where test scripts might
call to e.g. `node` or `yarn`.. but these would not be available due to
Bazel's environment variable encapsulation/filter.

Also the tool mappings can be provided as defaults in a macro, so that
integration test authors would not need to bother about Bazel
Rules_NodeJS internals.

Author: devversion

bazel/integration/BUILD.bazel

@@ -0,0 +1,9 @@
+package(default_visibility = ["//visibility:public"])
+
+# Make source files available for distribution via pkg_npm
+filegroup(
+    name = "files",
+    srcs = glob(["*"]) + [
+        "//bazel/integration/test_runner:files",
+    ],
+)

bazel/integration/index.bzl

@@ -0,0 +1,142 @@
+load("@build_bazel_rules_nodejs//:index.bzl", "nodejs_test")
+
+def _serialize_file(file):
+    """Serializes a file into a struct that matches the `BazelFileInfo` type in the
+      packager implementation. Useful for transmission of such information."""
+
+    return struct(path = file.path, shortPath = file.short_path)
+
+def _split_and_expand_command(ctx, command):
+    """Splits a command into the binary and its arguments. Also Bazel locations are expanded."""
+    expanded_command = ctx.expand_location(command, targets = ctx.attr.data)
+    return expanded_command.split(" ", 1)
+
+def _unwrap_label_keyed_mappings(dict, description):
+    """Unwraps a label-keyed dictionary used for expressing mappings into a JSON-serializable
+    dictionary that will match the `Record<string, BazelFileInfo>` type as in the test
+    runner. Additionally, the list of referenced mapping files is returned so that these
+    can be added to the runfiles of the tool relying on the serialized mappings.
+
+    This helper is used for serializing the `npm_packages` and `tool_mappings`
+    dictionaries into JSON that can be passed to the test runner."""
+
+    serialized_mappings = {}
+    referenced_files = []
+
+    for target in dict:
+        name = dict[target]
+
+        if not DefaultInfo in target:
+            fail("Expected %s mapping for %s to have the `DefaultInfo` provider." % (description, target))
+
+        files = target[DefaultInfo].files.to_list()
+
+        if len(files) != 1:
+            fail("Expected %s target %s to only have a single file in `DefaultInfo`" % (description, target))
+
+        serialized_mappings[name] = _serialize_file(files[0])
+        referenced_files.append(files[0])
+
+    return serialized_mappings, referenced_files
+
+def _integration_test_config_impl(ctx):
+    """Implementation of the `_integration_test_config` rule."""
+
+    npmPackageMappings, npmPackageFiles = \
+        _unwrap_label_keyed_mappings(ctx.attr.npm_packages, "NPM package")
+    toolMappings, toolFiles = _unwrap_label_keyed_mappings(ctx.attr.tool_mappings, "Tool")
+
+    config_file = ctx.actions.declare_file("%s.json" % ctx.attr.name)
+    config = struct(
+        testPackage = ctx.label.package,
+        testFiles = [_serialize_file(f) for f in ctx.files.srcs],
+        commands = [_split_and_expand_command(ctx, c) for c in ctx.attr.commands],
+        npmPackageMappings = npmPackageMappings,
+        toolMappings = toolMappings,
+    )
+
+    ctx.actions.write(
+        output = config_file,
+        content = json.encode(config),
+    )
+
+    runfiles = [config_file] + ctx.files.data + ctx.files.srcs + npmPackageFiles + toolFiles
+
+    return [
+        DefaultInfo(
+            files = depset([config_file]),
+            runfiles = ctx.runfiles(files = runfiles),
+        ),
+    ]
+
+_integration_test_config = rule(
+    implementation = _integration_test_config_impl,
+    doc = """Rule which controls the integration test runner by writing a configuration file.""",
+    attrs = {
+        "srcs": attr.label_list(
+            allow_files = True,
+            mandatory = True,
+            doc = "Files which need to be available when the integration test commands are invoked.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = """
+              Files which will be available for runfile resolution. Useful when location
+              expansion is used in a command.""",
+        ),
+        "commands": attr.string_list(
+            mandatory = True,
+            doc = """
+              List of commands to run as part of the integration test. The commands can rely on
+              the global tools made available through the tool mappings.
+
+              Commands can also use Bazel make location expansion.""",
+        ),
+        "npm_packages": attr.label_keyed_string_dict(
+            allow_files = True,
+            doc = """
+              Dictionary of targets which map to NPM packages. This allows for NPM packages
+              to be mapped to first-party built NPM artifacts.""",
+        ),
+        "tool_mappings": attr.label_keyed_string_dict(
+            allow_files = True,
+            doc = """
+              Dictionary of targets which map to global tools needed by the integration test.
+              This allows for binaries like `node` to be made available to the integration test
+              using the `PATH` environment variable.""",
+        ),
+    },
+)
+
+def integration_test(
+        name,
+        srcs,
+        commands,
+        npm_packages = {},
+        tool_mappings = {},
+        data = [],
+        tags = [],
+        **kwargs):
+    """Rule that allows for arbitrary commands to be executed within a temporary
+      directory which will hold the specified test source files."""
+
+    config_target = "%s_config" % name
+
+    _integration_test_config(
+        name = config_target,
+        srcs = srcs,
+        data = data,
+        commands = commands,
+        npm_packages = npm_packages,
+        tool_mappings = tool_mappings,
+        tags = tags,
+    )
+
+    nodejs_test(
+        name = name,
+        data = ["//bazel/integration/test_runner", ":" + config_target],
+        templated_args = ["--bazel_patch_module_resolver", "$(rootpath :%s)" % config_target],
+        entry_point = "//bazel/integration/test_runner:main.ts",
+        tags = tags,
+        **kwargs
+    )

bazel/integration/test/BUILD.bazel

@@ -0,0 +1,13 @@
+load("//bazel/integration:index.bzl", "integration_test")
+
+integration_test(
+    name = "test",
+    srcs = ["package.json", "yarn.lock"],
+    commands = [
+        "yarn test"
+    ],
+    tool_mappings = {
+        "@nodejs//:yarn_bin": "yarn",
+        "@nodejs//:node_bin": "node",
+    }
+)

bazel/integration/test/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "test",
+  "version": "1.0.0",
+  "license": "MIT",
+  "scripts": {
+    "test": "node ./some-test.js"
+  }
+}

bazel/integration/test/some-test.js

@@ -0,0 +1 @@
+console.log('Running test!');

bazel/integration/test/yarn.lock

@@ -0,0 +1,4 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+

bazel/integration/test_runner/BUILD.bazel

@@ -0,0 +1,24 @@
+load("@npm//@bazel/typescript:index.bzl", "ts_library")
+
+package(default_visibility = ["//visibility:public"])
+
+ts_library(
+    name = "test_runner",
+    srcs = glob(["*.ts"]),
+    module_name = "@angular/dev-infra-private/bazel/integration/test_runner",
+    # A tsconfig needs to be specified as otherwise `ts_library` will look for the config
+    # in `//:package.json` and this breaks when the BUILD file is copied to `@npm//`.
+    tsconfig = "//:tsconfig.json",
+    deps = [
+        "@npm//@bazel/runfiles",
+        "@npm//@types/node",
+        "@npm//@types/tmp",
+        "@npm//tmp",
+    ],
+)
+
+# Make source files available for distribution via pkg_npm
+filegroup(
+    name = "files",
+    srcs = glob(["*"]),
+)

bazel/integration/test_runner/bazel.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {debug} from './debug';
+import {runfiles} from '@bazel/runfiles';
+
+// Exposing the runfiles to keep the Bazel-specific code local to this file.
+export {runfiles};
+
+/**
+ * Interface describing a file captured in the Bazel action.
+ * https://docs.bazel.build/versions/main/skylark/lib/File.html.
+ */
+export interface BazelFileInfo {
+  /** Execroot-relative path pointing to the file. */
+  path: string;
+  /** The path of this file relative to its root. e.g. omitting `bazel-out/<..>/bin`. */
+  shortPath: string;
+}
+
+/** Resolves the specified Bazel file to an absolute disk path. */
+export function resolveBazelFile(file: BazelFileInfo): string {
+  return runfiles.resolveWorkspaceRelative(file.shortPath);
+}
+
+/**
+ * Resolves a binary with respect to the runfiles part of this test. An integration
+ * test could use a Bazel location substitution within a command. This function ensures
+ * that the substituted manifest path is then resolved to an absolute path.
+ *
+ * e.g. consider a case where a Bazel-built tool, like `$(rootpath @nodejs//:node)` is
+ * used as binary for the integration test command. This results in a root-relative
+ * path that we try to resolve here (using the runfiles).
+ */
+export async function resolveBinaryWithRunfiles(binary: string): Promise<string> {
+  try {
+    const resolved = runfiles.resolveWorkspaceRelative(binary);
+    debug(`Resolved ${binary} to ${resolved} using runfile resolution.`);
+    return resolved;
+  } catch {
+    debug(`Unable to resolve ${binary} with respect to runfiles.`);
+    return binary;
+  }
+}

bazel/integration/test_runner/debug.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import * as util from 'util';
+
+/** Function for printing debug messages when working with the test runner. */
+export const debug = util.debuglog('ng-integration-test');

bazel/integration/test_runner/file_system_utils.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import * as fs from 'fs';
+
+/** Gets whether the file is executable or not. */
+export async function isExecutable(filePath: string): Promise<boolean> {
+  try {
+    await fs.promises.access(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Adds the `write` permission to the given file using `chmod`. */
+export async function addWritePermissionFlag(filePath: string) {
+  if (await isExecutable(filePath)) {
+    await fs.promises.chmod(filePath, 0o755);
+  } else {
+    await fs.promises.chmod(filePath, 0o644);
+  }
+}
+
+/** Writes an executable file to the specified location. */
+export async function writeExecutableFile(outputFilePath: string, content: string): Promise<void> {
+  await fs.promises.writeFile(outputFilePath, content, {mode: 0o755});
+}