src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl

# Copyright 2018 The Bazel Authors. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Convenience macro for skydoc tests. Each target represents two targets:
# 1. A sh_test target which verifies that skydoc, when run on an input file,
#    creates output matching the contents of a golden file.
# 2. A genrule target which will generate a new golden file given an input file
#    and the current version of skydoc. This target should be used to regenerate
#    the golden file if changes are made to skydoc.
"""Convenience macro for skydoc tests."""

load("@rules_java//java:defs.bzl", "java_binary")

def _extract_binaryproto_impl(ctx):
    output_file = ctx.outputs.output
    extractor_args = ctx.actions.args()
    extractor_args.add("--input=" + str(ctx.file.input.owner))
    extractor_args.add("--output=" + output_file.path)
    extractor_args.add("--workspace_name=" + ctx.workspace_name)
    extractor_args.add_all(
        ctx.attr.symbol_names,
        format_each = "--symbols=%s",
        omit_if_empty = True,
    )
    ctx.actions.run(
        outputs = [output_file],
        executable = ctx.executable.tool,
        arguments = [extractor_args],
        mnemonic = "Stardoc",
        progress_message = ("Extracting Starlark doc for %s" % (ctx.label.name)),
    )
    outputs = [output_file]
    return [DefaultInfo(files = depset(outputs), runfiles = ctx.runfiles(files = outputs))]

extract_binaryproto = rule(
    doc = "Minimalistic binary-proto-only variant of the Stardoc rule using the legacy extractor",
    implementation = _extract_binaryproto_impl,
    attrs = {
        "input": attr.label(
            doc = "The starlark file to generate documentation for.",
            allow_single_file = [".bzl"],
            mandatory = True,
        ),
        "output": attr.output(
            doc = "The binary proto file to which documentation will be output.",
            mandatory = True,
        ),
        "symbol_names": attr.string_list(
            doc = """
A list of symbol names to generate documentation for. These should correspond to
the names of rule definitions in the input file. If this list is empty, then
documentation for all exported rule definitions will be generated.
""",
            default = [],
        ),
        "tool": attr.label(
            doc = "The location of the Stardoc legacy extractor tool.",
            allow_files = True,
            cfg = "exec",
            executable = True,
            mandatory = True,
        ),
    },
)

def skydoc_test(
        name,
        input_file,
        golden_file,
        deps = [],
        **kwargs):
    """Creates a test target and golden-file regeneration target for skydoc testing.

    The test target is named "{name}".
    The golden-file regeneration target is named "regenerate_{name}_golden".

    Args:
      name: A unique name to qualify the created targets.
      input_file: The label string of the Starlark input file for which documentation is generated
          in this test.
      golden_file: The label string of the golden file containing the documentation when skydoc
          is run on the input file.
      deps: A list of label strings of Starlark file dependencies of the input_file.
      **kwargs: Remaining arguments to passthrough to the underlying stardoc rule.
      """

    extractor = "%s_legacy_extractor" % name
    extractor_binary = "%s_binary" % extractor
    generated_binaryproto = "%s.binaryproto" % extractor
    generated_textproto = "%s.textproto" % extractor
    textproto_to_binaryproto = Label("//src/test/java/com/google/devtools/build/skydoc:binaryprotoToTextproto")

    native.sh_test(
        name = name,
        srcs = ["diff_test_runner.sh"],
        args = [
            "$(location %s)" % generated_textproto,
            "$(location %s)" % golden_file,
        ],
        data = [
            generated_textproto,
            golden_file,
        ],
    )

    java_binary(
        name = extractor_binary,
        main_class = "com.google.devtools.build.skydoc.SkydocMain",
        runtime_deps = [Label("//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar")],
        data = [input_file] + deps,
        tags = ["manual", "notap"],
        testonly = True,
        visibility = ["//visibility:private"],
    )

    extract_binaryproto(
        name = extractor,
        input = input_file,
        output = generated_binaryproto,
        tool = extractor_binary,
        testonly = True,
    )

    native.genrule(
        name = "regenerate_%s_golden" % name,
        srcs = [generated_binaryproto],
        outs = [generated_textproto],
        cmd = "./$(location %s) < $(location %s) > $(location %s)" % (
            textproto_to_binaryproto,
            generated_binaryproto,
            generated_textproto,
        ),
        tools = [textproto_to_binaryproto],
        testonly = True,
    )