README

This tool reads the clover.xml report from phpunit and checks, if all files have a CRAP index below a specified threshold.

Installation

PHAR (recommended)

You can download the latest PHAR from https://github.com/LeoVie/clover-crap-check/releases/latest

Composer

Install via composer as a dev dependency

composer require --dev leovie/clover-crap-check

Usage

The tool has two required arguments

1. The path of the clover.xml file, that's generated by phpunit. The path can be absolute or relative to cwd.
2. The CRAP index threshold that is acceptable (min 1)

Generate the clover.xml file by using phpunit and run clover-crap-check afterwards:

vendor/bin/phpunit --coverage-clover clover.xml
vendor/bin/clover-crap-check clover.xml 50

This can give you an output like the following

 [ERROR] The following methods are crappier than allowed

 ------------ -------- ------
  Class        method   CRAP
 ------------ -------- ------
  ClassA       m1       100    
  Foo\ClassB   m2       60     
 ------------ -------- ------ 

Baseline feature

When using clover-crap-check with legacy code, likely you don't want to refactor all your files to have a low CRAP index. At the same time you want your new code to be as less CRAPpy as possible.

To achieve this with clover-crap check, there is a baseline feature.

1. Generate the baseline

In addition to the required arguments, pass the option --generate-baseline with a path to where the baseline file should get stored. The path can be absolute or relative to cwd.

vendor/bin/clover-crap-check clover.xml 50 \
  --generate-baseline=baseline.json

This will run clover-crap-check and generate a baseline file that contains all your files with a CRAP index over the defined threshold (50 in this case).

The baseline files looks like the following

[
  {
    "classFQN": "ClassA",
    "name": "m1",
    "crap": 100
  },
  {
    "classFQN": "Foo\\ClassB",
    "name": "m2",
    "crap": 60
  }
]

2. Use the baseline

After generating the baseline, you can use it in the next runs. To do this, simply pass the path to the baseline file via the option --baseline to the tool. The path can be absolute or relative to cwd.

vendor/bin/clover-crap-check clover.xml 50 \
  --baseline=baseline.json

clover-crap-check should not report anything in that case.

Now, when you add new files with a CRAP index over the defined threshold (50 in this case), you will get noticed about that. The same thing happens, when files in your baseline get CRAPpier, than they were when the baseline was generated.

This can give you an output like the following

 [ERROR] The baseline is not up to date

 [ERROR] The following methods are newly occurring

 -------- -------- ------ 
  Class    method   CRAP  
 -------- -------- ------ 
  ClassC   m3       70     
 -------- -------- ------ 

 [ERROR] The following methods got crappier

 -------- -------- ------ 
  Class    method   CRAP  
 -------- -------- ------ 
  ClassA   m1       65    
 -------- -------- ------ 

3. Keeping the baseline up to date

You can decide to generate the baseline once and then never touch it again. This can be useful when you have very many files in the baseline and don't want to bother with improving the legacy code over the time.

But you can also decide to get noticed, when a file gets less CRAPpy. To do this, you can pass the option --report-less-crappy-methods to clover-crap-check

vendor/bin/clover-crap-check clover.xml 50 \
  --baseline=baseline.json \
  --report-less-crappy-methods

This will give you a hint, e.g. when a file that had a CRAP index of 100 when you generated the baseline now has a CRAP index of 60.

 [ERROR] The baseline is not up to date

 [INFO] The following methods got less crappy

 -------- -------- ------ 
  Class    method   CRAP  
 -------- -------- ------ 
  ClassA   m1       60     
 -------- -------- ------ 

You can than manually update the CRAP value in the baseline file (to 60 in this case).

There's also another option --report-vanished-methods. When activated, clover-crap-check will notice you when there are methods in your baseline, that are not occurring anymore in the clover report or have a CRAP index below your threshold, now.

 [ERROR] The baseline is not up to date

 [INFO] The following methods vanished

 -------- -------- ------ 
  Class    method   CRAP  
 -------- -------- ------ 
  ClassA   m1       100    
 -------- -------- ------