pytest--钩子

可由conftest.py文件来引用我们实现的所有Hook方法。

 

一、引导时的Hook方法

引导时的Hook方法要求尽早注册插件(内部和setuptools插件)。

1.pytest_load_initial_conftests(early_config,parser,args): 在命令行选项解析之前实现初始conftest文件的加载。

参数：

• early_config(_pytest.config.Config) - pytest配置对象
• args(list**]) - 在命令行上传递的参数列表
• 解析器(_pytest.config.Parser) - 添加命令行选项

注意：仅适用于setuptools插件。

 

2.pytest_cmdline_preparse(config,args): (不推荐)在选项解析之前修改命令行参数。

此钩子被认为已弃用,将在未来的pytest版本中删除。考虑pytest_load_initial_conftests()改用。

参数：

• config(_pytest.config.Config) - pytest配置对象
• args(list**]) - 在命令行上传递的参数列表

注意：仅适用于setuptools插件。

 

3.pytest_cmdline_parse(pluginmanager,args): 解析指定的args，返回初始化的配置对象。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

参数：

• pluginmanager(_pytest.config.PytestPluginManager) - pytest插件管理器
• args(list**]) - 在命令行上传递的参数列表

注意：plugins当使用[pytest.main为传递给arg的插件类调用此挂接。

 

4.pytest_cmdline_main(config): 执行命令行动作。

默认实现将调用configure hooks和runtest_mainloop。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

参数：

• config(_pytest.config.Config) - pytest配置对象

注意：仅适用于setuptools插件。

 

二、初始化时的Hook方法

初始化时的Hook方法调用插件和conftest.py文件。

1.pytest_addoption(parser): 添加命令行或ini参数，在测试运行开始时调用一次。

参数：

• parser(_pytest.config.Parser) -

要添加命令行选项,请调用parser.addoption(...)。添加ini文件值调用parser.addini(...)。

然后后可以config分别通过对象访问选项：

• config.getoption(name)检索命令行选项的值。
• config.getini(name)检索从ini样式文件中读取的值。

配置对象通过.config属性在许多内部对象上传递,或者可以作为pytestconfigFixture方法检索。

注意：这个Hook方法与hookwrapper=True冲突。

 

2.pytest_addhooks(pluginmanager): 在插件注册时调用,允许添加新的Hook方法。

pluginmanager.add_hookspecs(module_or_class,prefix)

参数：

• pluginmanager(_pytest.config.PytestPluginManager) - pytest插件管理器

注意：这个Hook方法与hookwrapper=True冲突。

 

3.pytest_configure(config): 允许插件和conftest文件执行初始配置。

在解析了命令行选项后,为每个插件和初始conftest文件调用此Hook方法。

之后,在导入钩子时会调用其他conftest文件。

参数：

• config(_pytest.config.Config) - pytest配置对象

注意：这个Hook方法与hookwrapper=True冲突。

 

4.pytest_unconfigure(config): 在退出测试过程之前调用。

参数：

• config(_pytest.config.Config) - pytest配置对象

 

5.pytest_sessionstart(session): 在Session创建对象之后以及执行收集和进入运行测试循环之前调用。

参数：

• session(_pytest.main.Session) - pytest会话对象

 

6.pytest_sessionfinish(session,exitstatus): 在整个测试运行完成之后调用,在将退出状态返回到系统之前。

参数：

• session(_pytest.main.Session) - pytest会话对象
• exitstatus(int) - pytest将返回系统的状态

 

7.pytest_plugin_registered(plugin,manager):一个新的pytest插件已注册。

参数：

• 插件- 插件模块或实例
• manager(_pytest.config.PytestPluginManager) - pytest插件管理器

注意：这个Hook方法与hookwrapper=True冲突。

 

三、收集用例时的Hook方法

pytest调用以下Hook方法来来收集测试文件及目录

1.pytest_collection(session): 执行给定会话的收集协议。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止。

参数：

• session(_pytest.main.Session) - pytest会话对象

 

2.pytest_ignore_collect(path,config): 返回True以防止考虑此收集路径。在调用更具体的钩子之前,会查询所有文件和目录的钩子。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

参数：

• path(str) - 要分析的路径
• config(_pytest.config.Config) - pytest配置对象

 

3.pytest_collect_directory(path,parent): 在遍历目录以获取集合文件之前调用。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

参数：

• path(str) - 要分析的路径

pytest_collect_file(path,parent): 返回集合给定路径的节点或无。任何新节点都需要将指定parent的父节点作为父节点。

参数：

• path(str) - 要收集的路径

 

4.pytest_pycollect_makemodule(path,parent): 返回给定路径的Module收集器或None。将为每个匹配的测试模块路径调用此Hook方法。如果要为不匹配的文件创建测试模块作为测试模块,则需要使用pytest_collect_fileHook方法。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

要影响Python模块中的对象集合,可以使用以下Hook方法：

 

5.pytest_pycollect_makeitem(收藏家,name,obj): 返回模块中python对象的自定义项/收集器,或者无。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

 

6.pytest_generate_tests(metafunc): 生成(多个)参数化调用到测试函数。

 

7.pytest_make_parametrize_id(config,val,argname): 返回val@ pytest.mark.parametrize调用将使用的给定的用户友好字符串表示形式。如果钩子不知道,则返回Noneval。argname如果需要,参数名称可用。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

参数：

• config(_pytest.config.Config) - pytest配置对象
• val- 参数化值
• argname(str) - pytest生成的自动参数名称

收集完成后,你可以修改项目的顺序,删除或以其他方式修改测试项目：

 

8.pytest_collection_modifyitems(session,config,items): 在执行收集后调用,可以就地过滤或重新排序项目。

参数：

• session(_pytest.main.Session) - pytest会话对象
• config(_pytest.config.Config) - pytest配置对象
• items(List**_pytest.nodes.Item**]) - 项目对象列表

