diff options
Diffstat (limited to 'test/stardoc_test.bzl')
| -rw-r--r-- | test/stardoc_test.bzl | 123 |
1 files changed, 91 insertions, 32 deletions
diff --git a/test/stardoc_test.bzl b/test/stardoc_test.bzl index 8a18b52..d782643 100644 --- a/test/stardoc_test.bzl +++ b/test/stardoc_test.bzl @@ -21,21 +21,27 @@ def stardoc_test( name, input_file, golden_file, + legacy_golden_file = None, + test_legacy_extractor = True, deps = [], test = "default", **kwargs): """Convenience macro for stardoc e2e test suites. - Each invocation creates four targets: + Each invocation creates multiple targets: 1. A sh_test target which verifies that stardoc-built-from-source, when run on an input file, - creates output matching the contents of a golden file, named "{name}_e2e_test". - 2. A `stardoc` target which will generate a new golden file given an input file - with stardoc-built-from-source. This target should be used to regenerate - the golden file when updating stardoc, named "regenerate_{name}_golden". + creates output matching the contents of a golden file, named "{name}_e2e_legacy_test". + 2. A `stardoc` target which will generate a new golden file given an input file with the + legacy extractor built from Bazel source. This target should be used to regenerate the + legacy golden file when updating stardoc, named "regenerate_{name}_legacy_golden". 3 & 4. Targets identical to (1) and (2) except they use the prebuilt-stardoc jar, and - are named "{name}_e2e_jar_test" and "regenerate_with_jar_{name}_golden". - 5. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib". + are named "{name}_e2e_jar_legacy_test" and "regenerate_with_jar_{name}_legacy_golden". + 5 & 6. Only if the host Bazel supports the `native.starlark_doc_extract` rule: Targets + identical to (1) and (2) except they use starlark_doc_extract, and are named "{name}_e2e_test" + and "regenerate_{name}_golden". The latter target should be used to regenerate the golden + file when updating Stardoc. + 7. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib". Args: name: A unique name to qualify the created targets. @@ -43,38 +49,60 @@ def stardoc_test( in this test. golden_file: The label string of the golden file containing the documentation when stardoc is run on the input file. + legacy_golden_file: The label string of the golden file when using the legacy documentation + extractor. If `legacy_golden_file` is not set, `golden_file` will be used for both extractors. + test_legacy_extractor: Whether to create legacy extractor test targets. deps: A list of label strings of starlark file dependencies of the input_file. test: The type of test (default or html_tables). **kwargs: A dictionary of input template names mapped to template file path for which documentation is generated. """ + if legacy_golden_file == None: + legacy_golden_file = golden_file + bzl_library( name = "%s_lib" % name, srcs = [input_file], deps = deps, ) - _create_test_targets( - test_name = "%s_e2e_test" % name, - genrule_name = "regenerate_%s_golden" % name, - lib_name = "%s_lib" % name, - input_file = input_file, - golden_file = golden_file, - stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", - renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", - test = test, - **kwargs - ) - _create_test_targets( - test_name = "%s_e2e_jar_test" % name, - genrule_name = "regenerate_with_jar_%s_golden" % name, - lib_name = "%s_lib" % name, - input_file = input_file, - golden_file = golden_file, - stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc", - renderer_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc/renderer", - test = test, - **kwargs - ) + + if test_legacy_extractor: + _create_test_targets( + test_name = "%s_e2e_legacy_test" % name, + genrule_name = "regenerate_%s_legacy_golden" % name, + lib_name = "%s_lib" % name, + input_file = input_file, + golden_file = legacy_golden_file, + stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar", + test = test, + use_starlark_doc_extract = False, + **kwargs + ) + + _create_test_targets( + test_name = "%s_e2e_jar_legacy_test" % name, + genrule_name = "regenerate_with_jar_%s_legacy_golden" % name, + lib_name = "%s_lib" % name, + input_file = input_file, + golden_file = legacy_golden_file, + stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar", + test = test, + use_starlark_doc_extract = False, + **kwargs + ) + + if hasattr(native, "starlark_doc_extract"): + _create_test_targets( + test_name = "%s_e2e_test" % name, + genrule_name = "regenerate_%s_golden" % name, + lib_name = "%s_lib" % name, + input_file = input_file, + golden_file = golden_file, + stardoc_bin = None, + test = test, + use_starlark_doc_extract = True, + **kwargs + ) def _create_test_targets( test_name, @@ -83,7 +111,6 @@ def _create_test_targets( input_file, golden_file, stardoc_bin, - renderer_bin, test, **kwargs): actual_generated_doc = "%s.out" % genrule_name @@ -107,7 +134,6 @@ def _create_test_targets( out = actual_generated_doc, input = input_file, deps = [lib_name], - renderer = renderer_bin, stardoc = stardoc_bin, **kwargs ) @@ -117,9 +143,42 @@ def _create_test_targets( out = actual_generated_doc, input = input_file, deps = [lib_name], - renderer = renderer_bin, stardoc = stardoc_bin, **kwargs ) else: fail("parameter 'test' must either be 'default' or 'html_tables', but was " + test) + +def self_gen_test( + name, + stardoc_doc, + golden_file, + require_starlark_doc_extract, + **kwargs): + """ + A wrapper around `diff_test_runner.sh` for testing Stardoc's own generated documentation. + + Args: + name: A unique name for the test target. + stardoc_doc: The Stardoc output being tested. + golden_file: Expected Stardoc output. + require_starlark_doc_extract: If true, and the native `starlark_doc_extract` rule is not available, + then no test target will not be created. + **kwargs: Additional arguments for the test. + """ + if require_starlark_doc_extract and not hasattr(native, "starlark_doc_extract"): + return + + native.sh_test( + name = name, + srcs = ["diff_test_runner.sh"], + args = [ + "$(location %s)" % golden_file, + "$(location %s)" % stardoc_doc, + ], + data = [ + golden_file, + stardoc_doc, + ], + **kwargs + ) |