1# Copyright 2019 The Bazel Authors. All rights reserved. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14"""Convenience macro for stardoc e2e tests.""" 15 16load("@bazel_skylib//:bzl_library.bzl", "bzl_library") 17load("//stardoc:html_tables_stardoc.bzl", "html_tables_stardoc") 18load("//stardoc:stardoc.bzl", "stardoc") 19 20def stardoc_test( 21 name, 22 input_file, 23 golden_file, 24 deps = [], 25 test = "default", 26 **kwargs): 27 """Convenience macro for stardoc e2e test suites. 28 29 Each invocation creates four targets: 30 31 1. A sh_test target which verifies that stardoc-built-from-source, when run on an input file, 32 creates output matching the contents of a golden file, named "{name}_e2e_test". 33 2. A `stardoc` target which will generate a new golden file given an input file 34 with stardoc-built-from-source. This target should be used to regenerate 35 the golden file when updating stardoc, named "regenerate_{name}_golden". 36 3 & 4. Targets identical to (1) and (2) except they use the prebuilt-stardoc jar, and 37 are named "{name}_e2e_jar_test" and "regenerate_with_jar_{name}_golden". 38 5. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib". 39 40 Args: 41 name: A unique name to qualify the created targets. 42 input_file: The label string of the Starlark input file for which documentation is generated 43 in this test. 44 golden_file: The label string of the golden file containing the documentation when stardoc 45 is run on the input file. 46 deps: A list of label strings of starlark file dependencies of the input_file. 47 test: The type of test (default or html_tables). 48 **kwargs: A dictionary of input template names mapped to template file path for which documentation is generated. 49 """ 50 51 bzl_library( 52 name = "%s_lib" % name, 53 srcs = [input_file], 54 deps = deps, 55 ) 56 _create_test_targets( 57 test_name = "%s_e2e_test" % name, 58 genrule_name = "regenerate_%s_golden" % name, 59 lib_name = "%s_lib" % name, 60 input_file = input_file, 61 golden_file = golden_file, 62 stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", 63 renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", 64 test = test, 65 **kwargs 66 ) 67 _create_test_targets( 68 test_name = "%s_e2e_jar_test" % name, 69 genrule_name = "regenerate_with_jar_%s_golden" % name, 70 lib_name = "%s_lib" % name, 71 input_file = input_file, 72 golden_file = golden_file, 73 stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", 74 renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", 75 test = test, 76 **kwargs 77 ) 78 79def _create_test_targets( 80 test_name, 81 genrule_name, 82 lib_name, 83 input_file, 84 golden_file, 85 stardoc_bin, 86 renderer_bin, 87 test, 88 **kwargs): 89 actual_generated_doc = "%s.out" % genrule_name 90 91 native.sh_test( 92 name = test_name, 93 srcs = ["diff_test_runner.sh"], 94 args = [ 95 "$(location %s)" % actual_generated_doc, 96 "$(location %s)" % golden_file, 97 ], 98 data = [ 99 actual_generated_doc, 100 golden_file, 101 ], 102 ) 103 104 if test == "default": 105 stardoc( 106 name = genrule_name, 107 out = actual_generated_doc, 108 input = input_file, 109 deps = [lib_name], 110 renderer = renderer_bin, 111 stardoc = stardoc_bin, 112 **kwargs 113 ) 114 elif test == "html_tables": 115 html_tables_stardoc( 116 name = genrule_name, 117 out = actual_generated_doc, 118 input = input_file, 119 deps = [lib_name], 120 renderer = renderer_bin, 121 stardoc = stardoc_bin, 122 **kwargs 123 ) 124 else: 125 fail("parameter 'test' must either be 'default' or 'html_tables', but was " + test) 126