Pytest权威教程21-API参考-05-对象(Objects)

目录

• 对象(Objects)
  • CallInfo
  • Class
  • Collector
  • Config
  • ExceptionInfo
  • FixtureDef
  • FSCollector
  • Function
  • Item
  • MarkDecorator
  • MarkGenerator
  • Mark
  • Metafunc
  • Module
  • Node
  • Parser
  • PluginManager
  • PytestPluginManager
  • Session
  • TestReport
  • _Result

返回: Pytest权威教程

对象(Objects)

Objects的完整使用可参考: Fixturs及Hooks方法。

CallInfo

class CallInfo: 结果/异常信息是一个函数调用。

Class

class Class: 基类：_pytest.python.PyCollector

收集器的测试用例。

collect(): 返回此集合节点的子项(项和收集器)列表。

Collector

class Collector: 基类_pytest.nodes.Node

收集器实例通过collect()创建子项,从而迭代地构建树。

exception CollectError: 基类Exception

收集期间出错,包含自定义消息。

collect(): 返回此集合节点的子项(项和收集器)列表。

repr_failure(excinfo): 表示集合失败。

Config

class Config: 访问配置值,pluginmanager和插件钩子。
option=None: 访问命令行选项作为属性。(已弃用),请getoption()改用

pluginmanager=None: 一个pluginmanager实例

add_cleanup(func): 添加一个在配置对象不使用时调用的函数(通常与pytest_unconfigure一致)。

classmethod fromdictargs(option_dict,args): 构造函数可用于子进程。

addinivalue_line(name,line): 在ini-file选项中添加一行。该选项必须已声明但可能尚未设置,在这种情况下,该行将成为其值中的第一行。

getini(name): 从ini文件返回配置值。如果未通过先前parser.addini调用(通常来自插件)注册指定的名称,则会引发ValueError。

getoption(name, default=, skip=False): 返回命令行选项值。

参数：

• name- 选项的名称。你也可以指定文字--OPT选项而不是“dest”选项名称。
• default- 如果不存在该名称的选项,则为默认值。
• skip- 如果选项不存在或具有None值,则为true raise pytest.skip。

getvalue(name,path = None): (不推荐使用,请使用getoption())

getvalueorskip(name,path = None): (不推荐使用,使用getoption(skip = True))

ExceptionInfo

class ExceptionInfo(excinfo,striptext ='',traceback = None): 包装sys.exc_info()对象并提供导航回溯的帮助。

classmethod from_current(exprinfo = None)
返回与当前回溯匹配的ExceptionInfo

警告
实验性API

参数： exprinfo- 一个文本字符串,帮助确定我们是否应该AssertionError从输出中剥离,默认为异常消息/__str__()

classmethod`for_later()
返回一个未填充的ExceptionInfo

type: 异常类

value: 异常值

tb: 异常原始追溯

typename: 异常的类型名称

traceback: 追溯信息

exconly(tryshort = False): 将异常作为字符串返回

当'tryshort'解析为True,异常是_pytest._code._AssertionError时,只返回异常表示的实际异常部分(因此'AssertionError：'从头开始删除)

errisinstance(exc): 如果异常是exc的实例,则返回True

getrepr(showlocals = False,style ='long',abspath = False,tbfilter = True,funcargs = False,truncate_locals = True,chain = True): 返回str()表示此异常信息。

参数：

• showlocals(bool) - 显示每个回溯条目的本地人。忽略如果style=="native"。
• style(str) - long short no native traceback style
• abspath(bool) - 如果路径应更改为绝对路径或保持不变。
• tbfilter(bool) - 隐藏包含局部变量的条目__tracebackhide__==True。忽略如果style=="native"。
• funcargs(bool) - 为每个回溯条目显示Fixture方法(用于传统目的的“funcargs”)。
• truncate_locals(bool) - 使用showlocals==True,确保本地可以安全地表示为字符串。
• chain(bool) - 如果显示Python 3中的链接异常。

在版本3.9中更改：添加了chain参数。

match(regexp): 将正则表达式'regexp'与异常的字符串表示形式匹配。如果匹配则返回True(这样就可以写'assert excinfo.match()')。如果不匹配则引发AssertionError。

FixtureDef

class FixtureDef: 基类object

工厂定义的容器。

FSCollector

class FSCollector: 基类_pytest.nodes.Collector

Function

class Function: 基类_pytest.python.FunctionMixin,_pytest.nodes.Item,_pytest.compat.FuncargnamesCompatAttr
函数项负责设置和执行Python测试函数。
originalname=None: 原始函数名称,没有任何装饰(例如参数"[...]"`化为函数名称添加后缀)。
3.0版中的新函数。

