feat: add assert_outputs

It's a simple way to make an executable example demonstrate what outputs a rule produces.
See https://github.com/aspect-build/rules_ts/pull/214 for an example usage in the real world.

docs/testing.md

@@ -27,3 +27,23 @@ Depends on bash, as it creates an sh_test target.
 | <a id="assert_contains-timeout"></a>timeout |  the timeout attribute of the test target   |  <code>None</code> |
 
 
+<a id="assert_outputs"></a>
+
+## assert_outputs
+
+<pre>
+assert_outputs(<a href="#assert_outputs-name">name</a>, <a href="#assert_outputs-actual">actual</a>, <a href="#assert_outputs-expected">expected</a>)
+</pre>
+
+Assert that the default outputs of a target are the expected ones.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="assert_outputs-name"></a>name |  name of the resulting diff_test   |  none |
+| <a id="assert_outputs-actual"></a>actual |  string of the label to check the outputs   |  none |
+| <a id="assert_outputs-expected"></a>expected |  a list of rootpaths of expected outputs, as they would appear in a runfiles manifest   |  none |
+
+

lib/BUILD.bazel

@@ -163,7 +163,10 @@ bzl_library(
     name = "testing",
     srcs = ["testing.bzl"],
     deps = [
+        ":params_file",
         ":utils",
+        "@bazel_skylib//lib:types",
+        "@bazel_skylib//rules:diff_test",
         "@bazel_skylib//rules:write_file",
     ],
 )

lib/testing.bzl

@@ -1,5 +1,8 @@
 "Helpers for making test assertions"
 
+load("//lib:params_file.bzl", "params_file")
+load("@bazel_skylib//lib:types.bzl", "types")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
 load("@bazel_skylib//rules:write_file.bzl", "write_file")
 load("//lib:utils.bzl", "default_timeout")
 
@@ -36,3 +39,34 @@ def assert_contains(name, actual, expected, size = None, timeout = None):
         timeout = default_timeout(size, timeout),
         data = [actual],
     )
+
+def assert_outputs(name, actual, expected):
+    """Assert that the default outputs of a target are the expected ones.
+
+    Args:
+        name: name of the resulting diff_test
+        actual: string of the label to check the outputs
+        expected: a list of rootpaths of expected outputs, as they would appear in a runfiles manifest
+    """
+
+    if not types.is_list(expected):
+        fail("expected should be a list of strings")
+
+    params_file(
+        name = "_actual_" + name,
+        data = [actual],
+        args = ["$(rootpaths {})".format(actual)],
+        out = "_{}_outputs.txt".format(name),
+    )
+
+    write_file(
+        name = "_expected_ " + name,
+        content = expected,
+        out = "_expected_{}.txt".format(name),
+    )
+
+    diff_test(
+        name = name,
+        file1 = "_expected_ " + name,
+        file2 = "_actual_" + name,
+    )

lib/tests/write_source_files/BUILD.bazel

@@ -4,6 +4,7 @@ load("//lib:write_source_files.bzl", "write_source_files")
 load("//lib:copy_to_directory.bzl", "copy_to_directory")
 load("//lib:directory_path.bzl", "directory_path")
 load("//lib:output_files.bzl", "output_files")
+load("//lib:testing.bzl", "assert_outputs")
 
 genrule(
     name = "a-desired",
@@ -24,6 +25,15 @@ generate_outputs(
     ],
 )
 
+assert_outputs(
+    name = "test_assert_outputs",
+    actual = "b_c-desired",
+    expected = [
+        "lib/tests/write_source_files/b-desired.js",
+        "lib/tests/write_source_files/c-desired.js",
+    ],
+)
+
 output_files(
     name = "b-desired",
     paths = ["%s/b-desired.js" % package_name()],