README

PhpUnit @dataProvider 辅助工具

PhpUnit 的便捷 require-dev 测试工具。允许使用 zip()、join()、cross()、pairs()、slice() 等方法管理数据提供程序。

安装
- Composer
概述
文档
- 功能
- 特性
文档
- 示例
- 高级示例
迁移

安装

PHP 7.1 及以上版本的安装

composer require --dev rawr/phpunit-data-provider

概述

DataProvider 可用于构建、组合和编辑用于与 PhpUnit 一起使用的 PhpUnit 数据提供程序。

`DataProvider::list()`

DataProvider::list() 提供一个元素列表。每次调用测试时使用单个参数。

/**
 * @test 
 * @dataProvider colors
 */
public function test(string $color): void {
  // your test here
}

public function colors(): DataProvider {
  return DataProvider::list("blue", "yellow", "red");
}

此外，DataProvider::list() 根据值命名行。

`DataProvider::join()`

垂直连接数据提供程序。

💡 当两个数据提供程序在其他测试中使用，并且新测试应使用它们时，非常有用。

/**
 * @test 
 * @dataProvider colors
 */
public function test(string $color, string $thing): void {
  // your test here
}

public function colors(): DataProvider {
  return DataProvider::join($this->natureColors(), $this->shadeColors());
}

public function natureColors(): DataProvider {
  return DataProvider::sets(
    ["blue", "sky"], 
    ["yellow", "sun"],
    ["red", "apple"]
  );
}

public function shadeColors(): array {
  return [
    'hair' => ["gray", "hair"], 
    'ink' => ["black", "ink"],
    'dust' => ["lightgray", "dust"]
  ];
}

`DataProvider::zip()`

水平连接数据提供程序。

💡 对于保持数据提供程序简洁简单非常有用。

/**
 * @test 
 * @dataProvider colors
 */
public function test($blueColor, $blueThing, $yellowThing, $redThing): void {
  // your test here
}

public function colors(): DataProvider {
  return DataProvider::zip($this->blueThings(), $this->yellowThings(), $this->redThings());
}

public function blueThings(): DataProvider {
  return DataProvider::sets(
    ["blue", "pen"],
    ["light blue", "shirt"],
    ["deep blue", "ocean"]
  );
}

public function yellowThings(): iterable {
  return DataProvider::list("sun", "apple", "lemon");
}

public function redThings(): iterable {
  yield ["apple"];
  yield ["cranberry"];
  yield ["car"];
}

`DataProvider::cross()`

创建给定数据提供程序的方阵。

💡 对于测试所有参数组合非常有用。

/**
 * @test 
 * @dataProvider shadedColors
 */
public function test(string $shade, string $color): void {
  // your test here
}

public function shadedColors(): DataProvider {
  return DataProvider::cross($this->shades(), $this->colors());
}

public function shades(): iterable {
  return DataProvider::list("light", "standard", "dark");
}

public function colors(): array {
  return [
    ["blue"], ["yellow"], ["red"]
  ];
}

`DataProvider::pairs()`

调用测试时带有两个参数。每个参数都与所有其他参数配对。

示例显示了测试配对图像格式

/**
 * @test
 * @dataProvider formats
 */
public function shouldConvertFile(string $from, string $to): void {
  // your test here
}

public function formats(): array {
  return DataProviders::distinctPairs('png', 'jpg', 'bmp');
}

`DataProvider::of()`

从 PhpUnit 接受的原始数组中实例化一个 DataProvider。

public function example(): DataProvider {
  return DataProvider::of($this->rawArray());
}

public function rawArrayDataProvider(): array {
  return [
    'key' => ['argument 1', 'argument 2']
  ];
}

`DataProvider::sets()`

为每个测试提供多个参数。DataProvider::sets() 根据值命名每一行。

/**
 * @test 
 * @dataProvider colors
 */
public function test(string color, string $thing): void {
  // your test here
}