function: 底层python'函数'对象

runtest(): 执行基础测试函数。

setup(): 执行此测试函数的设置。

Item

class Item: 基类_pytest.nodes.Node
一个基本的测试调用项。请注意,对于单个函数,可能存在多个测试调用项。

user_properties=None: user属性是一个元组列表(名称,值),用于保存此测试的用户定义属性。

add_report_section(when,key,content): 添加一个新的报表部分,类似于内部完成添加stdout和stderr捕获的输出：

item.add_report_section("call","stdout","report section contents")

参数：

• when(STR) -一个可能捕获的状态,"setup","call","teardown"。
• key(str) - 部分名称,可以随意定制。Pytest使用"stdout"和"stderr"内部。
• content(str) - 作为字符串的完整内容。

MarkDecorator

class MarkDecorator(mark): 测试函数和测试类的装饰器。应用时,它将创建MarkInfo可以通过钩子作为项目关键字检索的对象。MarkDecorator实例通常是这样创建的：

mark1 = pytest.mark.NAME              # simple MarkDecorator
mark2 = pytest.mark.NAME(name1=value) # parametrized MarkDecorator

然后可以作为装饰器应用于测试函数：

@mark2
def test_function():
    pass

调用MarkDecorator实例时,它会执行以下操作：

1. 如果使用单个类作为其唯一的位置参数调用而没有其他关键字参数,则它会将自身附加到类,以便自动应用于该类中的所有测试用例。
2. 如果使用单个函数作为唯一的位置参数调用而没有其他关键字参数,则会将MarkInfo对象附加到函数,其中包含已存储在MarkDecorator内部的所有参数。
3. 当在任何其他情况下调用时,它执行“假构造”调用,即它返回一个新的MarkDecorator实例,其原始MarkDecorator的内容使用传递给此调用的参数进行更新。

注意：上述规则阻止MarkDecorator对象仅存储单个函数或类引用作为其位置参数,而不包含其他关键字或位置参数。

name: mark.name的别名

args: mark.args的别名

kwargs: mark.kwargs的别名

with_args(** args,** kwargs*): 返回添加了额外参数的MarkDecorator

与调用不同,即使唯一参数是可调用/类,也可以使用它

返回：MarkDecorator

MarkGenerator

class MarkGenerator: MarkDecorator对象的工厂- 作为pytest.mark单例实例公开。例如:

import pytest
@pytest.mark.slowtest
def test_function():
   pass

将在MarkInfo对象上设置一个“最慢”的test_function对象。

Mark

class Mark (name：str,args,kwargs)

name=None: 商标名称

args=None: 标记装饰器的位置参数

kwargs=None: 标记装饰器的关键字参数

combined_with(other)

参数：

• other(mark) - 与之结合的商标: 返回类型： Mark标记

通过附加args和合并映射来组合

Metafunc

class Metafunc(definition,fixtureinfo,config,cls = None,module = None): Metafunc对象被传递给pytest_generate_tests钩子。它们有助于检查测试函数并根据测试配置或在定义测试函数的类或模块中指定的值生成测试。

config=None: 访问_pytest.config.Config测试Session的对象

module=None: 定义测试函数的模块对象。

function=None: 底层python测试函数

fixturenames=None: 测试函数所需的Fixture方法名称集

