c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 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 | |
| 16 | load("@bazel_skylib//:bzl_library.bzl", "bzl_library") |
c-parsons | 166ff5e | 2019-09-11 12:04:15 -0400 | [diff] [blame] | 17 | load("//stardoc:html_tables_stardoc.bzl", "html_tables_stardoc") |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 18 | load("//stardoc:stardoc.bzl", "stardoc") |
| 19 | |
| 20 | def 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 Rostovtsev | f8fab82 | 2023-07-24 21:43:33 -0400 | [diff] [blame] | 29 | Each invocation creates multiple targets: |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 30 | |
Alexandre Rostovtsev | 39a0c66 | 2024-04-23 14:25:42 -0400 | [diff] [blame] | 31 | 1. A `stardoc` target which will generate a new golden file given an input |
Alexandre Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 32 | file, named "{name}_stardoc". |
Alexandre Rostovtsev | 39a0c66 | 2024-04-23 14:25:42 -0400 | [diff] [blame] | 33 | 2. An `sh_test` target which verifies that the output of the `stardoc` |
| 34 | target above matches a golden file. |
Alexandre Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 35 | 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-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 38 | |
| 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-parsons | 166ff5e | 2019-09-11 12:04:15 -0400 | [diff] [blame] | 46 | test: The type of test (default or html_tables). |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 47 | **kwargs: A dictionary of input template names mapped to template file path for which documentation is generated. |
| 48 | """ |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 49 | bzl_library( |
| 50 | name = "%s_lib" % name, |
| 51 | srcs = [input_file], |
| 52 | deps = deps, |
| 53 | ) |
Alexandre Rostovtsev | f8fab82 | 2023-07-24 21:43:33 -0400 | [diff] [blame] | 54 | |
Alexandre Rostovtsev | 39a0c66 | 2024-04-23 14:25:42 -0400 | [diff] [blame] | 55 | _create_test_targets( |
Alexandre Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 56 | test_name = name, |
| 57 | stardoc_name = "%s_stardoc" % name, |
| 58 | regenerate_name = "%s_regenerate" % name, |
Alexandre Rostovtsev | 39a0c66 | 2024-04-23 14:25:42 -0400 | [diff] [blame] | 59 | lib_name = "%s_lib" % name, |
| 60 | input_file = input_file, |
| 61 | golden_file = golden_file, |
| 62 | test = test, |
| 63 | **kwargs |
| 64 | ) |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 65 | |
Alexandre Rostovtsev | d93ee53 | 2021-04-22 14:24:24 -0400 | [diff] [blame] | 66 | def _create_test_targets( |
| 67 | test_name, |
Alexandre Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 68 | stardoc_name, |
| 69 | regenerate_name, |
Alexandre Rostovtsev | d93ee53 | 2021-04-22 14:24:24 -0400 | [diff] [blame] | 70 | lib_name, |
| 71 | input_file, |
| 72 | golden_file, |
Alexandre Rostovtsev | d93ee53 | 2021-04-22 14:24:24 -0400 | [diff] [blame] | 73 | test, |
| 74 | **kwargs): |
Alexandre Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 75 | actual_generated_doc = "%s.md" % stardoc_name |
| 76 | tags = kwargs.get("tags", []) |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 77 | |
| 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 Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 89 | 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 |
| 97 | cd \\$${BUILD_WORKSPACE_DIRECTORY} |
| 98 | cp -fv $(location %s) $(location %s) |
| 99 | EOF""" % (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-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 110 | ) |
| 111 | |
| 112 | if test == "default": |
| 113 | stardoc( |
Alexandre Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 114 | name = stardoc_name, |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 115 | out = actual_generated_doc, |
| 116 | input = input_file, |
| 117 | deps = [lib_name], |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 118 | **kwargs |
| 119 | ) |
c-parsons | 166ff5e | 2019-09-11 12:04:15 -0400 | [diff] [blame] | 120 | elif test == "html_tables": |
| 121 | html_tables_stardoc( |
Alexandre Rostovtsev | aba1a01 | 2024-06-18 14:40:59 -0400 | [diff] [blame] | 122 | name = stardoc_name, |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 123 | out = actual_generated_doc, |
| 124 | input = input_file, |
| 125 | deps = [lib_name], |
c-parsons | 2c81ab8 | 2019-08-30 16:16:25 -0400 | [diff] [blame] | 126 | **kwargs |
| 127 | ) |
| 128 | else: |
c-parsons | 166ff5e | 2019-09-11 12:04:15 -0400 | [diff] [blame] | 129 | fail("parameter 'test' must either be 'default' or 'html_tables', but was " + test) |
Alexandre Rostovtsev | 056ba3b | 2023-08-02 14:53:54 -0400 | [diff] [blame] | 130 | |
| 131 | def self_gen_test( |
| 132 | name, |
| 133 | stardoc_doc, |
| 134 | golden_file, |
Alexandre Rostovtsev | 056ba3b | 2023-08-02 14:53:54 -0400 | [diff] [blame] | 135 | **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 Rostovtsev | 056ba3b | 2023-08-02 14:53:54 -0400 | [diff] [blame] | 143 | **kwargs: Additional arguments for the test. |
| 144 | """ |
Alexandre Rostovtsev | 056ba3b | 2023-08-02 14:53:54 -0400 | [diff] [blame] | 145 | 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 | ) |