README

phpCoverFish (coverfish) is an open source php cli static code validator used for code coverage pre-processing. coverFish will analyze all of your @covers annotations inside your test files before the big code coverage train will run through all of your tests and may collide with bad coverage annotations scattered along the rails. Coverfish is using plugin base validators and is easy to extend / fulfill changes or extension in code coverage annotations.

Installation

If you use Composer to manage the dependencies of your project, edit your projects composer.json file and add a dependency on df/phpcoverfish. Below you can find find a minimal example of a composer.json file that just defines a dev-time dependency on PHPCoverFish (stable strain):

...
{
    "require-dev": {
        "df/php-coverfish": "~1.0"
}
...

You can also execute the following composer command in your console:

composer require df/php-coverfish

In order to use upcoming PHPCoverFish beta releases you will need to take down the minimum-stability key in your composer.json file (set "beta"). Simply place this line above your "extra" property key:

...
"minimum-stability": "beta",
"extra": {
...

Afterwards, just call composer install "df/phpcoverfish=~1.0" or use composer update and create a symbolic link from vendor/df/coverfish/bin/coverfish.php to your web application tool directory (this step is optional).

composer install "df/php-coverfish=~1.0"

To provide coverfish system-wide just type the following command:

composer global require "df/php-coverfish=~1.0"

Don't forget to make sure you've got your composers vendor binary path available in your global shell path:

PATH=$PATH:~/.composer/vendor/bin/

As soon as coverfish will reach it's stable state we will not only provide an additional phar file but also a corresponding download link / installer for wget related installation of PHPCoverFish.

Usage

To call coverfish from your shell after installation use the following two modes: if you bound coverfish in your symfony application, composer will be create a symbolic link inside your bin/ directory so you can call this tool like others (phpunit, ...) from this path directly.

PHPUnit-Mode scan (the recommended scan mode), using existing phpunit.xml instead of "raw" parameter for scan-path, exclude-path and autoload-file:

php ./bin/coverfish scan tests/phpunit.xml \
        --phpunit-config-suite "PHPCoverFish Suite" \ 
        --output-level 1 \
        --no-ansi

for example (using phpunit.xml without any test suite name will take first test suite configuration for this scan) :

php ./bin/coverfish scan tests/phpunit.xml --output-level 1 --no-ansi

or (using phpunit test suite name "PHPCoverFish Suite" ):

php ./bin/coverfish scan tests/phpunit.xml --phpunit-config-suite "PHPCoverFish Suite" --output-level 1 --no-ansi

the screen result for code with and without called test suite should be the same:

RAW-Mode scan (alternative scan mode), using additional parameters for required scan-path, autoload-file (exclude path will be used optional here)

php <path/to/your/coverfish/vendor/>bin/coverfish.php *scan* \
        --raw-scan-path "<path/to/your/phpunit/tests>" \
        --raw-autoload-file "<path/to/your/autoload.php>" \
        --raw-exclude-path "<path/to/your/excluded/test/files>"

for example:

php ./bin/coverfish scan --raw-scan-path tests/ --raw-autoload-file "vendor/autoload.php" --raw-exclude-path "tests/data" --output-level 1 --no-ansi

the result should looking like:

PHPCoverfish arguments and parameter

To call the PHPCoverFish help page use:

php <path/to/your/coverfish/vendor/>bin/coverfish.php help scan

Arguments

scan                     scan/analyze command (currently the only available mode of coverfish)
phpunit-config           path to your project phpunit.xml config file (e.g. tests/phpunit.xml)
                         this argument override all raw-parameters (raw-scan-path, raw-autoload-path ...)

Parameters (optional)

raw-scan-path            path to your target php unit class test files or a single test file
raw-exclude-path         exclude a specific path from your planned scan 
raw-autoload-file        your application used autoload file (psr-0/psr-4 standard)
                         will be replaced by phpunit.xml file in our upcoming beta version
-f | --output-format     json, text (default) - rendering of scan result output format (json or text)
-l | --output-level      detail of scan result output (0=minimal, 1=normal(default), 2=detailed)
-n | --no-interaction    not necessary, no virtual interaction planned yet
-v | --verbose           will be handled by option '--output-level <n>'
-q | --quiet             if you fetch results in json format, you can hide direct output and analyse results as as a json object directly
        
--no-ansi                prevent colorful output of rendering results (default: false | 0)
--stop-on-error          stop on first application error | exception (default: false | 0)
--stop-on-failure        stop on first detected coverFish scan failure (default: false | 0)

Missing features, annoying bugs and project thoughts

Feel free to contact us for missing features, discovered bugs or nice ideas around this project :)

We are currently working on:

File/IO scan mode, currently php reflection ability is used to identify code coverage errors - in future versions a raw scan mode to scan files outside the autoload context will be provided
coverage warnings implementation, identify coverage problems or misconfiguration issues in use of phpunit code coverage
optimization of coverFish's output module; this module is just "bad"
refactoring of color output module, using symfony outputFormatter
mastering coverfish documentation and build up a useful wiki
include @use statement check
improve scanner/analyzer speed

Some screenshots of result screens

Depending on the chosen --output-level option coverfish will provide different output of test results

using minimal output level (—ouput-level 0), no errors in code coverage found same mode, errors in code coverage identified

using moderate (default) output level (—ouput-level 1) same mode, errors in code coverage identified and shown detailed

and using maximum output level, showing partial output of large screen result (—ouput-level 2) same mode, errors in code coverage identified and shown more detailed

Version and compatibility

Please use our latest stable version 1.0.2 of phpCoverFish for your productive static code analyzing process. This Documentation was last updated on 2018-05-15 (internal version 1.0.2)

phpCoverFish (>= 1.0.2) works fine with php7.0, php7.1 and php7.2 phpCoverFish (<= 1.0.1) is compatible with php5.5, php5.6 and php7.n

Contribute

PHPCoverFish is still under development and contributors are always welcome! Feel free to join our coverFish distributor team. Please refer to CONTRIBUTING.md to find out how to contribute to the PHPCoverFish Project.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

df / php-coverfish

Maintainers

Details