Pytest官方教程-22-API参考-Hooks

安装及入门
使用和调用方法
原有TestSuite使用方法
断言的编写和报告
Pytest fixtures：清晰模块化易扩展
使用Marks标记测试用例
Monkeypatching/对模块和环境进行Mock
使用tmp目录和文件
捕获stdout及stderr输出
捕获警告信息
模块及测试文件中集成doctest测试
skip及xfail: 处理不能成功的测试用例
Fixture方法及测试用例的参数化
缓存: 使用跨执行状态
unittest.TestCase支持
运行Nose用例
经典xUnit风格的setup/teardown
安装和使用插件
插件编写
编写钩子(hook)方法
运行日志
API参考
1. 方法(Functions)
2. 标记(Marks)
3. 钩子(Hooks)
4. 装置(Fixtures)
5. 对象(Objects)
6. 特殊变量(Special Variables)
7. 环境变量(Environment Variables)
8. 配置选项(Configuration Options)
优质集成实践
片状测试
Pytest导入机制及sys.path/PYTHONPATH
配置选项
示例及自定义技巧
Bash自动补全设置

API参考-Hooks

钩子(Hooks)
- 引导钩子
- 初始化Hook方法
- 测试运行Hook方法
- 收藏Hook方法
- 报告Hook方法
- 调试/交互Hook方法

