• 1. @pytest.mark.parametrize标记
  • 1.1. empty_parameter_set_mark选项
  • 1.2. 多个标记组合
  • 1.3. 标记测试模块
• 2. pytest_generate_tests钩子方法

在实际工作中，测试用例可能需要支持多种场景，我们可以把和场景强相关的部分抽象成参数，通过对参数的赋值来驱动用例的执行；

参数化的行为表现在不同的层级上：

• fixture的参数化：参考 4、fixtures：明确的、模块化的和可扩展的 – fixture的参数化；

• 测试用例的参数化：使用@pytest.mark.parametrize可以在测试用例、测试类甚至测试模块中标记多个参数或fixture的组合；

另外，我们也可以通过pytest_generate_tests这个钩子方法自定义参数化的方案；

1. @pytest.mark.parametrize标记

@pytest.mark.parametrize的根本作用是在收集测试用例的过程中，通过对指定参数的赋值来新增被标记对象的调用（执行）；

首先，我们来看一下它在源码中的定义：

# _pytest/python.pydef parametrize(self, argnames, argvalues, indirect=False, ids=None, scope=None):

着重分析一下各个参数：

• argnames：一个用逗号分隔的字符串，或者一个列表/元组，表明指定的参数名；

  对于argnames，实际上我们是有一些限制的：

  • 只能是被标记对象入参的子集：

    @pytest.mark.parametrize('input, expected', [(1, 2)])
    def test_sample(input):assert input + 1 == 1
    

    test_sample中并没有声明expected参数，如果我们在标记中强行声明，会得到如下错误：

    In test_sample: function uses no argument 'expected'
    

  • 不能是被标记对象入参中，定义了默认值的参数：

    @pytest.mark.parametrize('input, expected', [(1, 2)])
    def test_sample(input, expected=2):assert input + 1 == expected
    

    虽然test_sample声明了expected参数，但同时也为其赋予了一个默认值，如果我们在标记中强行声明，会得到如下错误：

    In test_sample: function already takes an argument 'expected' with a default value
    

  • 会覆盖同名的fixture：

    @pytest.fixture()
    def expected():return 1
    

    @pytest.mark.parametrize('input, expected', [(1, 2)])
    def test_sample(input, expected):assert input + 1 == expected
    ````test_sample`标记中的`expected（2）`覆盖了同名的`fixture expected（1）`，所以这条用例是可以测试成功的；这里可以参考：[4、fixtures：明确的、模块化的和可扩展的 -- 在用例参数中覆写`fixture`](4、fixtures：明确的、模块化的和可扩展的.md#163-在用例参数中覆写fixture)
    

• argvalues：一个可迭代对象，表明对argnames参数的赋值，具体有以下几种情况：

  • 如果argnames包含多个参数，那么argvalues的迭代返回元素必须是可度量的（即支持len()方法），并且长度和argnames声明参数的个数相等，所以它可以是元组/列表/集合等，表明所有入参的实参：

    @pytest.mark.parametrize('input, expected', [(1, 2), [2, 3], set([3, 4])])
    def test_sample(input, expected):assert input + 1 == expected
    

    注意：考虑到集合的去重特性，我们并不建议使用它；

  • 如果argnames只包含一个参数，那么argvalues的迭代返回元素可以是具体的值：

    @pytest.mark.parametrize('input', [1, 2, 3])
    def test_sample(input):assert input + 1
    

  • 如果你也注意到我们之前提到，argvalues是一个可迭代对象，那么我们就可以实现更复杂的场景；例如：从excel文件中读取实参：

    def read_excel():# 从数据库或者 excel 文件中读取设备的信息，这里简化为一个列表for dev in ['dev1', 'dev2', 'dev3']:yield dev
    

    @pytest.mark.parametrize('dev', read_excel())
    def test_sample(dev):assert dev
    ```> 实现这个场景有多种方法，你也可以直接在一个`fixture`中去加载`excel`中的数据，但是它们在测试报告中的表现会有所区别；
    

    • 或许你还记得，在上一篇教程（10、skip和xfail标记 – 结合pytest.param方法）中，我们使用pytest.param为argvalues参数赋值：

      @pytest.mark.parametrize(('n', 'expected'),[(2, 1),pytest.param(2, 1, marks=pytest.mark.xfail(), id='XPASS')])
      def test_params(n, expected):assert 2 / n == expected
      

      现在我们来具体分析一下这个行为：

      无论argvalues中传递的是可度量对象（列表、元组等）还是具体的值，在源码中我们都会将其封装成一个ParameterSet对象，它是一个具名元组（namedtuple），包含values, marks, id三个元素：

      >>> from _pytest.mark.structures import ParameterSet as PS
      >>> PS._make([(1, 2), [], None])
      ParameterSet(values=(1, 2), marks=[], id=None)
      

      如果直接传递一个ParameterSet对象会发生什么呢？我们去源码里找答案：

      # _pytest/mark/structures.pyclass ParameterSet(namedtuple("ParameterSet", "values, marks, id")):...@classmethoddef extract_from(cls, parameterset, force_tuple=False):""":param parameterset:a legacy style parameterset that may or may not be a tuple,and may or may not be wrapped into a mess of mark objects:param force_tuple:enforce tuple wrapping so single argument tuple valuesdon't get decomposed and break tests"""if isinstance(parameterset, cls):return parametersetif force_tuple:return cls.param(parameterset)else:return cls(parameterset, marks=[], id=None)
      

      可以看到如果直接传递一个ParameterSet对象，那么返回的就是它本身（return parameterset），所以下面例子中的两种写法是等价的：

      # src/chapter-11/test_sample.pyimport pytestfrom _pytest.mark.structures import ParameterSet@pytest.mark.parametrize('input, expected',[(1, 2), ParameterSet(values=(1, 2), marks=[], id=None)])
      def test_sample(input, expected):assert input + 1 == expected
      

      到这里，或许你已经猜到了，pytest.param的作用就是封装一个ParameterSet对象；那么我们去源码里求证一下吧！

      # _pytest/mark/__init__.pydef param(*values, **kw):"""Specify a parameter in `pytest.mark.parametrize`_ calls or:ref:`parametrized fixtures <fixture-parametrize-marks>`... code-block:: python@pytest.mark.parametrize("test_input,expected", [("3+5", 8),pytest.param("6*9", 42, marks=pytest.mark.xfail),])def test_eval(test_input, expected):assert eval(test_input) == expected:param values: variable args of the values of the parameter set, in order.:keyword marks: a single mark or a list of marks to be applied to this parameter set.:keyword str id: the id to attribute to this parameter set."""return ParameterSet.param(*values, **kw)
      

      正如我们所料，现在你应该更明白怎么给argvalues传参了吧；

