README

PHP 对 Haskell 的 QuickCheck 的实现。

注意 这处于 ALPHA 状态。请不要使用它。

目录

• phpcheck
  • 安装
  • 类型声明
  • 注解
    • 表格化
  • 生成器
  • 断言
  • 示例
  • 命令行参数
  • 结果存储
  • 待办事项

安装

将 composer 包安装到您的项目中。您需要 PHP7.2 或更高版本

composer require --dev datashaman/phpcheck

或者，您可以全局安装 composer 包

composer global require datashaman/phpcheck

类型声明

PHPCheck 将根据类型声明自动生成检查方法的参数。

要更细粒度地控制参数，请使用方法参数上的注解。

注解

使用注解您的检查方法参数以控制提供给方法的参数。

参数标签（在参数描述中使用它们，通常在末尾）

• {@gen 方法()} 或 {@gen 方法(1, 10)}，其中 方法 是以下生成器的名称。

方法标签

• @maxSuccess 设置成功结果的成功检查次数。默认为 100。
• @tabulate 和 @coverTable（下面讨论）。

表格化

如果您用 tabulate 装饰检查方法，则会将测试用例分布信息收集到一个表中。

tabulate 的参数是表名和与当前检查关联的值列表。例如

/**
 * @tabulate "Values" [$value]
 */
public function checkBooleans(bool $value)
{
    return true;
}

如果您运行此检查，所有内容都通过，并在检查运行结束时输出表

Tables

1) Datashaman\PHPCheck\Checks\GeneratorCheck::checkBooleans

Values (100 total)

   52% true
   48% false

我们想检查生成器的覆盖率是否正确，因此我们使用 @coverTable 方法注解

/**
 * @coverTable "Values" [[true, 49], [false, 49]]
 * @tabulate "Values" [$value]
 */
public function checkBooleans(bool $value)
{
    return true;
}

注解的参数是表名和键值对列表，其中值是预期的百分比分布。

以下是从上述示例中得到的样本输出

1) Datashaman\PHPCheck\Checks\GeneratorCheck::checkBooleans

Values (100 total)

54% true
46% false

Table 'Values' had only 46.0% false, but expected 49.0%

现在，当分布不落在可接受的生成值百分比范围内时，我们会收到警告。

在这种情况下，我们通过运行检查更多次数来受益，这样我们就可以接近布尔值的预期 50/50 平均值。

/**
 * @coverTable "Values" [[true, 49], [false, 49]]
 * @maxSuccess 10000
 * @tabulate "Values" [$value]
 */
public function checkBooleans(bool $value)
{
    return true;
}

现在，在 10000 次成功迭代后，警告从输出中消失，并且百分比在可接受的 1% 错误范围内。

1) Datashaman\PHPCheck\Checks\GeneratorCheck::checkBooleans

Values (10000 total)

    50.5% true
    49.5% false

生成器

以下是目前可用的生成器列表

• 参数（可调用 $callable）
• 数组（
• ASCII 字符串（
• 布尔值（int $chanceOfGettingTrue = 50）
• 字符（$minChar = null, $maxChar = null）
• 选择（$min = PHP_INT_MIN, $max = PHP_INT_MAX）
• 选择任何（string $type）
• 日期时间（$min = null, $max = null, Generator $timezones = null）
• 日期（$min = null, $max = null）
• 元素（array $array）
• 假数据（...$args）
• 浮点数（float $min, float $max）
• 频率（array $frequencies）
• 递增元素（array $array）
• 整数（int $min = PHP_INT_MIN, int $max = PHP_INT_MAX）
• 区间（array $include = [[PHP_INT_MIN, PHP_INT_MAX]], array $exclude=[]）
• 列表（Generator $gen）
• 列表1（Generator $gen）
• 混合（
• 其中一个（array $gens）
• 调整大小（int $n, Generator $gen）
• 缩放（callable $f, Generator $gen）
• 字符串（Generator $characters = null）
• 如此（Generator $gen, callable $f）
• 如此映射（Generator $gen, callable $f）
• 如此可能（Generator $gen, callable $f）
• 时区（
• 变体（int $seed, Generator $gen）
• 向量（int $n, Generator $gen）

要从上述之一生成值，请使用 generate

>>> use function Datashaman\PHPCheck\{
...     choose,
...     generate
... };
>>>
>>> var_dump(generate(choose(0, 10)));
int(2)

要使用增加的大小生成值的样本，请使用 sample