9.pytest_collection_finish(session): 在执行和修改集合后调用。

参数：

• session(_pytest.main.Session) - pytest会话对象

 

四、测试运行时的Hook方法

所有与runtest相关的钩子都会收到一个pytest.Item对象。

1.pytest_runtestloop(session): 执行运行测试循环(收集完成后)。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

参数：

• session(_pytest.main.Session) - pytest会话对象

2.pytest_runtest_protocol(item,nextitem): 为给定的测试项实现runtest_setup / call / teardown协议,包括捕获异常和调用报告Hook方法。

参数：

• item- 为其执行运行测试协议的测试项目。
• nextitem- 预定下一个测试项目(如果这是我朋友的结束,则为无)。这个论点被传递给了pytest_runtest_teardown()。

返回布尔值：如果不应调用其他钩子实现,则为True。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

 

3.pytest_runtest_logstart(nodeid,location): 发出运行单个测试项目的信号。

在调用pytest_runtest_setup()Hook方法之前会调用此Hook方法。

参数：

• nodeid(str) - 项目的完整ID
• location- 三倍(filename,linenum,testname)`

 

4.pytest_runtest_logfinish(nodeid,location): 发出运行单个测试项目的完成信号。

调用pytest_runtest_setup()Hook方法之后, 调用此Hook方法。

参数：

• nodeid(str) - 项目的完整ID
• location- (filename,linenum,testname)`三者的组合

 

5.pytest_runtest_setup(item): 以前称作pytest_runtest_call(item)。

6.pytest_runtest_call(item): 调用执行测试项。

7.pytest_runtest_teardown(item,nextitem): 在pytest_runtest_call之后调用。

参数：

• nextitem- 计划下一个测试项目(如果没有安排其他测试项目,则为None)。这个参数可以用来执行精确的拆卸,即调用足够的终结器,以便nextitem只需要调用setup-functions。

 

8.pytest_runtest_makereport(item,call): 返回_pytest.runner.TestReport。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

_pytest.runner也可能与其_pytest.pdb进行交互_pytest.capture以及其输入/输出捕获,以便在发生测试失败时立即进入交互式调试。

在_pytest.terminal具体报告使用报告Hook方法,打印有关测试运行的信息。

 

9.pytest_pyfunc_call(pyfuncitem): 调用底层测试函数。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

 

五、生成测试结果时的Hook方法

与会话报告相关的Hook方法

1.pytest_collectstart(collector): Collector开始收集。