public function colors(): DataProvider {
  return DataProvider::sets(
    ["blue", "sky"], 
    ["yellow", "sun"],
    ["red", "apple"]
  );
}

`DataProvider::dictionary()`

为测试指定单个参数。DataProvider::dictionary() 根据提供的数组键命名每一行。

/**
 * @test 
 * @dataProvider colors
 */
public function test(string color): void {
  // your test here
}

public function colors(): DataProvider {
  return DataProvider::dictionary([
    "custom key 1" => "blue", 
    "custom key 2" => "yellow", 
    "custom key 3" => "red"  
  ]);
}

在大多数情况下，可能应使用 DataProvider::list() 而不是 DataProvider::dictionary()。当参数不是自我解释时，方法 ::dictionary() 很有用，例如

public function ports(): DataProvider {
  return DataProvider::dictionary([
    "http"  => 80, 
    "https" => 443, 
    "ftp"   => 21  
  ]);
}

文档

特性

DataProvider 接受多种提供者类型。
每个构建方法根据值设置适当的行名
正确处理键的重复，并以信息性的方式格式化
延迟评估迭代器，即使提供者被多次使用，也只调用它们一次

功能

创建新的数据提供者

DataProvider::list()，DataProvider::sets()，DataProvider::dictionary()，DataProvider::pairs()，DataProvider::distinctPairs()

组合现有提供者

DataProvider::zip()，DataProvider::join()，DataProvider::cross()，DataProvider::of()

编辑现有提供者

DataProvider.slice()，DataProvider.drop()

命名

DataProvider 根据值设置每行的适当名称。

/**
 * @test 
 * @dataProvider colors
 */
public function test(string color, string $thing): void {
  // your test here
}

public function colors(): DataProvider {
  return DataProvider::sets(
    ["blue", "sky"], 
    ["yellow", "sun"],
    ["red", "apple"]
  );
}

文档

示例用法

DataProvider::cross() 返回一个 DataProvider 实例，它是一个输入数据提供者的方阵。

/**
 * @test
 * @dataProvider services
 */
public function shouldLogin(string $service, string $method, int $port): void {
  // your test here
}

public function services(): DataProvider {
  return DataProvider::cross(
    [
      ['github.com'], ['bitbucket.com'], ['gitlab.com'], ['sourceforge.net']
    ],
    [
      ['http', 80],
      ['https', 443],
      ['ssh', 22]
    ]);
}

这相当于有一个由12个条目组成的常规数据提供者，如下所示

public function services(): array {
  return [
    ['github.com', 'http', 80],
    ['github.com', 'https', 443],
    ['github.com', 'ssh', 22],
    ['bitbucket.com', 'http', 80],
    ['bitbucket.com', 'https', 443],
    ['bitbucket.com', 'ssh', 22],
    ['gitlab.com', 'http', 80],
    ['gitlab.com', 'https', 443],
    ['gitlab.com', 'ssh', 22],
    ['sourceforge.net', 'http', 80],
    ['sourceforge.net', 'https', 443],
    ['sourceforge.net', 'ssh', 22],
  ];
}

DataProvider::cross() 接受不同类型的数据提供者：array，\Iterator，\IteratorAggregate，\Traversable，\Generator，iterable 和 DataProvider。

这意味着 DataProvider 可以组合在一起。

public function services(): DataProvider {
  return DataProvider::cross(
    DataProvider::list('github.com', 'bitbucket.com', 'gitlab.com', 'sourceforge.net'),
    DataProvider::sets(['http', 80], ['https', 443], ['ssh', 22]));
}

高级用法

DataProvider 可以与其他 DataProvider 以及常规 PhpUnit 数据提供者一起使用。

/**
 * @test
 * @dataProvider urls
 */
public function test0(string $url): void {
  // your test here
}

/**
 * @test
 * @dataProvider services
 */
public function test1(string $url, string $name, string $method, int $port): void {
  // your test here
}