>>> use function Datashaman\PHPCheck\{
...     ascii,
...     strings,
...     sample
... };
>>>
>>> var_dump(sample(strings(ascii())));
array(11) {
[0]=>
string(0) ""
[1]=>
string(2) "0]"
[2]=>
string(2) "^|"
[3]=>
string(3) "P@N"
[4]=>
string(5) "G1KPu"
[5]=>
string(5) "q-e1y"
[6]=>
string(4) "NcdL"
[7]=>
string(7) "hS:{_>@"
[8]=>
string(10) "wjv1X"Zm$V"
[9]=>
string(16) "aX-6*s0-WX>#cf~T"
[10]=>
string(12) ";g<&8*b&Q0=)"
}
=> null

请参阅GeneratorCheck和GeneratorTest，了解这些用法示例。

characters生成器接受字符或整数码点作为minChar和maxChar的参数。生成的字符来自Unicode字符的完整范围，不包括控制字符、私有范围和代理字符。

faker生成器接受可变数量的参数。如果你提供一个参数，它被视为Faker生成器上的属性。如果你提供多个参数，第一个参数是Faker生成器上的方法，其余的作为参数传递给该方法。

这打开了大量的领域特定生成器。有关详细信息，请参阅Faker。

检查方法

检查方法必须返回一个布尔值，表示成功或失败。

异常

我们选择使用Nuno Maduro的Collision将异常报告到控制台。

这很快就可以切换。

示例

在examples文件夹中实现了一个示例检查。要运行它

phpcheck examples

此包的Generator检查是生成器使用的极好示例。

命令行参数

phpcheck程序接受多个参数和选项

Description:
    Runs checks.

Usage:
    phpcheck [options] [--] [<path>]

Arguments:
    path                           File or folder with checks [default: "checks"]

Options:
        --bootstrap[=BOOTSTRAP]         A PHP script that is included before the checks run
        --coverage-html[=COVERAGE-HTML] Generate HTML code coverage report [default: false]
        --coverage-text[=COVERAGE-TEXT] Generate text code coverage report [default: false]
    -f, --filter[=FILTER]               Filter the checks that will be run
    -j, --log-junit[=LOG-JUNIT]         Log check execution to JUnit XML file [default: false]
    -t, --log-text[=LOG-TEXT]           Log check execution to text file [default: false]
    --max-success=MAX-SUCCESS           Maximum number of successful checks before succeeding. Testing stops at the first failure.
                                        If all tests are passing and you want to run more tests, increase this number. [default: 100]
    -d, --no-defects[=NO-DEFECTS]       Ignore previous defects [default: false]
    -h, --help                          Display this help message
    -q, --quiet                         Do not output any message
    -s, --seed[=SEED]                   Seed the random number generator to get repeatable runs
    -V, --version                       Display this application version
    --ansi                              Force ANSI output
    --no-ansi                           Disable ANSI output
    -n, --no-interaction                Do not ask any interactive question
    -v|vv|vvv, --verbose                Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

--bootstrap参数可以包含在phpcheck.xml或phpcheck.xml.dist文件中。有关示例，请参阅 ours。

--filter或-f参数是按以下方式的文件名样式匹配

ClassName::
ClassName::MethodName
MethodName

其中ClassName和MethodName可以包括使用*和?的模式，就像你预期的那样。

控制台报告器输出检查结果，就像PHPUnit一样

PHPCheck 0.1.0 by Marlin Forbes and contributors.

.............

13 / 13 (100%)

Time: 284 ms, Memory: 6.00 MB

OK (Checks: 13, Iterations: 120006, Failures: 0, Errors: 0)

使用---verbose 3或-vvv可以启用正在运行的检查列表

PHPCheck 0.1.0 by Marlin Forbes and contributors.

Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkCharacters' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkCharacters' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkStrings' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkStrings' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkAscii' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkAscii' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkBooleans' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkBooleans' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkBooleansWithPercentage' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkBooleansWithPercentage' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkCharactersWithNumbers' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkCharactersWithNumbers' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkCharactersWithStrings' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkCharactersWithStrings' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkChoose' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkChoose' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkIterations' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkIterations' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkFloats' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkFloats' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkFloatsWithDecimalGen' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkFloatsWithDecimalGen' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkStringsWithMinMax' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkStringsWithMinMax' ended
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkListOfInts' started
Check 'Datashaman\PHPCheck\Checks\GeneratorCheck::checkListOfInts' ended

Time: 305 ms, Memory: 6.00 MB

OK (Checks: 13, Iterations: 120006, Failures: 0, Errors: 0)

结果存储

PHPCheck将检查执行的结果存储在项目中的.phpcheck文件夹中。

你应该将文件夹添加到你的.gitignore文件中。

当PHPCheck发现错误或失败时，它将首先重试有缺陷的参数，然后再进行常规迭代并使用新参数。

如果你希望忽略先前的缺陷并仅运行新迭代，请使用--no-defects或-d。

待办事项

所有待办事项都已捕获为问题。