钩子(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* [ [str](https://docs.python.org/3/library/stdtypes.html#str "（在Python v3.7中）") ]*） - 在命令行上传递的参数列表
解析器（_pytest.config.Parser） - 添加命令行选项
|

pytest_cmdline_preparse（config，*args *）[来源]

（不推荐）在选项解析之前修改命令行参数。
此钩子被认为已弃用，将在未来的pytest版本中删除。考虑pytest_load_initial_conftests()改用。
注意
不会为conftest.py文件调用此Hook方法，仅适用于setuptools插件。

| 参数： |

config（_pytest.config.Config） - pytest配置对象
args（list* [ [str](https://docs.python.org/3/library/stdtypes.html#str "（在Python v3.7中）") ]*） - 在命令行上传递的参数列表
|

pytest_cmdline_parse（pluginmanager，*args *）[来源]

返回初始化的配置对象，解析指定的args。
首先停止非结果，请参见firstresult：首先停止非结果
注意
plugins当使用pytest.main执行进程内测试运行时，只会为传递给arg的插件类调用此挂接。

| 参数： |

pluginmanager（_pytest.config.PytestPluginManager） - pytest插件管理器
args（list* [ [str](https://docs.python.org/3/library/stdtypes.html#str "（在Python v3.7中）") ]*） - 在命令行上传递的参数列表
|

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 属性在许多内部对象上传递，或者可以作为pytestconfig夹具检索。
注意
这个钩子与之不相容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（_pytest.main.Session） - pytest会话对象 |

pytest_sessionfinish（session，*exitstatus *）[来源]

在整个测试运行完成之后调用，在将退出状态返回到系统之前。

| 参数： |

session（_pytest.main.Session） - pytest会话对象
exitstatus（int） - pytest将返回系统的状态
|

pytest_plugin_registered（插件，经理）[来源]

一个新的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 *）[来源]

发出运行单个测试项目的信号。
之前会调用此Hook方法pytest_runtest_setup()，pytest_runtest_call()并pytest_runtest_teardown()Hook方法。

| 参数： |

nodeid（str） - 项目的完整ID
位置 - 三倍(filename, linenum, testname)
|

pytest_runtest_logfinish（nodeid，*location *）[来源]

发出运行单个测试项目的完整信号。
这个钩子将在之后调用pytest_runtest_setup()，pytest_runtest_call()并pytest_runtest_teardown()Hook方法。

| 参数： |

nodeid（str） - 项目的完整ID
位置 - 三倍(filename, linenum, testname)

pytest_runtest_setup（项目）[来源]

以前叫过pytest_runtest_call(item)。

pytest_runtest_call（项目）[来源]

叫做执行测试item。

pytest_runtest_teardown（item，*nextitem *）[来源]

叫之后pytest_runtest_call。

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

pytest_runtest_makereport（项目，电话）[来源]

返回_pytest.runner.TestReport给定pytest.Item和的对象_pytest.runner.CallInfo。
首先停止非结果，请参见firstresult：首先停止非结果

为了更深入地理解，你可以查看这些钩子的默认实现，_pytest.runner也可能与其_pytest.pdb进行交互_pytest.capture以及其输入/输出捕获，以便在发生测试失败时立即进入交互式调试。
在_pytest.terminal具体报告使用报告Hook方法，打印有关测试运行的信息。

pytest_pyfunc_call（*pyfuncitem *）[来源]

调用底层测试功能。
首先停止非结果，请参见firstresult：首先停止非结果

集合Hook方法

pytest 调用以下钩子来收集文件和目录：

pytest_collection（会话）[来源]

执行给定会话的收集协议。
首先停止非结果，请参见firstresult：首先停止非结果。

| 参数： | session（_pytest.main.Session） - pytest会话对象 |

pytest_ignore_collect（路径，配置）[来源]

返回True以防止考虑此收集路径。在调用更具体的钩子之前，会查询所有文件和目录的钩子。
首先停止非结果，请参见firstresult：首先停止非结果

| 参数： |

path（str） - 要分析的路径
config（_pytest.config.Config） - pytest配置对象
|

pytest_collect_directory（路径，父母）[来源]

在遍历目录以获取集合文件之前调用。
首先停止非结果，请参见firstresult：首先停止非结果

| 参数： | path（str） - 要分析的路径 |

pytest_collect_file（路径，父母）[来源]

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

| 参数： | path（str） - 要收集的路径 |

pytest_pycollect_makemodule（路径，父母）[来源]

返回给定路径的Module收集器或None。将为每个匹配的测试模块路径调用此Hook方法。如果要为不匹配的文件创建测试模块作为测试模块，则需要使用pytest_collect_fileHook方法。
首先停止非结果，请参见firstresult：首先停止非结果

要影响Python模块中的对象集合，可以使用以下钩子：

pytest_pycollect_makeitem（收藏家，名字，*obj *）[来源]

返回模块中python对象的自定义项/收集器，或者无。
首先停止非结果，请参见firstresult：首先停止非结果

pytest_generate_tests（*metafunc *）[来源]

生成（多个）参数化调用到测试函数。

pytest_make_parametrize_id（config，val，*argname *）[来源]

返回val@ pytest.mark.parametrize调用将使用的给定的用户友好字符串表示形式。如果钩子不知道，则返回None val。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](https://docs.pytest.org/en/latest/reference.html#_pytest.nodes.Item "_pytest.nodes.Item") ]） - 项目对象列表
|

pytest_collection_finish（会话）[来源]

在执行和修改集合后调用。

| 参数： | session（_pytest.main.Session） - pytest会话对象 |

报告Hook方法

与会话相关的报告Hook方法：

pytest_collectstart（收藏家）[来源]

Collector开始收集。

pytest_make_collect_report（收藏家）[来源]

执行collector.collect()并返回CollectReport。
首先停止非结果，请参见firstresult：首先停止非结果

pytest_itemcollected（项目）[来源]

我们刚收集了一个测试项目。

pytest_collectreport（报告）[来源]

Collector完成收集。

pytest_deselected（项目）[来源]

要求通过关键字取消选择的测试项目。

pytest_report_header（config，*startdir *）[来源]

返回一个字符串或字符串列表，以显示为终端报告的标题信息。

| 参数： |

config（_pytest.config.Config） - pytest配置对象
startdir - 带起始目录的py.path对象
|
注意
conftest.py 由于pytest 在启动期间发现插件的方式，此函数应仅在位于测试根目录的插件或文件中实现。

pytest_report_collectionfinish（config，startdir，*items *）[来源]

版本3.2中的新功能。
返回集合成功完成后要显示的字符串或字符串列表。
此字符串将显示在标准的“收集的X项目”消息之后。

| 参数： |

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函数的返回值 |
首先停止非结果，请参见firstresult：首先停止非结果
注意
如果fixture函数返回None，则将根据firstresult的行为继续调用此钩子函数的其他实现：首先停止非None结果选项。

pytest_fixture_post_finalizer（fixturedef，*request *）[来源]

在夹具拆卸后调用，但在清除缓存之前，fixturedef.cached_result仍然可以访问夹具结果缓存。

pytest_warning_captured（warning_message，when，*item *）[来源]

处理内部pytest warnings插件捕获的警告。

| 参数： |

warning_message（warnings.WarningMessage） - 捕获的警告。这与生成的对象相同warnings.catch_warnings()，并且包含与参数相同的属性warnings.showwarning()。
什么时候（str） -
指示何时捕获警告。可能的值：
- "config"：在pytest配置/初始化阶段。
- "collect"：在测试收集期间。
- "runtest"：在测试执行期间。
item（pytest.Item | None） -
DEPRECATED：此参数与以后版本不兼容pytest-xdist，并且将始终None在以后的版本中接收。
正在执行的项目，如果when是"runtest"，否则None。
|

这是报告测试执行的中心钩子：

pytest_runtest_logreport（报告）[来源]

处理与执行测试的相应阶段有关的测试设置/调用/拆除报告。

你还可以使用此Hook方法来自定义某些类型的断言表示：

pytest_assertrepr_compare（config，op，left，*right *）[来源]

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

| 参数： | config（_pytest.config.Config） - pytest配置对象 |

调试/交互Hook方法

很少有钩子可用于特殊报告或与异常交互：

pytest_internalerror（excrepr，*excinfo *）[来源]

要求内部错误。

pytest_keyboard_interrupt（*excinfo *）[来源]

要求键盘中断。

pytest_exception_interact（节点，呼叫，报告）[来源]

在引发异常时调用，可以交互式处理。
只有在引发的异常不是内部异常时才会调用此钩子skip.Exception。

pytest_enter_pdb（config，*pdb *）[来源]

调用pdb.set_trace（）时，插件可以使用插件在python调试器进入交互模式之前采取特殊操作。

| 参数： |

config（_pytest.config.Config） - pytest配置对象
pdb（pdb.Pdb） - Pdb实例