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(test_name = "%s_e2e_test" % name, 57 genrule_name = "regenerate_%s_golden" % name, 58 lib_name = "%s_lib" % name, 59 input_file = input_file, 60 golden_file = golden_file, 61 stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", 62 renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", 63 test = test, 64 **kwargs) 65 _create_test_targets(test_name = "%s_e2e_jar_test" % name, 66 genrule_name = "regenerate_with_jar_%s_golden" % name, 67 lib_name = "%s_lib" % name, 68 input_file = input_file, 69 golden_file = golden_file, 70 stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", 71 renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", 72 test = test, 73 **kwargs) 74 75def _create_test_targets(test_name, 76 genrule_name, 77 lib_name, 78 input_file, 79 golden_file, 80 stardoc_bin, 81 renderer_bin, 82 test, 83 **kwargs): 84 actual_generated_doc = "%s.out" % genrule_name 85 86 native.sh_test( 87 name = test_name, 88 srcs = ["diff_test_runner.sh"], 89 args = [ 90 "$(location %s)" % actual_generated_doc, 91 "$(location %s)" % golden_file, 92 ], 93 data = [ 94 actual_generated_doc, 95 golden_file, 96 ], 97 ) 98 99 if test == "default": 100 stardoc( 101 name = genrule_name, 102 out = actual_generated_doc, 103 input = input_file, 104 deps = [lib_name], 105 renderer = renderer_bin, 106 stardoc = stardoc_bin, 107 **kwargs 108 ) 109 elif test == "html_tables": 110 html_tables_stardoc( 111 name = genrule_name, 112 out = actual_generated_doc, 113 input = input_file, 114 deps = [lib_name], 115 renderer = renderer_bin, 116 stardoc = stardoc_bin, 117 **kwargs 118 ) 119 else: 120 fail("parameter 'test' must either be 'default' or 'html_tables', but was " + test) 121 122