blob: 085dc5b1b5a71bc3f9d849fc984c94d826ad7377 [file] [log] [blame]
c-parsons2c81ab82019-08-30 16:16:25 -04001# 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")
c-parsons166ff5e2019-09-11 12:04:15 -040017load("//stardoc:html_tables_stardoc.bzl", "html_tables_stardoc")
c-parsons2c81ab82019-08-30 16:16:25 -040018load("//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
Alexandre Rostovtsevf8fab822023-07-24 21:43:33 -040029 Each invocation creates multiple targets:
c-parsons2c81ab82019-08-30 16:16:25 -040030
Alexandre Rostovtsev39a0c662024-04-23 14:25:42 -040031 1. A `stardoc` target which will generate a new golden file given an input
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -040032 file, named "{name}_stardoc".
Alexandre Rostovtsev39a0c662024-04-23 14:25:42 -040033 2. An `sh_test` target which verifies that the output of the `stardoc`
34 target above matches a golden file.
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -040035 3. A shell script which can be executed via `bazel run` to update the golden
36 file from the `stardoc` target's output, named "{name}_regenerate"
37 4. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib".
c-parsons2c81ab82019-08-30 16:16:25 -040038
39 Args:
40 name: A unique name to qualify the created targets.
41 input_file: The label string of the Starlark input file for which documentation is generated
42 in this test.
43 golden_file: The label string of the golden file containing the documentation when stardoc
44 is run on the input file.
45 deps: A list of label strings of starlark file dependencies of the input_file.
c-parsons166ff5e2019-09-11 12:04:15 -040046 test: The type of test (default or html_tables).
c-parsons2c81ab82019-08-30 16:16:25 -040047 **kwargs: A dictionary of input template names mapped to template file path for which documentation is generated.
48 """
c-parsons2c81ab82019-08-30 16:16:25 -040049 bzl_library(
50 name = "%s_lib" % name,
51 srcs = [input_file],
52 deps = deps,
53 )
Alexandre Rostovtsevf8fab822023-07-24 21:43:33 -040054
Alexandre Rostovtsev39a0c662024-04-23 14:25:42 -040055 _create_test_targets(
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -040056 test_name = name,
57 stardoc_name = "%s_stardoc" % name,
58 regenerate_name = "%s_regenerate" % name,
Alexandre Rostovtsev39a0c662024-04-23 14:25:42 -040059 lib_name = "%s_lib" % name,
60 input_file = input_file,
61 golden_file = golden_file,
62 test = test,
63 **kwargs
64 )
c-parsons2c81ab82019-08-30 16:16:25 -040065
Alexandre Rostovtsevd93ee532021-04-22 14:24:24 -040066def _create_test_targets(
67 test_name,
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -040068 stardoc_name,
69 regenerate_name,
Alexandre Rostovtsevd93ee532021-04-22 14:24:24 -040070 lib_name,
71 input_file,
72 golden_file,
Alexandre Rostovtsevd93ee532021-04-22 14:24:24 -040073 test,
74 **kwargs):
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -040075 actual_generated_doc = "%s.md" % stardoc_name
76 tags = kwargs.get("tags", [])
c-parsons2c81ab82019-08-30 16:16:25 -040077
78 native.sh_test(
79 name = test_name,
80 srcs = ["diff_test_runner.sh"],
81 args = [
82 "$(location %s)" % actual_generated_doc,
83 "$(location %s)" % golden_file,
84 ],
85 data = [
86 actual_generated_doc,
87 golden_file,
88 ],
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -040089 tags = tags,
90 )
91
92 regenerate_sh = "%s.sh" % regenerate_name
93 native.genrule(
94 name = "%s_sh" % regenerate_name,
95 cmd = """cat > $(location %s) <<EOF
96#!/usr/bin/env bash
97cd \\$${BUILD_WORKSPACE_DIRECTORY}
98cp -fv $(location %s) $(location %s)
99EOF""" % (regenerate_sh, actual_generated_doc, golden_file),
100 outs = [regenerate_sh],
101 srcs = [actual_generated_doc, golden_file],
102 tags = tags,
103 )
104
105 native.sh_binary(
106 name = regenerate_name,
107 srcs = [regenerate_sh],
108 data = [actual_generated_doc],
109 tags = tags,
c-parsons2c81ab82019-08-30 16:16:25 -0400110 )
111
112 if test == "default":
113 stardoc(
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -0400114 name = stardoc_name,
c-parsons2c81ab82019-08-30 16:16:25 -0400115 out = actual_generated_doc,
116 input = input_file,
117 deps = [lib_name],
c-parsons2c81ab82019-08-30 16:16:25 -0400118 **kwargs
119 )
c-parsons166ff5e2019-09-11 12:04:15 -0400120 elif test == "html_tables":
121 html_tables_stardoc(
Alexandre Rostovtsevaba1a012024-06-18 14:40:59 -0400122 name = stardoc_name,
c-parsons2c81ab82019-08-30 16:16:25 -0400123 out = actual_generated_doc,
124 input = input_file,
125 deps = [lib_name],
c-parsons2c81ab82019-08-30 16:16:25 -0400126 **kwargs
127 )
128 else:
c-parsons166ff5e2019-09-11 12:04:15 -0400129 fail("parameter 'test' must either be 'default' or 'html_tables', but was " + test)
Alexandre Rostovtsev056ba3b2023-08-02 14:53:54 -0400130
131def self_gen_test(
132 name,
133 stardoc_doc,
134 golden_file,
Alexandre Rostovtsev056ba3b2023-08-02 14:53:54 -0400135 **kwargs):
136 """
137 A wrapper around `diff_test_runner.sh` for testing Stardoc's own generated documentation.
138
139 Args:
140 name: A unique name for the test target.
141 stardoc_doc: The Stardoc output being tested.
142 golden_file: Expected Stardoc output.
Alexandre Rostovtsev056ba3b2023-08-02 14:53:54 -0400143 **kwargs: Additional arguments for the test.
144 """
Alexandre Rostovtsev056ba3b2023-08-02 14:53:54 -0400145 native.sh_test(
146 name = name,
147 srcs = ["diff_test_runner.sh"],
148 args = [
149 "$(location %s)" % golden_file,
150 "$(location %s)" % stardoc_doc,
151 ],
152 data = [
153 golden_file,
154 stardoc_doc,
155 ],
156 **kwargs
157 )