aaronhipple/sampler

Test inline code samples from your docblocks using PHPUnit

0.2.0 2017-11-18 23:46 UTC

Requires

• erusev/parsedown: ^1.6
• nikic/php-parser: ^3.0
• phpdocumentor/reflection-docblock: ^3.0
• phpunit/phpunit: >=5.0

Requires (Dev)

• codeclimate/php-test-reporter: dev-master
• squizlabs/php_codesniffer: ^3.1

MIT

• Aaron Hipple

README

Test inline code samples from your docblocks using PHPUnit!

caveats

• This is not particularly mature. Issues and pull requests welcome.
• The extracted sample code is eval'd for testing, with all those security implications. As always, be mindful only to run trusted code in sensitive environments.
• Right now it only works on classes, class methods, and functions. It does no magic to expose private or protected methods, so normal rules apply.

usage

First, install sampler as a dependency.

$ composer require aaronhipple/sampler

Then, in your PHPUnit suite, implement a case extending AbstractSampleTestCase.

use AaronHipple\Sampler\AbstractSampleTestCase;

class SampleTest extends AbstractSampleTestCase
{
    /**
     * Provide absolute paths to the directories to scan for samples.
     * 
     * @return []string An array of folder paths.
     */
    protected function paths() 
    {
        return [__DIR__ . '/../src'];
    }
   
    /**
     * (Optional) Provide a list of file extensions to scan.
     */
    protected function extensions() 
    {
        return ['php', 'inc'];
    }
}

Finally, write some samples! You can use our @sample annotation...

/**
 * Say hello to someone!
 *
 * @sample
 *   use PHPUnit\Framework\Assert;
 *   Assert::assertInternalType(
 *     'string',
 *     say_hello('Frank')
 *   );
 * @sample
 *   use PHPUnit\Framework\Assert;
 *   Assert::assertEquals(
 *     'Hello, Aaron!',
 *     say_hello('Aaron')
 *   );
 */
function say_hello($name) {
  return "Hello, $name!";
}

...or good ol' inline markdown.

/**
 * Say hello to someone!
 *
 * # Examples
 *
 * ```
 * use PHPUnit\Framework\Assert;
 * Assert::assertEquals(
 *   'Hello, Aaron!',
 *   say_hello('Aaron')
 * );
 * ```
 *
 * ```
 * use PHPUnit\Framework\Assert;
 * Assert::assertEquals(
 *   'Hello, Frank!',
 *   say_hello('Frank')
 * );
 * ```
 */
function say_hello($name) {
  return "Hello, $name!";
}

Run your test suite as usual, with phpunit.

contributing

• Pull requests are welcome.
• More tests please.
• PSR-2 is good. Use phpcbf.