Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1""" 

2support for presenting detailed information in failing assertions. 

3""" 

4import sys 

5from typing import Any 

6from typing import Generator 

7from typing import List 

8from typing import Optional 

9 

10from _pytest.assertion import rewrite 

11from _pytest.assertion import truncate 

12from _pytest.assertion import util 

13from _pytest.assertion.rewrite import assertstate_key 

14from _pytest.compat import TYPE_CHECKING 

15from _pytest.config import Config 

16from _pytest.config import hookimpl 

17from _pytest.config.argparsing import Parser 

18from _pytest.nodes import Item 

19 

20if TYPE_CHECKING: 

21 from _pytest.main import Session 

22 

23 

24def pytest_addoption(parser: Parser) -> None: 

25 group = parser.getgroup("debugconfig") 

26 group.addoption( 

27 "--assert", 

28 action="store", 

29 dest="assertmode", 

30 choices=("rewrite", "plain"), 

31 default="rewrite", 

32 metavar="MODE", 

33 help=( 

34 "Control assertion debugging tools.\n" 

35 "'plain' performs no assertion debugging.\n" 

36 "'rewrite' (the default) rewrites assert statements in test modules" 

37 " on import to provide assert expression information." 

38 ), 

39 ) 

40 parser.addini( 

41 "enable_assertion_pass_hook", 

42 type="bool", 

43 default=False, 

44 help="Enables the pytest_assertion_pass hook." 

45 "Make sure to delete any previously generated pyc cache files.", 

46 ) 

47 

48 

49def register_assert_rewrite(*names: str) -> None: 

50 """Register one or more module names to be rewritten on import. 

51 

52 This function will make sure that this module or all modules inside 

53 the package will get their assert statements rewritten. 

54 Thus you should make sure to call this before the module is 

55 actually imported, usually in your __init__.py if you are a plugin 

56 using a package. 

57 

58 :raise TypeError: if the given module names are not strings. 

59 """ 

60 for name in names: 

61 if not isinstance(name, str): 

62 msg = "expected module names as *args, got {0} instead" 

63 raise TypeError(msg.format(repr(names))) 

64 for hook in sys.meta_path: 

65 if isinstance(hook, rewrite.AssertionRewritingHook): 

66 importhook = hook 

67 break 

68 else: 

69 # TODO(typing): Add a protocol for mark_rewrite() and use it 

70 # for importhook and for PytestPluginManager.rewrite_hook. 

71 importhook = DummyRewriteHook() # type: ignore 

72 importhook.mark_rewrite(*names) 

73 

74 

75class DummyRewriteHook: 

76 """A no-op import hook for when rewriting is disabled.""" 

77 

78 def mark_rewrite(self, *names: str) -> None: 

79 pass 

80 

81 

82class AssertionState: 

83 """State for the assertion plugin.""" 

84 

85 def __init__(self, config: Config, mode) -> None: 

86 self.mode = mode 

87 self.trace = config.trace.root.get("assertion") 

88 self.hook = None # type: Optional[rewrite.AssertionRewritingHook] 

89 

90 

91def install_importhook(config: Config) -> rewrite.AssertionRewritingHook: 

92 """Try to install the rewrite hook, raise SystemError if it fails.""" 

93 config._store[assertstate_key] = AssertionState(config, "rewrite") 

94 config._store[assertstate_key].hook = hook = rewrite.AssertionRewritingHook(config) 

95 sys.meta_path.insert(0, hook) 

96 config._store[assertstate_key].trace("installed rewrite import hook") 

97 

98 def undo() -> None: 

99 hook = config._store[assertstate_key].hook 

100 if hook is not None and hook in sys.meta_path: 

101 sys.meta_path.remove(hook) 

102 

103 config.add_cleanup(undo) 

104 return hook 

105 

106 

107def pytest_collection(session: "Session") -> None: 

108 # this hook is only called when test modules are collected 

109 # so for example not in the master process of pytest-xdist 

110 # (which does not collect test modules) 

111 assertstate = session.config._store.get(assertstate_key, None) 

112 if assertstate: 

113 if assertstate.hook is not None: 

114 assertstate.hook.set_session(session) 

115 

116 

117@hookimpl(tryfirst=True, hookwrapper=True) 

118def pytest_runtest_protocol(item: Item) -> Generator[None, None, None]: 

119 """Setup the pytest_assertrepr_compare and pytest_assertion_pass hooks 

120 

121 The rewrite module will use util._reprcompare if 

122 it exists to use custom reporting via the 

123 pytest_assertrepr_compare hook. This sets up this custom 

124 comparison for the test. 

125 """ 

126 

127 ihook = item.ihook 

128 

129 def callbinrepr(op, left: object, right: object) -> Optional[str]: 

130 """Call the pytest_assertrepr_compare hook and prepare the result 

131 

132 This uses the first result from the hook and then ensures the 

133 following: 

134 * Overly verbose explanations are truncated unless configured otherwise 

135 (eg. if running in verbose mode). 

136 * Embedded newlines are escaped to help util.format_explanation() 

137 later. 

138 * If the rewrite mode is used embedded %-characters are replaced 

139 to protect later % formatting. 

140 

141 The result can be formatted by util.format_explanation() for 

142 pretty printing. 

143 """ 

144 hook_result = ihook.pytest_assertrepr_compare( 

145 config=item.config, op=op, left=left, right=right 

146 ) 

147 for new_expl in hook_result: 

148 if new_expl: 

149 new_expl = truncate.truncate_if_required(new_expl, item) 

150 new_expl = [line.replace("\n", "\\n") for line in new_expl] 

151 res = "\n~".join(new_expl) 

152 if item.config.getvalue("assertmode") == "rewrite": 

153 res = res.replace("%", "%%") 

154 return res 

155 return None 

156 

157 saved_assert_hooks = util._reprcompare, util._assertion_pass 

158 util._reprcompare = callbinrepr 

159 

160 if ihook.pytest_assertion_pass.get_hookimpls(): 

161 

162 def call_assertion_pass_hook(lineno: int, orig: str, expl: str) -> None: 

163 ihook.pytest_assertion_pass(item=item, lineno=lineno, orig=orig, expl=expl) 

164 

165 util._assertion_pass = call_assertion_pass_hook 

166 

167 yield 

168 

169 util._reprcompare, util._assertion_pass = saved_assert_hooks 

170 

171 

172def pytest_sessionfinish(session: "Session") -> None: 

173 assertstate = session.config._store.get(assertstate_key, None) 

174 if assertstate: 

175 if assertstate.hook is not None: 

176 assertstate.hook.set_session(None) 

177 

178 

179def pytest_assertrepr_compare( 

180 config: Config, op: str, left: Any, right: Any 

181) -> Optional[List[str]]: 

182 return util.assertrepr_compare(config=config, op=op, left=left, right=right)