Pytest权威教程21-API参考-04-钩子(Hooks)
钩子函数(Hooks)
参考: 编写插件
引用可由conftest.py文件实现的所有钩子函数。
初始化时的钩子函数
初始化时的钩子函数调用插件和conftest.py文件。
pytest_addoption(parser)
注册argparse-style选项和ini-style配置值,在测试运行开始时调用一次。
注意：
conftest.py由于pytest[在启动期间发现插件的方式,此函数应仅在位于测试根目录的插件或文件中实现。
参数：
- parser(_pytest.config.Parser) - 要添加命令行选项,请调用
parser.addoption(...)。添加ini文件值调用parser.addini(...)。
以后可以config分别通过对象访问选项：
config.getoption(name)检索命令行选项的值。config.getini(name)检索从ini样式文件中读取的值。
配置对象通过.config属性在许多内部对象上传递,或者可以作为pytestconfigFixture方法检索。
注意：这个钩子函数与
hookwrapper=True冲突。
pytest_addhooks(pluginmanager)
在插件注册时调用,允许通过调用添加新的钩子函数。
pluginmanager.add_hookspecs(module_or_class,prefix)
参数：
- pluginmanager(_pytest.config.PytestPluginManager) - pytest插件管理器
注意：这个钩子与之不相容
hookwrapper=True。
pytest_configure(config)
允许插件和conftest文件执行初始配置。
在解析了命令行选项后,为每个插件和初始conftest文件调用此钩子函数。
之后,在导入钩子时会调用其他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。
启动时的钩子函数
启动时的钩子函数要求尽早注册插件(内部和setuptools插件)。
pytest_load_initial_conftests(early_config,parser,args)
在命令行选项解析之前实现初始conftest文件的加载。
注意：不会为
conftest.py文件调用此钩子函数,仅适用于setuptools插件。
参数：
- early_config(_pytest.config.Config) - pytest配置对象
- args(list**]) - 在命令行上传递的参数列表
- parser(_pytest.config.Parser) - 添加命令行选项
pytest_cmdline_preparse(config,args)
(不推荐)在选项解析之前修改命令行参数。
此钩子被认为已弃用,将在未来的pytest版本中删除。考虑pytest_load_initial_conftests()改用。
注意：不会为
conftest.py文件调用此钩子函数,仅适用于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文件调用此钩子函数,仅适用于setuptools插件。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
参数：
- config(_pytest.config.Config) - pytest配置对象
收集用例时的钩子函数
pytest调用以下钩子函数来来收集测试文件及目录：
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_file(path,parent)
返回集合给定路径的节点或无。任何新节点都需要将指定parent的父节点作为父节点。
参数：
- path(str) - 要收集的路径
pytest_pycollect_makemodule(path,parent)
返回给定路径的Module收集器或None。将为每个匹配的测试模块路径调用此钩子函数。如果要为不匹配的文件创建测试模块作为测试模块,则需要使用pytest_collect_file钩子函数。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
要影响Python模块中的对象集合,可以使用以下钩子函数：
pytest_pycollect_makeitem(collector,name,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,config)
在执行收集后调用,可以就地过滤或重新排序项目。
参数：
- session(_pytest.main.Session) - pytest会话对象
- config(_pytest.config.Config) - pytest配置对象
- items(List**_pytest.nodes.Item**]) - 项目对象列表
pytest_collection_finish(session)
在执行和修改集合后调用。
参数：
- session(_pytest.main.Session) - pytest会话对象
执行用例时的钩子函数
所有与runtest相关的钩子都会收到一个pytest.Item对象。
pytest_runtestloop(session)
要求执行主运行测试循环(收集完成后)。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
参数：
- session(_pytest.main.Session) - pytest会话对象
pytest_runtest_protocol(item,nextitem)
为给定的测试项实现runtest_setup / call / teardown协议,包括捕获异常和调用报告钩子函数。
参数：
- item- 为其执行运行测试协议的测试项目。
- nextitem- 预定下一个测试项目(如果这是我朋友的结束,则为无)。这个论点被传递给了
pytest_runtest_teardown()。
返回布尔值：如果不应调用其他钩子实现,则为True。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
pytest_runtest_logstart(nodeid,location)
发出运行单个测试项目的信号。
在调用pytest_runtest_setup()钩子函数之前会调用此钩子函数。
参数：
- nodeid(str) - 项目的完整ID
- location- 三倍(filename,linenum,testname)`
pytest_runtest_logfinish(nodeid,location)
发出运行单个测试项目的完整信号。
调用pytest_runtest_setup()钩子函数之后, 调用此钩子函数。
参数：
- 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：在第一个非空结果处停止
为了更深入地理解,你可以查看这些钩子函数的默认实现,_pytest.runner也可能与其_pytest.pdb进行交互_pytest.capture以及其输入/输出捕获,以便在发生测试失败时立即进入交互式调试。
在_pytest.terminal具体报告使用报告钩子函数,打印有关测试运行的信息。
pytest_pyfunc_call(pyfuncitem)
调用底层测试函数。
在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止
生成测试结果时的钩子函数
与会话报告相关的钩子函数
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(report,config)
返回结果类别,简短和冗长的报告单词。
参数：
- 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。
这是报告测试执行的中心钩子函数：
pytest_runtest_logreport(report)
处理与执行测试的相应阶段有关的测试设置/调用/拆除报告。
断言相关钩子函数
pytest_assertrepr_compare(config,op,left,right)
返回失败的断言表达式中的比较解释。
如果没有自定义说明,则返回None,否则返回字符串列表。该字符串将通过新行被加入,但任何换行符在字符串将被转义。请注意,除第一行外的所有行都将略微缩进,目的是将第一行作为摘要。
参数：
- config(_pytest.config.Config) - pytest配置对象
pytest_assertion_pass(item, lineno, orig, expl)
每当断言通过时,Hook就会调用。
在传递断言后使用此钩子函数进行一些处理。 原始断言信息在orig字符串中可用,而pytest内省断言信息在expl字符串中可用。
必须通过enable_assertion_pass_hook ini-file选项显式启用此钩子函数：
[pytest]
enable_assertion_pass_hook=true
启用此选项时,需要清除项目目录和解释器库中的.pyc文件,因为断言需要重写。
参数：
- item(_pytest.nodes.Item) - 当前测试的pytest项目对象
- lineno(int) - 断言语句的行号
- orig(string) - 带有原始断言的字符串
- expl(string) - 带有断言解释的字符串
注意：这个钩子函数是实验性的,因此它的参数甚至钩子本身可能会在未来的任何pytest版本中被更改/删除而不会发出警告。
如果您发现此Hook有用,请分享您的反馈,以解决问题。
调试/交互钩子函数
很少有钩子函数可用于特殊报告或与异常交互：
pytest_internalerror(excrepr,excinfo)
内部出错时调用。
pytest_keyboard_interrupt(excinfo)
键盘中断时调用。
pytest_exception_interact(node,call,report)
在引发异常时调用,可以交互式处理。
只有在引发的异常不是内部异常, 如skip.Exception时才会调用此钩子函数。
pytest_enter_pdb(config,pdb)
调用pdb.set_trace()时,插件可以使用插件在python调试器进入交互模式之前采取特殊操作。
参数：
- config(_pytest.config.Config) - pytest配置对象
- pdb(pdb.Pdb) - Pdb实例