2.pytest_make_collect_report(collector): 执行collector.collect()并返回CollectReport。

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

3.pytest_itemcollected(item): 我们刚收集了一个测试项目。

4.pytest_collectreport(report): Collector完成收集。

5.pytest_deselected(items): 要求通过关键字取消选择的测试项目。

6.pytest_report_header(config,startdir): 返回一个字符串或字符串列表,以显示为终端报告的标题信息。

参数：

• config(_pytest.config.Config) - pytest配置对象
• startdir- 带起始目录的py.path对象

注意：conftest.py由于pytest在启动期间发现插件的方式,此函数应仅在位于测试根目录的插件或文件中实现。

7.pytest_report_collectionfinish(config,startdir,items): 返回集合成功完成后要显示的字符串或字符串列表。

此字符串将显示在标准的“收集的X项目”消息之后。

参数：

• config(_pytest.config.Config) - pytest配置对象
• startdir- 带起始目录的py.path对象
• items- 将要执行的pytest项列表;此列表不应修改。

8.pytest_report_teststatus(report,config): 返回结果类别,简短和冗长的报告单词。

参数：

• config(_pytest.config.Config) - pytest配置对象

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

 

9.pytest_terminal_summary(terminalreporter,exitstatus,config): 在终端摘要报告中添加一个部分。

参数：

• terminalreporter(_pytest.terminal.TerminalReporter) - 内部终端报告对象
• exitstatus(int) - 将报告回操作系统的退出状态
• config(_pytest.config.Config) - pytest配置对象

 

10.pytest_fixture_setup(fixturedef,request): 执行Fixture方法设置执行。

返回：调用fixture函数的返回值

在第一个非空结果处停止,请参见: firstresult：在第一个非空结果处停止

注意：如果fixture函数返回None,则将根据firstresult选项。

 

11.pytest_fixture_post_finalizer(fixturedef,request): 在Fixture方法拆卸后调用,但在清除缓存之前,fixturedef.cached_result仍然可以访问Fixture方法结果缓存。

12.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方法：

13.pytest_runtest_logreport(report): 处理与执行测试的相应阶段有关的测试设置/调用/拆除报告。

 

断言相关Hook方法：

14.pytest_assertrepr_compare(config,op,left,right): 返回失败的断言表达式中的比较解释。

如果没有自定义说明,则返回None,否则返回字符串列表。该字符串将通过新行被加入,但任何换行符在字符串将被转义。请注意,除第一行外的所有行都将略微缩进,目的是将第一行作为摘要。

参数：

• config(_pytest.config.Config) - pytest配置对象

15.pytest_assertion_pass(item, lineno, orig, expl): 每当断言通过时,Hook就会调用。

在传递断言后使用此Hook方法进行一些处理。 原始断言信息在orig字符串中可用,而pytest内省断言信息在expl字符串中可用。

必须通过enable_assertion_pass_hook ini-file选项显式启用此Hook方法：

Copy

[pytest] enable_assertion_pass_hook=true

启用此选项时,需要清除项目目录和解释器库中的.pyc文件,因为断言需要重写。

参数：

• item(_pytest.nodes.Item) - 当前测试的pytest项目对象
• lineno(int) - 断言语句的行号
• orig(string) - 带有原始断言的字符串
• expl(string) - 带有断言解释的字符串

注意：这个Hook方法是实验性的,因此它的参数甚至钩子本身可能会在未来的任何pytest版本中被更改/删除而不会发出警告。

 

六、调试/交互Hook方法

有Hook方法可用于特殊报告或与异常交互

1.pytest_internalerror(excrepr,excinfo): 内部出错时调用。

2.pytest_keyboard_interrupt(excinfo): 键盘中断时调用。

3.pytest_exception_interact(节点,呼叫,报告): 在引发异常时调用,可以交互式处理。

只有在引发的异常不是内部异常, 如skip.Exception时才会调用此Hook方法。

4.pytest_enter_pdb(config,pdb): 调用pdb.set_trace()时,插件可以使用插件在python调试器进入交互模式之前采取特殊操作。

参数：

• config(_pytest.config.Config) - pytest配置对象
• pdb(pdb.Pdb) - Pdb实例