test_util_verify.py (5477B)
1 # This Source Code Form is subject to the terms of the Mozilla Public 2 # License, v. 2.0. If a copy of the MPL was not distributed with this 3 # file, You can obtain one at http://mozilla.org/MPL/2.0/. 4 """ 5 There are some basic tests run as part of the Decision task to make sure 6 documentation exists for taskgraph functionality. 7 These functions are defined in gecko_taskgraph.generator and call 8 gecko_taskgraph.util.verify.verify_docs with different parameters to do the 9 actual checking. 10 """ 11 12 import os.path 13 14 import pytest 15 from mozunit import main 16 17 import gecko_taskgraph.util.verify 18 from gecko_taskgraph import GECKO 19 from gecko_taskgraph.util.verify import DocPaths, verify_docs 20 21 FF_DOCS_BASE = os.path.join(GECKO, "taskcluster", "docs") 22 EXTRA_DOCS_BASE = os.path.abspath(os.path.join(os.path.dirname(__file__), "docs")) 23 24 25 @pytest.fixture 26 def mock_single_doc_path(monkeypatch): 27 """Set a single path containing documentation""" 28 mocked_documentation_paths = DocPaths() 29 mocked_documentation_paths.add(FF_DOCS_BASE) 30 monkeypatch.setattr( 31 gecko_taskgraph.util.verify, "documentation_paths", mocked_documentation_paths 32 ) 33 34 35 @pytest.fixture 36 def mock_two_doc_paths(monkeypatch): 37 """Set two paths containing documentation""" 38 mocked_documentation_paths = DocPaths() 39 mocked_documentation_paths.add(FF_DOCS_BASE) 40 mocked_documentation_paths.add(EXTRA_DOCS_BASE) 41 monkeypatch.setattr( 42 gecko_taskgraph.util.verify, "documentation_paths", mocked_documentation_paths 43 ) 44 45 46 @pytest.mark.usefixtures("mock_single_doc_path") 47 class PyTestSingleDocPath: 48 """ 49 Taskcluster documentation for Firefox is in a single directory. Check the tests 50 running at build time to make sure documentation exists, actually work themselves. 51 """ 52 53 def test_heading(self): 54 """ 55 Look for a headings in filename matching identifiers. This is used when making sure 56 documentation exists for kinds and attributes. 57 """ 58 verify_docs( 59 filename="kinds.rst", 60 identifiers=["build", "packages", "toolchain"], 61 appearing_as="heading", 62 ) 63 with pytest.raises(Exception, match="missing from doc file"): 64 verify_docs( 65 filename="kinds.rst", 66 identifiers=["build", "packages", "badvalue"], 67 appearing_as="heading", 68 ) 69 70 def test_inline_literal(self): 71 """ 72 Look for inline-literals in filename. Used when checking documentation for decision 73 task parameters and run-using functions. 74 """ 75 verify_docs( 76 filename="parameters.rst", 77 identifiers=["base_repository", "head_repository", "owner"], 78 appearing_as="inline-literal", 79 ) 80 with pytest.raises(Exception, match="missing from doc file"): 81 verify_docs( 82 filename="parameters.rst", 83 identifiers=["base_repository", "head_repository", "badvalue"], 84 appearing_as="inline-literal", 85 ) 86 87 88 @pytest.mark.usefixtures("mock_two_doc_paths") 89 class PyTestTwoDocPaths: 90 """ 91 Thunderbird extends Firefox's taskgraph with additional kinds. The documentation 92 for Thunderbird kinds are in its repository, and documentation_paths will have 93 two places to look for files. Run the same tests as for a single documentation 94 path, and cover additional possible scenarios. 95 """ 96 97 def test_heading(self): 98 """ 99 Look for a headings in filename matching identifiers. This is used when 100 making sure documentation exists for kinds and attributes. 101 The first test looks for headings that are all within the first doc path, 102 the second test is new and has a heading found in the second path. 103 The final check has a identifier that will not match and should 104 produce an error. 105 """ 106 verify_docs( 107 filename="kinds.rst", 108 identifiers=["build", "packages", "toolchain"], 109 appearing_as="heading", 110 ) 111 verify_docs( 112 filename="kinds.rst", 113 identifiers=["build", "packages", "newkind"], 114 appearing_as="heading", 115 ) 116 with pytest.raises(Exception, match="missing from doc file"): 117 verify_docs( 118 filename="kinds.rst", 119 identifiers=["build", "packages", "badvalue"], 120 appearing_as="heading", 121 ) 122 123 def test_inline_literal(self): 124 """ 125 Look for inline-literals in filename. Used when checking documentation for decision 126 task parameters and run-using functions. As with the heading tests, 127 the second check looks for an identifier in the added documentation path. 128 """ 129 verify_docs( 130 filename="parameters.rst", 131 identifiers=["base_repository", "head_repository", "owner"], 132 appearing_as="inline-literal", 133 ) 134 verify_docs( 135 filename="parameters.rst", 136 identifiers=["base_repository", "head_repository", "newparameter"], 137 appearing_as="inline-literal", 138 ) 139 with pytest.raises(Exception, match="missing from doc file"): 140 verify_docs( 141 filename="parameters.rst", 142 identifiers=["base_repository", "head_repository", "badvalue"], 143 appearing_as="inline-literal", 144 ) 145 146 147 if __name__ == "__main__": 148 main()