livexample

Живой пример

Это среда тестирования, ориентированная на документацию, для PHP 5.3–7.x. Его цель — убедиться, что ваши примеры кода работают посредством модульного тестирования. Вдохновлен тестированием Golang «Примеры».

Простой пример тестового примера

См. пример ниже. Первый раздел представляет собой пример кода, который будет протестирован. Комментарий, начинающийся с Output представляет собой тестовый код.

 <?php

function hello ( string $ name ): string {
	return ' hello ' . $ name ;
}
echo hello ( ' alice ' ) . "n" ;
echo hello ( ' bob ' ) . "n" ;

// Output:
// hello alice
// hello carol

Этот пример кода не работает. Ожидается, что на выходе появится слово «Кэрол», однако оно не появляется. Этот тестовый пример не пройден, но вы можете знать, что в примере кода есть проблема, и можете ее исправить.

Как это работает?

Liveexample выполняет следующие шаги:

1. Найдите оператор Output в примере кода, проанализировав его.
2. Запустите код в PHPUnit и запишите результат.
3. Сравните ожидаемый результат и фактический результат.

Преимущества

Иногда коды примеров не работают из-за добавления новых функций, забывания их обновить, запросов на включение, которые не учитывают коды примеров и так далее.

Неработающие примеры кода — плохой опыт для пользователей библиотеки.

Используя Livexample, вы получите преимущества:

• Коды ваших примеров защищены от неожиданной регрессии.
• Вы можете легко проверить корректность ваших примеров кодов.
• Пользователи вашей библиотеки могут использовать действительные примеры кодов путем копирования и вставки.
• Вам не нужно вносить большие изменения в существующие примеры кода; просто добавляю некоторые комментарии.

Функции

• Livexample является частью PHPUnit.
• Очень низкая стоимость обучения.

Начиная

Установите suin/livexample через Composer:

 composer require --dev suin/livexample

Добавьте файл ExampleTest.php в каталог тестов:

 use Livexample  PHPUnit  ExampleTestCase ;

class ExampleTest extends ExampleTestCase
{
    public function exampleFiles ()
    {
        // specify your example code directory.
        return self :: exampleDirectory ( ' example ' );
    }
}

Запустите phpunit:

 phpunit

Синтаксис утверждений

Существует два синтаксиса утверждения:

• Длинный: // Output: {expected output}
• Коротко: //=> {expected output}

 echo 1 ; // Output: 1 

 echo " hello " ; //=> hello 

 var_dump ([ 1 , 2 , 3 ]);
// Output:
// array(3) {
// 	[0] =>
// 	int(1)
// 	[1] =>
// 	int(2)
// 	[2] =>
// 	int(3)
// } 

Советы: var_dump($object)

Функция var_dump() печатает идентификаторы объектов, которые представляют собой #some-number рядом с именем класса. Поскольку идентификаторы зависят от среды выполнения, вы не можете жестко запрограммировать их в операторе Output: Вместо жесткого кодирования идентификатора вы можете использовать заполнитель %d для числа:

 <?php
var_dump ( new stdClass );
// Output:
// object(stdClass)#%d (0) {
// } 

Советы: запустите пример сценария с помощью команды php

 php -d auto_prepend_file=vendor/autoload.php 
    -d xdebug.overload_var_dump=0 
    example/simple-usage.php

Почему поддерживается PHP 5.3 в 2017 году?

Официальная поддержка PHP 5.3 закончилась, однако RHEL/CentOS продолжает поддерживать PHP 5.3 даже в 2017 году. Старые среды PHP по-прежнему остаются в работающем сервисе. Livexample также предполагается использовать для рефакторинга таких старых сред.

Журнал изменений

Пожалуйста, смотрите CHANGELOG для более подробной информации.

Содействие

Пожалуйста, смотрите ВКЛАД для более подробной информации. Пожалуйста, исправьте мой английский.