cls=None: 在或中定义测试函数的类对象None。

parametrize(argnames,argvalues,indirect = False,ids = None,scope = None): 使用给定argnames的argvalues列表向基础测试函数添加新调用。在收集阶段执行参数化。如果你需要设置昂贵的资源,请参阅设置间接,以便在测试设置时进行。

参数：

• argnames- 以逗号分隔的字符串,表示一个或多个参数名称,或参数字符串的列表/元组。
• argvalues-argvalues列表确定使用不同参数值调用测试的频率。如果只指定了一个argname,则argvalues是值列表。如果指定了N个argnames,则argvalues必须是N元组的列表,其中每个tuple-element为其各自的argname指定一个值。
• indirect- argnames或boolean的列表。参数列表名称(argnames的子集)。如果为True,则列表包含argnames中的所有名称。对应于此列表中的argname的每个argvalue将作为request.param传递到其各自的argname fixture函数,以便它可以在测试的设置阶段而不是在收集时执行更昂贵的设置。
• ids- 字符串ID列表或可调用的列表。如果字符串,则每个字符串对应于argvalues,以便它们是测试ID的一部分。如果将None作为特定测试的id给出,则将使用该参数的自动生成的id。如果是可调用的,它应该采用一个参数(单个argvalue)并返回一个字符串或返回None。如果为None,将使用该参数的自动生成的id。如果没有提供id,它们将自动从argvalues生成。
• 范围- 如果指定,则表示参数的范围。范围用于按参数实例对测试进行分组。它还将覆盖任何fixture函数定义的范围,允许使用测试上下文或配置设置动态范围。

Module

class Module: 基类_pytest.nodes.File,_pytest.python.PyCollector
测试类和函数的收集器。

collect(): 返回此集合节点的子项(项和收集器)列表。

Node

class Node: Collector的基类和测试集合树的Item。收集器子类有子节点,Items是终端节点。

name=None: 父节点范围内的唯一名称

parent=None: 父收集器节点。

config=None: pytest配置对象

session=None: 此节点所属的Session

fspath=None: 收集此节点的文件系统路径(可以是None)

keywords=None: 从所有范围收集的关键字/标记

own_markers=None: 属于此节点的标记对象

extra_keyword_matches=None: 允许添加额外的关键字以用于匹配

ihook: 用于调用pytest钩子的fspath敏感钩子代理

warn(warning): 发出此项目的警告。

除非明确禁止,否则将在测试Session后显示警告

参数：

• 警告(警告) - 要发出的警告实例。必须是PytestWarning的子类。

抛出: ValueError- 如果warning实例不是PytestWarning的子类。

使用方法示例如:

node.warn(PytestWarning("some message"))

nodeid: a :: - 表示其集合树地址的分隔字符串。

listchain(): 从收集树的根开始返回所有父收集器的列表。

add_marker(marker,append = True): 动态地将标记对象添加到节点。

参数：

• marker(str或pytest.mark.*对象) -append=True是否附加标记,如果False插入位置0。

iter_markers(name=None)

参数：

• name- 如果给定,则按name属性过滤结果
  迭代节点的所有标记

for ... in iter_markers_with_node(name = None)

参数：

• name- 如果给定,则按name属性过滤结果
  迭代节点的所有标记返回元组序列(节点,标记)

get_closest_marker(name,default=None): 返回与名称匹配的第一个标记,从最近(例如函数)到更远级别(例如模块级别)。

参数：

• default- 找不到标记的回退返回值
• name- 要过滤的名称

listextrakeywords(): 在self和任何父母中返回一组所有额外的关键字。

addfinalizer(fin): 在最终确定此节点时注册要调用的函数。

只有在此节点在设置链中处于活动状态时才能调用此方法,例如在self.setup()期间。

getparent(cls): 获取下一个父节点(包括ownelf),它是给定类的一个实例

Parser

class Parser: 解析命令行参数和ini文件值。

