diff options
author | 2015-11-18 16:16:22 +0000 | |
---|---|---|
committer | 2015-11-19 09:58:57 +0000 | |
commit | 251d75475e90567a1b3752af26ec185cbdc09d10 (patch) | |
tree | 79fee53adcaea559c35c06031721461df77de340 /src | |
parent | 47ea94897a06fac211609d62b92f0548e3fdfb4d (diff) |
Open source BazelDocumentationTest (and fix documentation).
--
MOS_MIGRATED_REVID=108145081
Diffstat (limited to 'src')
3 files changed, 184 insertions, 3 deletions
diff --git a/src/test/java/com/google/devtools/build/lib/BUILD b/src/test/java/com/google/devtools/build/lib/BUILD index 370614ecac..3f776a9eb7 100644 --- a/src/test/java/com/google/devtools/build/lib/BUILD +++ b/src/test/java/com/google/devtools/build/lib/BUILD @@ -490,8 +490,10 @@ java_library( deps = [ ":foundations_testutil", ":testutil", + "//src/main/java/com/google/devtools/build/docgen", "//src/main/java/com/google/devtools/build/lib:analysis-exec-rules-skyframe", "//src/main/java/com/google/devtools/build/lib:bazel-core", + "//src/main/java/com/google/devtools/build/lib:buildtool-runtime", "//src/main/java/com/google/devtools/build/lib:clock", "//src/main/java/com/google/devtools/build/lib:events", "//src/main/java/com/google/devtools/build/lib:io", @@ -512,9 +514,14 @@ java_library( java_test( name = "packages_test", - srcs = glob([ - "packages/*.java", - ]), + srcs = glob( + [ + "packages/*.java", + ], + exclude = [ + "packages/BazelDocumentationTest.java", + ], + ), args = ["com.google.devtools.build.lib.AllTests"], deps = [ ":actions_testutil", @@ -666,6 +673,26 @@ java_test( ], ) +java_test( + name = "BazelDocumentationTests", + size = "medium", + srcs = ["packages/BazelDocumentationTest.java"], + data = [ + "//site:docs/bazel-user-manual.html", + ], + deps = [ + ":foundations_testutil", + ":packages_testutil", + "//src/main/java/com/google/devtools/build/lib:bazel-core", + "//src/main/java/com/google/devtools/build/lib:packages", + "//third_party:guava", + "//third_party:guava-testlib", + "//third_party:jsr305", + "//third_party:junit4", + "//third_party:truth", + ], +) + java_library( name = "syntax_testutil", srcs = glob([ diff --git a/src/test/java/com/google/devtools/build/lib/packages/BazelDocumentationTest.java b/src/test/java/com/google/devtools/build/lib/packages/BazelDocumentationTest.java new file mode 100644 index 0000000000..371789359b --- /dev/null +++ b/src/test/java/com/google/devtools/build/lib/packages/BazelDocumentationTest.java @@ -0,0 +1,49 @@ +// Copyright 2015 The Bazel Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package com.google.devtools.build.lib.packages; + +import static java.nio.charset.StandardCharsets.UTF_8; + +import com.google.common.io.Files; +import com.google.devtools.build.lib.analysis.config.BuildConfiguration; + +import com.google.devtools.build.lib.bazel.BazelMain; +import com.google.devtools.build.lib.bazel.rules.BazelRuleClassProvider; +import com.google.devtools.build.lib.packages.util.DocumentationTestUtil; + +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.JUnit4; + +import java.io.File; + +/** + * Test for Bazel documentation. + */ +@RunWith(JUnit4.class) +public class BazelDocumentationTest { + /** + * Checks that the blaze-user-manual is in sync with the + * {@link BuildConfiguration}. + */ + @Test + public void testBazelUserManual() throws Exception { + final File documentationFile = new File("site/docs/bazel-user-manual.html"); + DocumentationTestUtil.validateUserManual( + BazelMain.BAZEL_MODULES, + BazelRuleClassProvider.create(), + Files.asCharSource(documentationFile, UTF_8).read()); + } +} diff --git a/src/test/java/com/google/devtools/build/lib/packages/util/DocumentationTestUtil.java b/src/test/java/com/google/devtools/build/lib/packages/util/DocumentationTestUtil.java new file mode 100644 index 0000000000..0836b5fdfd --- /dev/null +++ b/src/test/java/com/google/devtools/build/lib/packages/util/DocumentationTestUtil.java @@ -0,0 +1,105 @@ +// Copyright 2015 The Bazel Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package com.google.devtools.build.lib.packages.util; + +import static com.google.common.truth.Truth.assertWithMessage; + +import com.google.common.collect.Iterables; +import com.google.devtools.build.docgen.DocCheckerUtils; +import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider; +import com.google.devtools.build.lib.runtime.BlazeCommand; +import com.google.devtools.build.lib.runtime.BlazeCommandUtils; +import com.google.devtools.build.lib.runtime.BlazeModule; +import com.google.devtools.build.lib.runtime.BlazeRuntime; +import com.google.devtools.common.options.Options; +import com.google.devtools.common.options.OptionsBase; + +import java.io.IOException; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +/** + * Utility functions for validating correctness of Bazel documentation. + */ +public abstract class DocumentationTestUtil { + + private DocumentationTestUtil() {} + + private static final Pattern CODE_FLAG_PATTERN = + Pattern.compile( + "<code class\\s*=\\s*[\"']flag[\"']\\s*>--([a-z_\\[\\]]*)<\\/code>", + Pattern.CASE_INSENSITIVE); + + /** + * Validates that a user manual {@code documentationSource} contains only + * the flags actually provided by a given set of modules. + */ + public static void validateUserManual( + List<Class<? extends BlazeModule>> modules, + ConfiguredRuleClassProvider ruleClassProvider, String documentationSource) + throws IOException { + // if there is a class missing, one can find it using + // find . -name "*.java" -exec grep -Hn "@Option(name = " {} \; | grep "xxx" + // where 'xxx' is a flag name. + List<BlazeModule> blazeModules = BlazeRuntime.createModules(modules); + + Map<String, Object> optionsMap = new HashMap<>(); + + // collect all startup options + for (Class<? extends OptionsBase> optionsClass : + BlazeCommandUtils.getStartupOptions(blazeModules)) { + optionsMap.putAll(Options.getDefaults(optionsClass).asMap()); + } + + // collect all command options + List<BlazeCommand> blazeCommands = new ArrayList<>(); + blazeCommands.addAll(BlazeRuntime.getBuiltinCommandList()); + for (BlazeModule module : blazeModules) { + Iterables.addAll(blazeCommands, module.getCommands()); + } + + for (BlazeCommand command : blazeCommands) { + for (Class<? extends OptionsBase> optionClass : + BlazeCommandUtils.getOptions(command.getClass(), blazeModules, ruleClassProvider)) { + optionsMap.putAll(Options.getDefaults(optionClass).asMap()); + } + } + + // check validity of option flags in manual + Matcher anchorMatcher = CODE_FLAG_PATTERN.matcher(documentationSource); + String flag; + boolean found; + + while (anchorMatcher.find()) { + flag = anchorMatcher.group(1); + found = optionsMap.containsKey(flag); + if (!found && flag.startsWith("no")) { + found = optionsMap.containsKey(flag.substring(2)); + } + if (!found && flag.startsWith("[no]")) { + found = optionsMap.containsKey(flag.substring(4)); + } + + assertWithMessage("flag '" + flag + "' is not a blaze option (anymore)").that(found).isTrue(); + } + + String unclosedTag = DocCheckerUtils.getFirstUnclosedTagAndPrintHelp(documentationSource); + assertWithMessage("Unclosed tag found: " + unclosedTag).that(unclosedTag).isNull(); + } +} |