Usage

Configuration

The first time you run Infection for your project, it will ask you several questions to create a config file infection.json.dist, with the following structure:

{
"source": {
"directories": [
"src"
],
"excludes": [
"Config",
"Folder/with/File.php"
]
},
"timeout": 10,
"logs": {
"text": "infection.log",
"summary": "summary.log",
"debug": "debug.log",
"perMutator": "per-mutator.md",
"badge": {
"branch": "master"
}
},
"tmpDir": "/opt/tmp-folder",
"phpUnit": {
"configDir": "app",
"customPath": "\/path\/to\/phpunit-6.1.phar"
}
"mutators": {
"@default": true,
"@function_signature": false,
"TrueValue": {
"ignore": [
"NameSpace\\*\\Class::method"
]
}
},
"testFramework":"phpunit",
"bootstrap":"./tests/bootstrap.php",
"initialTestsPhpOptions": "-d zend_extension=xdebug.so",
"testFrameworkOptions": "-vvv"
}

You can commit it to the VCS and, if necessary, override it locally by creating infection.json which should be ignored (e.g. in .gitignore).

Configuration settings

How to use custom autoloader or bootstrap file

If you have a custom autoloader or bootstrap file for your application, you should tell Infection about it.

For example you have

// custom-autoloader.php

require NonPsr4CompliantFile.php

then you have to add it to the infection.json file:

{
"bootstrap": "./custom-autoloader.php"
}

Thus, Infection will know how to autoload NonPsr4CompliantFile class. Without adding it to the config, Infection will not be able to create Mutations because internally it uses new \ReflectionClass() objects.

Running Infection

Ensure that your tests are all in a passing state (incomplete and skipped tests are allowed). Infection will quit if any of your tests are failing.

If you have installed Infection as a global composer package, just run it in your project’s root:

infection

or if you cloned it to some folder:

# cd /path/to/project/root

~/infection/bin/infection

Running with Xdebug

In order to run Infection with Xdebug, you have several options:

Enable Xdebug globally

In this case just run

./infection.phar --threads=4

Enable Xdebug per process

Since Infection needs Xdebug only to generate code coverage in a separate process, it is possible to enable debugger just there.

Assuming Xdebug is disabled globally, run

./infection.phar --initial-tests-php-options="-d zend_extension=xdebug.so"

Running with phpdbg

In order to run Infection with phpdbg instead of Xdebug, you need to execute the following command:

phpdbg -qrr infection.phar

Running without debugger

It is possible to run Infection without any debugger enabled. However, in this case you should provide already generated code coverage as an option

./infection.phar --coverage=path/to/coverage

Read more what types of coverage Infection requires and how to do it.

Using with PHPUnit

@codeCoverageIgnore support

Infection supports @codeCoverageIgnore annotation on class and method level.

The following class will not be mutated, because it does not produce any code coverage.

/**
* @codeCoverageIgnore
*/
class Calculator
{
public function add(float $a, float $b): float
{
return $a + $b;
}
}

In this example, method generate() will be skipped from mutation logic, but getDependencies() will be mutated as usual method.

class ProductFixture
{
/**
* @codeCoverageIgnore
*/
public function generate(): void
{
// generate logic
}

public function getDependencies(): array
{
return [CategoryFixture::class];
}
}

Updating Phar distribution

To update your current phar, just run:

./infection.phar self-update

Note: Using a phar means that fixes may take longer to reach your version, but there’s more assurance of having a stable development version. The public key is downloaded only once. It is re-used by self-update to verify future phar releases.

Updating to pre-release versions

While we recommend to use the most stable releases, you can update it to pre-release version if available

./infection.phar self-update --pre

Check availability of new versions

It’s possible to check if there is a new version available:

./infection.phar self-update --check

Self-Update Request Debugging

If you experience any issues self-updating with unexpected openssl or SSL errors, please ensure that you have enabled the openssl extension. For example on Windows, you can do this by adding or uncommenting the following line in the php.ini file for PHP on the command line (if different than the file for your http server):

extension=php_openssl.dll