钩子(Hooks)
参考: 编写插件。
引用可由conftest.py文件实现的所有Hook方法。
引导时的Hook方法
引导时的Hook方法要求尽早注册插件(内部和setuptools插件)。
pytest_load_initial_conftests(early_config,parser,args): 在命令行选项解析之前实现初始conftest文件的加载。
注意：不会为
conftest.py文件调用此Hook方法,仅适用于setuptools插件。
参数：
- early_config(_pytest.config.Config) - pytest配置对象
- args(list**]) - 在命令行上传递的参数列表
- 解析器(_pytest.config.Parser) - 添加命令行选项
pytest_cmdline_preparse(config,args): (不推荐)在选项解析之前修改命令行参数。
此钩子被认为已弃用,将在未来的pytest版本中删除。考虑pytest_load_initial_conftests()改用。
注意：不会为
conftest.py文件调用此Hook方法,仅适用于setuptools插件。
参数：
- config(_pytest.config.Config) - pytest配置对象
- args(list**]) - 在命令行上传递的参数列表
pytest_cmdline_parse(pluginmanager,args): 返回初始化的配置对象,解析指定的args。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
注意：
plugins当使用[pytest.main为传递给arg的插件类调用此挂接。
参数：
- pluginmanager(_pytest.config.PytestPluginManager) - pytest插件管理器
- args(list**]) - 在命令行上传递的参数列表
pytest_cmdline_main(config): 要求执行主命令行动作。默认实现将调用configure hooks和runtest_mainloop。
注意：不会为
conftest.py文件调用此Hook方法,仅适用于setuptools插件。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
参数：
- config(_pytest.config.Config) - pytest配置对象
初始化时的Hook方法
初始化时的Hook方法调用插件和conftest.py文件。
pytest_addoption(解析器): 注册argparse-style选项和ini-style配置值,在测试运行开始时调用一次。
注意：
conftest.py由于pytest[在启动期间发现插件的方式,此函数应仅在位于测试根目录的插件或文件中实现。
参数：
- 解析器(_pytest.config.Parser) - 要添加命令行选项,请调用
parser.addoption(...)。添加ini文件值调用parser.addini(...)。
以后可以config分别通过对象访问选项：
config.getoption(name)检索命令行选项的值。config.getini(name)检索从ini样式文件中读取的值。
配置对象通过.config属性在许多内部对象上传递,或者可以作为pytestconfigFixture方法检索。
注意：这个Hook方法与
hookwrapper=True冲突。
pytest_addhooks(pluginmanager): 在插件注册时调用,允许通过调用添加新的Hook方法。
pluginmanager.add_hookspecs(module_or_class,prefix)
参数：
- pluginmanager(_pytest.config.PytestPluginManager) - pytest插件管理器
注意：这个钩子与之不相容
hookwrapper=True。
pytest_configure(config): 允许插件和conftest文件执行初始配置。
在解析了命令行选项后,为每个插件和初始conftest文件调用此Hook方法。
之后,在导入钩子时会调用其他conftest文件。
注意：这个钩子与之不相容
hookwrapper=True。
参数：
- config(_pytest.config.Config) - pytest配置对象
pytest_unconfigure(config): 在退出测试过程之前调用。
参数：
- config(_pytest.config.Config) - pytest配置对象
pytest_sessionstart(session): 在Session创建对象之后以及执行收集和进入运行测试循环之前调用。
参数：
- session(_pytest.main.Session) - pytest会话对象
pytest_sessionfinish(session,exitstatus): 在整个测试运行完成之后调用,在将退出状态返回到系统之前。
参数：
- session(_pytest.main.Session) - pytest会话对象
- exitstatus(int) - pytest将返回系统的状态
pytest_plugin_registered(plugin,manager):一个新的pytest插件已注册。
参数：
- 插件- 插件模块或实例
- manager(_pytest.config.PytestPluginManager) - pytest插件管理器
注意：这个钩子与之不相容
hookwrapper=True。
测试运行时的Hook方法
所有与runtest相关的钩子都会收到一个pytest.Item对象。
pytest_runtestloop(会话): 要求执行主运行测试循环(收集完成后)。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
参数：
- session(_pytest.main.Session) - pytest会话对象
pytest_runtest_protocol(item,nextitem): 为给定的测试项实现runtest_setup / call / teardown协议,包括捕获异常和调用报告Hook方法。
参数：
- item- 为其执行运行测试协议的测试项目。
- nextitem- 预定下一个测试项目(如果这是我朋友的结束,则为无)。这个论点被传递给了
pytest_runtest_teardown()。
返回布尔值：如果不应调用其他钩子实现,则为True。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
pytest_runtest_logstart(nodeid,location): 发出运行单个测试项目的信号。
在调用pytest_runtest_setup()Hook方法之前会调用此Hook方法。
参数：
- nodeid(str) - 项目的完整ID
- location- 三倍(filename,linenum,testname)`
pytest_runtest_logfinish(nodeid,location): 发出运行单个测试项目的完整信号。
调用pytest_runtest_setup()Hook方法之后, 调用此Hook方法。
参数：
- nodeid(str) - 项目的完整ID
- location- (filename,linenum,testname)`三者的组合
pytest_runtest_setup(item): 以前称作pytest_runtest_call(item)。
pytest_runtest_call(item): 调用以执行测试项。
pytest_runtest_teardown(item,nextitem): 在pytest_runtest_call之后调用。
参数：
- nextitem- 计划下一个测试项目(如果没有安排其他测试项目,则为None)。这个参数可以用来执行精确的拆卸,即调用足够的终结器,以便nextitem只需要调用setup-functions。
pytest_runtest_makereport(item,call): 返回_pytest.runner.TestReport。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
为了更深入地理解,你可以查看这些Hook方法的默认实现,_pytest.runner也可能与其_pytest.pdb进行交互_pytest.capture以及其输入/输出捕获,以便在发生测试失败时立即进入交互式调试。
在_pytest.terminal具体报告使用报告Hook方法,打印有关测试运行的信息。
pytest_pyfunc_call(pyfuncitem): 调用底层测试函数。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
收集用例时的Hook方法
pytest调用以下Hook方法来来收集测试文件及目录：
pytest_collection(session): 执行给定会话的收集协议。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止。
参数：
- session(_pytest.main.Session) - pytest会话对象
pytest_ignore_collect(path,config): 返回True以防止考虑此收集路径。在调用更具体的钩子之前,会查询所有文件和目录的钩子。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
参数：
- path(str) - 要分析的路径
- config(_pytest.config.Config) - pytest配置对象
pytest_collect_directory(path,parent): 在遍历目录以获取集合文件之前调用。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
参数：
- path(str) - 要分析的路径
pytest_collect_file(path,parent): 返回集合给定路径的节点或无。任何新节点都需要将指定parent的父节点作为父节点。
参数：
- path(str) - 要收集的路径
pytest_pycollect_makemodule(路径,父母): 返回给定路径的Module收集器或None。将为每个匹配的测试模块路径调用此Hook方法。如果要为不匹配的文件创建测试模块作为测试模块,则需要使用pytest_collect_fileHook方法。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
要影响Python模块中的对象集合,可以使用以下Hook方法：
pytest_pycollect_makeitem(收藏家,名字,obj): 返回模块中python对象的自定义项/收集器,或者无。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
pytest_generate_tests(metafunc): 生成(多个)参数化调用到测试函数。
pytest_make_parametrize_id(config,val,argname): 返回val@ pytest.mark.parametrize调用将使用的给定的用户友好字符串表示形式。如果钩子不知道,则返回Noneval。argname如果需要,参数名称可用。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
参数：
- config(_pytest.config.Config) - pytest配置对象
- val- 参数化值
- argname(str) - pytest生成的自动参数名称
收集完成后,你可以修改项目的顺序,删除或以其他方式修改测试项目：
pytest_collection_modifyitems(会话,配置,项目): 在执行收集后调用,可以就地过滤或重新排序项目。
参数：
- session(_pytest.main.Session) - pytest会话对象
- config(_pytest.config.Config) - pytest配置对象
- items(List**_pytest.nodes.Item**]) - 项目对象列表
pytest_collection_finish(会话): 在执行和修改集合后调用。
参数：
- session(_pytest.main.Session) - pytest会话对象
生成测试结果时的Hook方法
与会话报告相关的Hook方法：
pytest_collectstart(collector): Collector开始收集。
pytest_make_collect_report(collector): 执行collector.collect()并返回CollectReport。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
pytest_itemcollected(item): 我们刚收集了一个测试项目。
pytest_collectreport(report): Collector完成收集。
pytest_deselected(items): 要求通过关键字取消选择的测试项目。
pytest_report_header(config,startdir): 返回一个字符串或字符串列表,以显示为终端报告的标题信息。
参数：
- config(_pytest.config.Config) - pytest配置对象
- startdir- 带起始目录的py.path对象
注意：
conftest.py由于pytest在启动期间发现插件的方式,此函数应仅在位于测试根目录的插件或文件中实现。
pytest_report_collectionfinish(config,startdir,items): 返回集合成功完成后要显示的字符串或字符串列表。
此字符串将显示在标准的“收集的X项目”消息之后。
版本3.2中的新函数。
参数：
- config(_pytest.config.Config) - pytest配置对象
- startdir- 带起始目录的py.path对象
- items- 将要执行的pytest项列表;此列表不应修改。
pytest_report_teststatus(报告,配置): 返回结果类别,简短和冗长的报告单词。
参数：
- config(_pytest.config.Config) - pytest配置对象
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
pytest_terminal_summary(terminalreporter,exitstatus,config): 在终端摘要报告中添加一个部分。
参数：
- terminalreporter(_pytest.terminal.TerminalReporter) - 内部终端报告对象
- exitstatus(int) - 将报告回操作系统的退出状态
- config(_pytest.config.Config) - pytest配置对象
新的4.2版：该config参数。
pytest_fixture_setup(fixturedef,request): 执行Fixture方法设置执行。
返回：调用fixture函数的返回值
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
注意：如果fixture函数返回None,则将根据firstresult选项。
pytest_fixture_post_finalizer(fixturedef,request): 在Fixture方法拆卸后调用,但在清除缓存之前,fixturedef.cached_result仍然可以访问Fixture方法结果缓存。
pytest_warning_captured(warning_message,when,item): 处理内部pytest warnings插件捕获的警告。
参数：
- warning_message(warnings.WarningMessage) - 捕获的警告。这与生成的对象相同
warnings.catch_warnings(),并且包含与参数相同的属性warnings.showwarning()。 - when(str) -
指示何时捕获警告。可能的值："config"：在pytest配置/初始化阶段。"collect"：在测试收集期间。"runtest"：在测试执行期间。
- item(pytest.Item None) -
DEPRECATED：此参数与以后版本不兼容pytest-xdist,并且将始终None在以后的版本中接收。
正在执行的项目,如果when是"runtest",否则None。
这是报告测试执行的中心Hook方法：
pytest_runtest_logreport(report): 处理与执行测试的相应阶段有关的测试设置/调用/拆除报告。
断言相关Hook方法：
pytest_assertrepr_compare(config,op,left,right): 返回失败的断言表达式中的比较解释。
如果没有自定义说明,则返回None,否则返回字符串列表。该字符串将通过新行被加入,但任何换行符在字符串将被转义。请注意,除第一行外的所有行都将略微缩进,目的是将第一行作为摘要。
参数：
- config(_pytest.config.Config) - pytest配置对象
pytest_assertion_pass(item, lineno, orig, expl): 每当断言通过时,Hook就会调用。
在传递断言后使用此Hook方法进行一些处理。 原始断言信息在orig字符串中可用,而pytest内省断言信息在expl字符串中可用。
必须通过enable_assertion_pass_hook ini-file选项显式启用此Hook方法：
[pytest]
enable_assertion_pass_hook=true
启用此选项时,需要清除项目目录和解释器库中的.pyc文件,因为断言需要重写。
参数：
- item(_pytest.nodes.Item) - 当前测试的pytest项目对象
- lineno(int) - 断言语句的行号
- orig(string) - 带有原始断言的字符串
- expl(string) - 带有断言解释的字符串
注意：这个Hook方法是实验性的,因此它的参数甚至钩子本身可能会在未来的任何pytest版本中被更改/删除而不会发出警告。
如果您发现此Hook有用,请分享您的反馈,以解决问题。
调试/交互Hook方法
很少有Hook方法可用于特殊报告或与异常交互：
pytest_internalerror(excrepr,excinfo): 内部出错时调用。
pytest_keyboard_interrupt(excinfo): 键盘中断时调用。
pytest_exception_interact(节点,呼叫,报告): 在引发异常时调用,可以交互式处理。
只有在引发的异常不是内部异常, 如skip.Exception时才会调用此Hook方法。
pytest_enter_pdb(config,pdb): 调用pdb.set_trace()时,插件可以使用插件在python调试器进入交互模式之前采取特殊操作。
参数：
- config(_pytest.config.Config) - pytest配置对象
- pdb(pdb.Pdb) - Pdb实例