变量： extra_info- 泛型参数的字典 - >在处理命令行参数时出错的情况下显示的值。

getgroup(name,description ='',after = None): 获取(或创建)命名选项组。

• name: 选项组的名称。
• description： -help输出的长描述。
• after: 其他组的名称,用于排序-help输出。
  返回的组对象具有addoption与签名相同的方法,parser.addoption但将在输出中的相应组中显示。pytest.--help

addoption(** opts,** attrs*): 注册命令行选项。

• opts: 选项名称,可以是短期或长期期权。
• attrs： 相同的属性,其中add_option()所述的函数argparse库接受。

在命令行解析选项在pytest配置对象上可用之后config.option.NAME,NAME通常通过传递dest属性来设置,例如。addoption("--long",dest="NAME",...)

parse_known_args(args,namespace = None): 此时解析并返回具有已知参数的命名空间对象。

parse_known_and_unknown_args(args,namespace = None): 解析并返回具有已知参数的名称空间对象,此时其余参数未知。

addini(name,help,type = None,default = None): 注册ini文件选项。

名称： ini-variable的名称

类型： 该变量的类型,可以是pathlist,args,linelist或bool。

默认： 默认值,如果不存在ini-file选项但是被查询。
可以通过调用来检索ini变量的值config.getini(name)。

PluginManager

class PluginManager
Core Pluginmanager类,用于管理插件对象的注册和1：N钩子调用。
你可以通过致电注册新的钩子add_hookspec(module_or_class)。你可以通过调用注册插件对象(包含钩子)register(plugin)。Pluginmanager初始化为在注册的插件对象的dict名称中搜索的前缀。
出于调试目的,你可以调用enable_tracing()哪个随后将调试信息发送到跟踪帮助程序。

register(plugin,name=None): 如果名称被阻止注册,请注册插件并返回其规范名称或无。如果插件已注册,则引发ValueError。

unregister(plugin = None,name = None): 从内部数据结构取消注册插件对象及其所有包含的钩子实现。

set_blocked(name): 阻止给定名称的注册,如果已经注册,则注销。

is_blocked(name): 如果名称博客注册该名称的插件,则返回True。

add_hookspecs(module_or_class): 添加给定module_or_class中定义的新钩子规范。如果相应地修饰了函数,则会识别它们。

get_plugins(): 返回已注册的插件集。

is_registered(plugin): 如果插件已经注册,则返回True。

get_canonical_name(plugin): 返回插件对象的规范名称。请注意,插件可以使用由register(plugin,name)的调用者指定的其他名称注册。要获取已注册插件的名称,请使用get_name(plugin)。

get_plugin(name): 返回给定名称的插件或None。

has_plugin(name): 如果注册了具有给定名称的插件,则返回True。

get_name(plugin): 注册插件的返回名称,如果未注册,则返回None。

check_pending(): 验证所有未针对钩子规范验证的钩子是可选的,否则引发PluginValidationError

load_setuptools_entrypoints(group,name=None): 从查询指定的setuptools加载模块group。

参数：

• group(str) - 加载插件的入口点组
• name(str) - 如果给定,只加载给定的插件name。

返回类型： int

返回：通过此调用返回加载的插件数。

list_plugin_distinfo(): 返回所有setuptools注册插件的distinguishedfo / plugin元组列表。

list_name_plugin(): 返回名称/插件对的列表。

get_hookcallers(plugin): 获取指定插件的所有钩子调用者。

add_hookcall_monitoring(before,after): 在所有钩子的跟踪函数之前/之后添加并返回一个撤销函数,当被调用时,将删除添加的跟踪器。

before(hook_name,hook_impls,kwargs)将在所有钩子调用之前调用并接收一个hookcaller实例,一个HookImpl实例列表和一个钩子调用的关键字参数。

