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) for test_obj in self.project.tests.values() 

66 ] 

67 

68 return doc + [""] 

69 

70 

71def _get_test_section_title(test_obj): 

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

73 

74 

75class TestDocSectionGenerator: 

76 __test__ = False # Indicate this is not a test 

77 

78 def __init__(self, test_obj): 

79 self.test_obj = test_obj 

80 self.test_obj_name = _get_test_section_title(test_obj) 

81 

82 def get_test_section(self): 

83 return ( 

84 self._get_test_section_header() + self._get_test_table_header() + self._get_test_table() 

85 ) 

86 

87 def _get_test_section_header(self): 

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

89 

90 def _get_test_table_header(self): 

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

92 if self._any_test_output_is_different(): 

93 cells.append("Output") 

94 

95 return [ 

96 _cells_to_table_line(cells), 

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

98 ] 

99 

100 def _any_test_output_is_different(self): 

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

102 return True 

103 

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

105 return any(test_param.expected != first_expected for test_param in self.test_obj.params[1:]) 

106 

107 def _get_test_table(self): 

108 doc = [] 

109 has_output_column = self._any_test_output_is_different() 

110 num_input_params = len(self.test_obj.inputs) 

111 for test_param in self.test_obj.params: 

112 output = test_param.expected 

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

114 if test_param.input is None: 

115 inputs = [] 

116 else: 

117 inputs = shlex.split(test_param.input) 

118 extra_inputs = inputs[num_input_params:] 

119 inputs = inputs[:num_input_params] 

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

121 if extra_inputs: 

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

123 _quote_and_escape_pipe(value) for value in extra_inputs 

124 ) 

125 

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

127 

128 if has_output_column: 

129 if isinstance(output, str): 

130 cells.append(_quote_and_escape_pipe(output)) 

131 else: 

132 cells.append("<br>".join(_quote_and_escape_pipe(item) for item in output)) 

133 

134 doc.append(_cells_to_table_line(cells)) 

135 

136 if not has_output_column: 

137 doc += [ 

138 "", 

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

140 "", 

141 "```", 

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

143 "```", 

144 ] 

145 

146 return doc + [""] 

147 

148 

149def _cells_to_table_line(cells): 

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

151 

152 

153def _quote_and_escape_pipe(value): 

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