• indirect：argnames的子集或者一个布尔值；将指定参数的实参通过request.param重定向到和参数同名的fixture中，以此满足更复杂的场景；

  具体使用方法可以参考以下示例：

  # src/chapter-11/test_indirect.pyimport pytest
  

  @pytest.fixture()
  def max(request):
  return request.param - 1

  @pytest.fixture()
  def min(request):
  return request.param + 1

  默认 indirect 为 False

  @pytest.mark.parametrize(‘min, max’, [(1, 2), (3, 4)])
  def test_indirect(min, max):
  assert min <= max

  min max 对应的实参重定向到同名的 fixture 中

  @pytest.mark.parametrize(‘min, max’, [(1, 2), (3, 4)], indirect=True)
  def test_indirect_indirect(min, max):
  assert min >= max

  只将 max 对应的实参重定向到 fixture 中

  @pytest.mark.parametrize(‘min, max’, [(1, 2), (3, 4)], indirect=[‘max’])
  def test_indirect_part_indirect(min, max):
  assert min == max

• ids：一个可执行对象，用于生成测试ID，或者一个列表/元组，指明所有新增用例的测试ID；

  • 如果使用列表/元组直接指明测试ID，那么它的长度要等于argvalues的长度：

    @pytest.mark.parametrize('input, expected', [(1, 2), (3, 4)],ids=['first', 'second'])
    def test_ids_with_ids(input, expected):pass
    

    搜集到的测试ID如下：

    collected 2 items
    <Module test_ids.py><Function test_ids_with_ids[first]><Function test_ids_with_ids[second]>
    

  • 如果指定了相同的测试ID，pytest会在后面自动添加索引：

    @pytest.mark.parametrize('input, expected', [(1, 2), (3, 4)],ids=['num', 'num'])
    def test_ids_with_ids(input, expected):pass
    

    搜集到的测试ID如下：

    collected 2 items
    <Module test_ids.py><Function test_ids_with_ids[num0]><Function test_ids_with_ids[num1]>
    

  • 如果在指定的测试ID中使用了非ASCII的值，默认显示的是字节序列：

    @pytest.mark.parametrize('input, expected', [(1, 2), (3, 4)],ids=['num', '中文'])
    def test_ids_with_ids(input, expected):pass
    

    搜集到的测试ID如下：

    collected 2 items
    <Module test_ids.py><Function test_ids_with_ids[num]><Function test_ids_with_ids[\u4e2d\u6587]>
    

    可以看到我们期望显示中文，实际上显示的是\u4e2d\u6587；

    如果我们想要得到期望的显示，该怎么办呢？去源码里找答案：

    # _pytest/python.pydef _ascii_escaped_by_config(val, config):if config is None:escape_option = Falseelse:escape_option = config.getini("disable_test_id_escaping_and_forfeit_all_rights_to_community_support")return val if escape_option else ascii_escaped(val)
    

    我们可以通过在pytest.ini中使能disable_test_id_escaping_and_forfeit_all_rights_to_community_support选项来避免这种情况：

    [pytest]
    disable_test_id_escaping_and_forfeit_all_rights_to_community_support = True
    

    再次搜集到的测试ID如下：

    <Module test_ids.py><Function test_ids_with_ids[num]><Function test_ids_with_ids[中文]>
    

  • 如果通过一个可执行对象生成测试ID：

    def idfn(val):# 将每个 val 都加 1return val + 1
    

    @pytest.mark.parametrize('input, expected', [(1, 2), (3, 4)], ids=idfn)
    def test_ids_with_ids(input, expected):pass
    ```搜集到的测试`ID`如下：```bash
    collected 2 items
    <Module test_ids.py><Function test_ids_with_ids[2-3]><Function test_ids_with_ids[4-5]>
    ```通过上面的例子我们可以看到，对于一个具体的`argvalues`参数`(1, 2)`来说，它被拆分为`1`和`2`分别传递给`idfn`，并将返回值通过`-`符号连接在一起作为一个测试`ID`返回，而不是将`(1, 2)`作为一个整体传入的；下面我们在源码中看看是如何实现的：```python
    # _pytest/python.pydef _idvalset(idx, parameterset, argnames, idfn, ids, item, config):if parameterset.id is not None:return parameterset.idif ids is None or (idx >= len(ids) or ids[idx] is None):this_id = [_idval(val, argname, idx, idfn, item=item, config=config)for val, argname in zip(parameterset.values, argnames)]return "-".join(this_id)else:return _ascii_escaped_by_config(ids[idx], config)
    ```和我们猜想的一样，先通过`zip(parameterset.values, argnames)`将`argnames`和`argvalues`的值一一对应，再将处理过的返回值通过`"-".join(this_id)`连接；另外，如果我们足够细心，从上面的源码中还可以看出，假设已经通过`pytest.param`指定了`id`属性，那么将会覆盖`ids`中对应的测试`ID`，我们来证实一下：```python
    @pytest.mark.parametrize('input, expected',[(1, 2), pytest.param(3, 4, id='id_via_pytest_param')],ids=['first', 'second'])
    def test_ids_with_ids(input, expected):pass
    ```搜集到的测试`ID`如下：```bash
    collected 2 items
    <Module test_ids.py><Function test_ids_with_ids[first]><Function test_ids_with_ids[id_via_pytest_param]>
    ```测试`ID`是`id_via_pytest_param`，而不是`second`；
    

    讲了这么多ids的用法，对我们有什么用呢？

    我觉得，其最主要的作用就是更进一步的细化测试用例，区分不同的测试场景，为有针对性的执行测试提供了一种新方法；

    例如，对于以下测试用例，可以通过-k 'Window and not Non'选项，只执行和Windows相关的场景：

    # src/chapter-11/test_ids.pyimport pytest@pytest.mark.parametrize('input, expected', [pytest.param(1, 2, id='Windows'),pytest.param(3, 4, id='Windows'),pytest.param(5, 6, id='Non-Windows')
    ])
    def test_ids_with_ids(input, expected):pass
    

• scope：声明argnames中参数的作用域，并通过对应的argvalues实例划分测试用例，进而影响到测试用例的收集顺序；

  • 如果我们显式的指明scope参数；例如，将参数作用域声明为模块级别：

    # src/chapter-11/test_scope.pyimport pytest
    

    @pytest.mark.parametrize('test_input, expected', [(1, 2), (3, 4)], scope='module')
    def test_scope1(test_input, expected):pass@pytest.mark.parametrize('test_input, expected', [(1, 2), (3, 4)], scope='module')
    def test_scope2(test_input, expected):pass
    ```搜集到的测试用例如下：```bash
    collected 4 items
    <Module test_scope.py><Function test_scope1[1-2]><Function test_scope2[1-2]><Function test_scope1[3-4]><Function test_scope2[3-4]>
    ```以下是默认的收集顺序，我们可以看到明显的差别：```bash
    collected 4 items
    <Module test_scope.py><Function test_scope1[1-2]><Function test_scope1[3-4]><Function test_scope2[1-2]><Function test_scope2[3-4]>
    ```
    

    • scope未指定的情况下（或者scope=None），当indirect等于True或者包含所有的argnames参数时，作用域为所有fixture作用域的最小范围；否则，其永远为function；

      # src/chapter-11/test_scope.py@pytest.fixture(scope='module')
      def test_input(request):pass@pytest.fixture(scope='module')
      def expected(request):pass@pytest.mark.parametrize('test_input, expected', [(1, 2), (3, 4)],indirect=True)
      def test_scope1(test_input, expected):pass@pytest.mark.parametrize('test_input, expected', [(1, 2), (3, 4)],indirect=True)
      def test_scope2(test_input, expected):pass
      

      test_input和expected的作用域都是module，所以参数的作用域也是module，用例的收集顺序和上一节相同：

      collected 4 items
      <Module test_scope.py><Function test_scope1[1-2]><Function test_scope2[1-2]><Function test_scope1[3-4]><Function test_scope2[3-4]>
      