/**
 * @test
 * @dataProvider allServices
 */
public function test2(string $url, string $name, string $method, int $port): void {
  // your test here
}

public function urls(): DataProvider {
  return DataProvider::list('github.com', 'bitbucket.com', 'gitlab.com', 'sourceforge.net');
}

public function rawArrayProvider(): array {
  return [
    ['GitHub'],
    ['BitBucket'],
    ['GitLab'],
    ['SourceForge']
  ];
}

public function services(): DataProvider {
  return DataProvider::cross(
    DataProvider::zip($this->urls(), $this->rawArrayProvider()),
    DataProvider::sets(
      ['http', 80],
      ['https', 443],
      ['ssh', 22]));
}

public function allServices(): DataProvider {
  return DataProvider::join(
    $this->services(),
    $this->localServices()
  );
}

public function localServices(): array {
   return [
     'my local service' => ['localhost', 'local', 'http', '80']
   ];
}

接受类型

DataProvider 接受任何类型的数据提供者

PhpUnit 允许的所有类型：array，iterable，\Traversable，\Iterator，\IteratorAggregate，\Generator
DataProvider 本身

注意

关于 DataProvider::join() 的说明

DataProvider::join() 保留每个数据提供者的名称，并垂直地连接名称。标题中的重复项被保留并适当地展示。
DataProvider::join() 接受任何类型的数据提供者。
DataProvider::join() 在概念上类似于对原始数组提供者调用 \array_merge()，但是 \array_merge() 会覆盖重复的键，而 DataProvider::join() 保留重复的键，并适当地命名它们。
DataProvider::join() 使用可变参数 ...iterable 并可以用于连接多个数据提供者
DataProvider::join() 只能连接每行具有相同数量参数的数据提供者，否则会抛出 IrregularDataProviderException。
DataProvider::join() 接受 DataProvider 或 PhpUnit 所接受的任何 iterable。如果传递了不正确的数据提供者，将抛出 MalformedDataProviderException 异常。

关于 DataProvider::zip() 的说明

DataProvider::zip() 保留了每个数据提供者的名称，并将它们水平合并。
DataProvider::zip() 接受任何类型的数据提供者。
DataProvider::zip() 接受可变参数 ...iterable，可以合并多个数据提供者。
DataProvider::zip() 只能合并具有相同行数的数据提供者，否则将抛出 IrregularDataProviderException 异常。此外，每个特定的数据提供者必须在每行中具有相同数量的参数。
DataProvider::zip() 接受 DataProvider 或 PhpUnit 所接受的任何 iterable。如果传递了不正确的数据提供者，将抛出 MalformedDataProviderException 异常。

关于 DataProvider::pairs() 的说明

DataProvider::pairs() 生成重复的配对（例如 'png', 'png'），而 DataProvider::distinctPairs() 只生成不同参数的配对。

关于 DataProvider::sets() 的说明

DataProvider::sets() 与 DataProvider::of() 类似，但 ::of() 接受显式的名称，而 DataProvider::sets() 则根据集合中的值来命名行。

从旧版本迁移

要使用版本 3.0.0，从 2.4.0 或更早版本迁移

库命名空间从 \TRegx\DataProvider\ 更改为 \TRegx\PhpUnit\DataProviders\ 。
将 \TRegx\DataProvider\DataProviders::cross() 更改为 \TRegx\PhpUnit\DataProviders\DataProvider::cross()。
将 \TRegx\DataProvider\CrossDataProviders::cross() 更改为 \TRegx\PhpUnit\DataProviders\DataProvider::cross()。
将您的数据提供者返回类型从 array 更改为 iterable 或 \TRegx\PhpUnit\DataProviders\DataProvider。
已删除 \TRegx\DataProvider\CrossDataProviders::builder()，请使用 \TRegx\PhpUnit\DataProviders\DataProvider::cross() 代替。

rawr / cross-data-providers

维护者

详细信息