README

NOTICE: Library is under refactoring for release of V5.0.0 and docs reflect the new style of specs

Code Specs isn't just another tests library - it's the way you design your solutions. The Specs Way.

Code Specs is built as a PHPUnit plugin(with Codeception support as well) for writing BDD style Unit tests in a specification way using human-readable format.

Goal of Code Specs is to add a bunch of cool tools for unit testing and show a way of representing unit tests as a behavior specifications that describes specific class behavior in variety of use-cases.

The min hero of Code Specs that does the magic is Tester. Tester represents an actor who ensures you code pass specifications(yes, like in Codeception - this library expired by Codeception). See iy by yourself:

namespace Specs\Unit;

use PHPKitchen\CodeSpecs\Base\Specification;
use PHPKitchen\CodeSpecs\Actor\I;

/**
 * Specification of {@link IncomeCalculator}
 *
 * @author Dima Kolodko <prowwid@gmail.com>
 */
class IncomeCalculatorTest extends Specification {
    private const EXPECTED_TAX_FOR_FIRST_LEVEL_TAX_RULE = 4500;
    private const EXPECTED_TAX_FOR_SECOND_LEVEL_TAX_RULE = 7200;
    private const EXPECTED_TAX_FOR_THIRD_LEVEL_TAX_RULE = 30000;
    private const INCOME_AFTER_APPLYING_FIRST_LEVEL_TAX_RULE = 300000;

    /**
     * @test
     */
    public function calculateTaxBehavior() {
        $clientsPayments = []; // dummy variable, just for example
        $hoursSpentWorking = 160; // dummy variable, just for example
        $service = new IncomeCalculator($clientsPayments, $hoursSpentWorking);
        I::describe('income tax calculations');

        I::expect('for income less that 50 000 calculator use 10% tax rule', function () use ($service) {
            I::lookAt('first level income tax')
                ->seeNumber($service->calculateTax())
                ->isNotEmpty()
                ->isEqualTo(self::EXPECTED_TAX_FOR_FIRST_LEVEL_TAX_RULE);
        });

        I::expect('for income between 50 000 and 100 000 calculator use 12% tax rule', function () use ($service) {
            I::lookAt('second level income tax')
                ->seeNumber($service->calculateTax())
                ->isNotEmpty()
                ->isEqualTo(self::EXPECTED_TAX_FOR_SECOND_LEVEL_TAX_RULE);
        });

        I::expect('for income more than 100 000 calculator use 20% tax rule', function () use ($service) {
            I::lookAt('second level income tax')
                ->seeNumber($service->calculateTax())
                ->isNotEmpty()
                ->isEqualTo(self::EXPECTED_TAX_FOR_THIRD_LEVEL_TAX_RULE);
        });
    }

    /**
     * @test
     */
    public function calculateWithTaxBehavior() {
        $clientsPayments = []; // dummy variable, just for example
        $hoursSpentWorking = 160; // dummy variable, just for example
        $service = new IncomeCalculator($clientsPayments, $hoursSpentWorking);

        I::describe('Net income calculation');
        I::expect('calculator calculates income with tax using 10% tax rule for income less that 50 000');

        I::lookAt('income tax')
            ->seeNumber($service->calculateWithTax())
            ->isNotEmpty()
            ->isEqualTo(self::INCOME_AFTER_APPLYING_FIRST_LEVEL_TAX_RULE);


    }
}

CodeSpecs also decorates errors output so, for example, if "IncomeCalculator" service from example above will incorrectly calculate income the error output will include following message(example of output in PHPStorm):

Requirements

PHP >= 7.4 is required.

PHPUnit >= 9.1 is required.

Getting Started

Run the following command to add CodeSpecs to your project's composer.json. See Packagist for specific versions.

composer require --dev php-kitchen/code-specs

Or you can copy this library from:

• Packagist
• Github

Then you can use CodeSpecs in your test simply extending from Specification class. Example:

use PHPKitchen\CodeSpecs\Base\Specification;

class YourTest extends Specification {

    /**
     * @test
     */
    public function myMethodBehavior() {
        I::lookAt('my dummy variable')
            ->seeBool(true)
            ->isFalse();
    }
}

Note: If you want to use CodeSpecs with Codeception read Codeception integration guide

For additional information and guides go to the project documentation See changes log for information about changes in releases and update guide for information about upgrading to a next major version.

Contributing

If you want to ask any questions, suggest improvements or just to talk with community and developers, join our server at Discord Read organization contributing rules for additional information.

Spreading the Word

Acknowledging or citing CodeSpecs is as important as direct contributions.

If you are using CodeSpecs as part of an OpenSource project, a way to acknowledge it is to use a special badge in your README:

If your code is hosted at GitHub, you can place the following in your README.md file to get the badge:

[![CodeSpecs](https://img.shields.io/badge/Tested_By-CodeSpecs-brightgreen.svg?style=flat)](https://github.com/php-kitchen/code-specs)

or use regular HTML:

<a href="https://github.com/php-kitchen/code-specs"><img src="https://img.shields.io/badge/Tested_By-CodeSpecs-brightgreen.svg" alt="Tested By"></a>