Coverage for glotter/test_doc_generator.py: 100%

1import os 

2import shlex 

3 

4from glotter.settings import Settings 

5from glotter.utils import quote 

6 

7 

8def generate_test_docs(doc_dir, repo_name, repo_url): 

9 """ 

10 Generate test documentation for all projects 

11 

12 :param doc_dir: Documentation directory 

13 :param repo_name: Repository name 

14 :param repo_url: Repository URL 

15 """ 

16 

17 settings = Settings() 

18 for project in settings.projects.values(): 

19 test_doc_generator = TestDocGenerator(project) 

20 doc = test_doc_generator.generate_test_doc(repo_name, repo_url) 

21 if doc: 

22 project_dir = os.path.join(doc_dir, "-".join(project.words)) 

23 os.makedirs(project_dir) 

24 project_doc_path = os.path.join(project_dir, "testing.md") 

25 with open(os.path.join(project_doc_path), "w", encoding="utf-8") as f: 

26 f.write(doc) 

27 

28 

29class TestDocGenerator: 

30 __test__ = False # Indicate this is not a test 

31 

32 def __init__(self, project): 

33 self.project = project 

34 self.project_title = " ".join(self.project.words).title() 

35 

36 def generate_test_doc(self, repo_name, repo_url): 

37 if not self.project.tests: 

38 return "" 

39 

40 doc = self._get_test_intro(repo_name, repo_url) 

41 if self.project.requires_parameters: 

42 for test_obj in self.project.tests.values(): 

43 test_doc_section_generator = TestDocSectionGenerator(test_obj) 

44 doc += test_doc_section_generator.get_test_section() 

45 

46 return "\n".join(doc).rstrip() + "\n" 

47 

48 def _get_test_intro(self, repo_name, repo_url): 

49 if not self.project.requires_parameters: 

50 return [ 

51 "Verify that the actual output matches the expected output", 

52 "(see [Requirements](#requirements)).", 

53 ] 

54 

55 doc = [ 

56 f"Every project in the [{repo_name} repo]({repo_url}) should be tested.", 

57 f"In this section, we specify the set of tests specific to {self.project_title}.", 

58 ] 

59 if len(self.project.tests) > 1: 

60 doc += [ 

61 "In order to keep things simple, we split up the testing as follows:", 

62 "", 

63 ] 

64 doc += [ 

65 "- " + _get_test_section_title(test_obj) 

66 for test_obj in self.project.tests.values() 

67 ] 

68 

69 return doc + [""] 

70 

71 

72def _get_test_section_title(test_obj): 

73 return test_obj.name.replace("_", " ").title() + " Tests" 

74 

75 

76class TestDocSectionGenerator: 

77 __test__ = False # Indicate this is not a test 

78 

79 def __init__(self, test_obj): 

80 self.test_obj = test_obj 

81 self.test_obj_name = _get_test_section_title(test_obj) 

82 

83 def get_test_section(self): 

84 return ( 

85 self._get_test_section_header() 

86 + self._get_test_table_header() 

87 + self._get_test_table() 

88 ) 

89 

90 def _get_test_section_header(self): 

91 return [f"### {self.test_obj_name}", ""] 

92 

93 def _get_test_table_header(self): 

94 cells = ["Description"] + self.test_obj.inputs 

95 if self._any_test_output_is_different(): 

96 cells.append("Output") 

97 

98 return [ 

99 _cells_to_table_line(cells), 

100 _cells_to_table_line("-" * len(cell) for cell in cells), 

101 ] 

102 

103 def _any_test_output_is_different(self): 

104 if len(self.test_obj.params) < 2: 

105 return True 

106 

107 first_expected = self.test_obj.params[0].expected 

108 return any( 

109 test_param.expected != first_expected 

110 for test_param in self.test_obj.params[1:] 

111 ) 

112 

113 def _get_test_table(self): 

114 doc = [] 

115 has_output_column = self._any_test_output_is_different() 

116 num_input_params = len(self.test_obj.inputs) 

117 for test_param in self.test_obj.params: 

118 output = test_param.expected 

119 cells = [test_param.name.title()] 

120 if test_param.input is None: 

121 inputs = [] 

122 else: 

123 inputs = shlex.split(test_param.input) 

124 extra_inputs = inputs[num_input_params:] 

125 inputs = inputs[:num_input_params] 

126 cells += [_quote_and_escape_pipe(value) for value in inputs] 

127 if extra_inputs: 

128 cells[-1] += " " + " ".join( 

129 _quote_and_escape_pipe(value) for value in extra_inputs 

130 ) 

131 

132 cells += [""] * (num_input_params - len(inputs)) 

133 

134 if has_output_column: 

135 if isinstance(output, str): 

136 cells.append(_quote_and_escape_pipe(output)) 

137 else: 

138 cells.append( 

139 "<br>".join(_quote_and_escape_pipe(item) for item in output) 

140 ) 

141 

142 doc.append(_cells_to_table_line(cells)) 

143 

144 if not has_output_column: 

145 doc += [ 

146 "", 

147 "All of these tests should output the following:", 

148 "", 

149 "```", 

150 self.test_obj.params[0].expected, 

151 "```", 

152 ] 

153 

154 return doc + [""] 

155 

156 

157def _cells_to_table_line(cells): 

158 return "| " + " | ".join(cells) + " |" 

159 

160 

161def _quote_and_escape_pipe(value): 

162 return quote(value.replace("|", "\\|"))