after(outcome,hook_name,hook_impls,kwargs)接收相同的参数,before但也接收一个`_Result``表示整个钩子调用的结果的对象。

enable_tracing(): 启用对钩子调用的跟踪并返回撤销函数。

subset_hook_caller(name,remove_plugins): 为命名方法返回一个新的_HookCaller实例,该方法管理除remove_plugins之外的所有已注册插件的调用。

PytestPluginManager

class PytestPluginManager: 基类pluggy.manager.PluginManager

覆盖pluggy.PluginManager以添加特定于pytest的函数：

• 从命令行加载插件,加载插件中的PYTEST_PLUGINSenv变量和pytest_plugins全局变量;
• conftest.py在启动期间装载;
  `addhooks(module_or_class)

自2.8版以来已弃用。
请pluggy.PluginManager.add_hookspecs改用。

parse_hookimpl_opts(plugin,name)

parse_hookspec_opts(module_or_class,name)

`register(plugin,name=None): 如果名称被阻止注册,请注册插件并返回其规范名称或无。如果插件已注册,则引发ValueError。

getplugin(name)

hasplugin(name)
如果注册了具有给定名称的插件,则返回True。

pytest_configure(config)

consider_preparse(args)

consider_pluginarg(arg)

consider_conftest(conftestmodule)

consider_env()

consider_module(mod)

import_plugin(modname,consideration_entry_points = False): 用插件导入插件modname。如果consider_entry_points为True,则还会将入口点名称视为查找插件。

Session

class Session: 基类_pytest.nodes.FSCollector
exception Interrupted: 基类KeyboardInterrupt
发出中断的测试运行信号。

exception Failed: 基类Exception
在测试运行失败时发出停止信号。

for ... in collect(): 返回此集合节点的子项(项和收集器)列表。

TestReport

class TestReport: 基本测试报告对象(如果失败,也用于设置和拆除调用)。

nodeid=None: 规范化的集合节点ID

location=None: a(filesystempath,lineno,domaininfo)元组指示测试项的实际位置 - 它可能与收集的测试项不同,例如,如果方法是从不同的模块继承的。

keywords=None: name - > value字典,包含与测试调用关联的所有关键字和标记。

outcome=None: 测试结果,总是“通过”,“失败”,“跳过”之一。

longrepr=None: 无或失败表示。

when=None: 'setup','call','teardown'之一表示测试阶段。

user_properties=None: user属性是一个元组列表(名称,值),用于保存用户定义的测试属性

sections=None: 需要编组的额外信息对的列表。通过pytest用于添加从捕获的文本和,但是可以通过其它的插件可用于任意信息添加到报表。(str,str)stdoutstderr`

duration=None: 只运行测试所花费的时间

classmethod from_item_and_call(item,call)使用标准项和调用信息创建和填充TestReport的工厂方法。

caplog: 如果启用了日志捕获,则返回捕获的日志行
版本3.5中的新函数。

capstderr: 如果启用了捕获,则从stderr返回捕获的文本
3.0版中的新函数。

capstdout: 如果启用了捕获,则从stdout返回捕获的文本
3.0版中的新函数。

count_towards_summary: 如果此报告应计入测试Session结束时显示的总计,则返回True：“1通过,1失败等”。
试验性功能

注意：此函数被认为是实验性的,因此请注意即使在修补程序版本中它也会发生变化。

head_line: 返回此报告的longrepr输出显示的头行,更常见的是在故障期间的回溯表示期间：
试验性功能

________ Test.foo ________

在上面的示例中,head_line是“Test.foo”。

注意：此函数被认为是实验性的,因此请注意即使在修补程序版本中它也会发生变化。

longreprtext
只读属性,返回完整的字符串表示形式longrepr。
3.0版中的新函数。

_Result

class _Result(result,excinfo)
result: 获取此钩子调用的结果(DEPRECATED支持get_result())。

force_result(result): 强制结果result。

如果钩子被标记为firstresult单个值,则应设置否则设置(修改)结果列表。调用期间发现的任何异常都将被删除。

get_result(): 获取此钩子调用的结果。

如果钩子被标记为firstresult只有一个值,则返回结果列表。