1.1. empty_parameter_set_mark选项

默认情况下，如果@pytest.mark.parametrize的argnames中的参数没有接收到任何的实参的话，用例的结果将会被置为SKIPPED；

例如，当python版本小于3.8时返回一个空的列表（当前Python版本为3.7.3）：

# src/chapter-11/test_empty.pyimport pytest
import sysdef read_value():if sys.version_info >= (3, 8):return [1, 2, 3]else:return []@pytest.mark.parametrize('test_input', read_value())
def test_empty(test_input):assert test_input

我们可以通过在pytest.ini中设置empty_parameter_set_mark选项来改变这种行为，其可能的值为：

• skip：默认值
• xfail：跳过执行直接将用例标记为XFAIL，等价于xfail(run=False)
• fail_at_collect：上报一个CollectError异常；

1.2. 多个标记组合

如果一个用例标记了多个@pytest.mark.parametrize标记，如下所示：

# src/chapter-11/test_multi.py@pytest.mark.parametrize('test_input', [1, 2, 3])
@pytest.mark.parametrize('test_output, expected', [(1, 2), (3, 4)])
def test_multi(test_input, test_output, expected):pass

实际收集到的用例，是它们所有可能的组合：

collected 6 items
<Module test_multi.py><Function test_multi[1-2-1]><Function test_multi[1-2-2]><Function test_multi[1-2-3]><Function test_multi[3-4-1]><Function test_multi[3-4-2]><Function test_multi[3-4-3]>

