Pytest权威教程21-API参考-04-钩子(Hooks)

钩子(Hooks)

返回: Pytest权威教程

钩子(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实例