Gherkin-style specs that run inside PHPUnit.

GET STARTED

First scenario in four moves.

1. Install.

   composer require --dev noizu-labs/php-conformCopy

2. Register the extension.

   phpunit.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <phpunit bootstrap="vendor/autoload.php" colors="true" cacheDirectory=".phpunit-cache">
       <testsuites>
           <testsuite name="default">
               <directory>tests</directory>
           </testsuite>
       </testsuites>
       <extensions>
           <bootstrap class="\NoizuLabs\PHPConform\PHPUnitExtension\BDDExtension"/>
       </extensions>
   </phpunit>

   The <extensions> entry is the story output: a PHPUnit event extension, and without it the scenarios still run — you just see none of the story blocks. The <testsuites> entry is the other half: it tells PHPUnit where your tests live. Without one, PHPUnit runs nothing at all.

3. Describe.

   calculator_scenario.suite

   #Story: Smoke test
   As a developer
   I would like to show that the suite runs.
   
   #Scenario: The calculator adds
   Given a calculator
   When I add 2 plus 6
   Then the total should be 8

   Name the file after your test class — trailing Test dropped, snake_cased, next to it in the same directory: CalculatorScenarioTest → calculator_scenario.suite.

4. Wire and run.

   CalculatorSteps.php

   <?php
   
   use NoizuLabs\PHPConform\PHPUnitExtension\StepAbstract;
   
   class CalculatorSteps extends StepAbstract
   {
       protected int $total = 0;
   
       /** @given a calculator */
       public function createCalculator()
       {
           $this->total = 0;
       }
   
       /** @when I add $a plus $b */
       public function addition($a, $b)
       {
           $this->total = (int) $a + (int) $b;
       }
   
       /** @then the total should be $total */
       public function checkTotal($total)
       {
           $this->assertEquals((int) $total, $this->total);
       }
   }

   PHPUnit only loads *Test.php files itself, so the step class has to come off composer's autoloader. The simplest way is a classmap over your tests directory — add this to composer.json, then run composer dump-autoload:

   composer.json

   "autoload-dev": {
       "classmap": ["tests/"]
   }

   CalculatorScenarioTest.php

   <?php
   
   use NoizuLabs\PHPConform\PHPUnitExtension\ScenarioSuite;
   
   /**
    * @stepClass CalculatorSteps
    */
   class CalculatorScenarioTest extends ScenarioSuite
   {
   }

   $ vendor/bin/phpunit --no-progress

That is the whole ceremony: a spec file, a step class, a suite PHPUnit already knows how to run, and one extension entry that turns results into stories.