1.3. 标记测试模块

我们可以通过对pytestmark赋值，参数化一个测试模块：

# src/chapter-11/test_module.pyimport pytestpytestmark = pytest.mark.parametrize('test_input, expected', [(1, 2), (3, 4)])def test_module(test_input, expected):assert test_input + 1 == expected

2. pytest_generate_tests钩子方法

pytest_generate_tests方法在测试用例的收集过程中被调用，它接收一个metafunc对象，我们可以通过其访问测试请求的上下文，更重要的是，可以使用metafunc.parametrize方法自定义参数化的行为；

我们先看看源码中是怎么使用这个方法的：

# _pytest/python.pydef pytest_generate_tests(metafunc):# those alternative spellings are common - raise a specific error to alert# the useralt_spellings = ["parameterize", "parametrise", "parameterise"]for mark_name in alt_spellings:if metafunc.definition.get_closest_marker(mark_name):msg = "{0} has '{1}' mark, spelling should be 'parametrize'"fail(msg.format(metafunc.function.__name__, mark_name), pytrace=False)for marker in metafunc.definition.iter_markers(name="parametrize"):metafunc.parametrize(*marker.args, **marker.kwargs)

首先，它检查了parametrize的拼写错误，如果你不小心写成了["parameterize", "parametrise", "parameterise"]中的一个，pytest会返回一个异常，并提示正确的单词；然后，循环遍历所有的parametrize的标记，并调用metafunc.parametrize方法；

现在，我们来定义一个自己的参数化方案：

在下面这个用例中，我们检查给定的stringinput是否只由字母组成，但是我们并没有为其打上parametrize标记，所以stringinput被认为是一个fixture：

# src/chapter-11/test_strings.pydef test_valid_string(stringinput):assert stringinput.isalpha()

现在，我们期望把stringinput当成一个普通的参数，并且从命令行赋值：

首先，我们定义一个命令行选项：

# src/chapter-11/conftest.pydef pytest_addoption(parser):parser.addoption("--stringinput",action="append",default=[],help="list of stringinputs to pass to test functions",)

然后，我们通过pytest_generate_tests方法，将stringinput的行为由fixtrue改成parametrize：

# src/chapter-11/conftest.pydef pytest_generate_tests(metafunc):if "stringinput" in metafunc.fixturenames:metafunc.parametrize("stringinput", metafunc.config.getoption("stringinput"))

最后，我们就可以通过--stringinput命令行选项来为stringinput参数赋值了：

λ pytest -q --stringinput='hello' --stringinput='world' src/chapter-11/test_strings.py
..                                                                     [100%] 
2 passed in 0.02s

如果我们不加--stringinput选项，相当于parametrize的argnames中的参数没有接收到任何的实参，那么测试用例的结果将会置为SKIPPED

λ pytest -q src/chapter-11/test_strings.py
s                                                                  [100%] 
1 skipped in 0.02s

注意：

不管是metafunc.parametrize方法还是@pytest.mark.parametrize标记，它们的参数（argnames）不能是重复的，否则会产生一个错误：ValueError: duplicate 'stringinput'；