- Command Line Options
- Using with CI
- Mutation Badge
- How-to Guides
- Debugging Issues
- Infection Playground
- GitHub Sponsors ♥️
- Compare with competitors
- What's new in Infection 0.21.0
- What's new in Infection 0.20.0
- What's new in Infection 0.19.0
- What's new in Infection 0.18.0
- What's new in Infection 0.17.0
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:
You can commit it to the VCS and, if necessary, override it locally by creating
infection.json which should be ignored (e.g. in
directories- array, contains all folders with source code you want to mutate. Can be
., but make sure to exclude
vendorin this case.
excludes- array, contains all folders or files you want to exclude within your source folders. You can use glob pattern (
*Bundle/**/*/Tests) for them as well as everything that accepts Symfony Finder’s notPath() method - path or regular expression. In order to skip all files containing
.interface.phpin the name, you would write it as
Infection automatically excludes
testsfolders if the source folder is
.(current dir). Make sure to not mutate your test suite.
excludeskey are relative to the
timeout- the maximum allowed time for mutated processes to run, in whole seconds, before they are considered a timeout. Make sure to set it to higher value than your tests are executed in seconds to avoid false-positives.
text- human-readable text log file. Must see to understand what is going on during mutation process.
summary- summary log file, which will only display the amount of mutants per category, (Killed, Errored, Escaped, Timed Out, Skipped, and Not Covered)
json- machine-readable file in JSON format. Can be programmatically analyzed. In addition to general stats, contains original, mutated code, diff and test framework output for each Mutant.
perMutator- a markdown file which will give a break-down of the effectiveness of each mutator.
Each of the above logs accept a local filename to write to (eg
infection.log), or you can write to the terminal using
php://stderr, this can be useful in CI to store the mutation results in the output.
github- prints GitHub Annotation warnings right in the Pull Request. Supposed to be used with GitHub Actions. See
tmpDir- Optional. It’s a folder where Infection creates its configs, caches and other stuff. It may be useful for people who doesn’t have access to the default system temporary folder and/or doesn’t have write permissions. Either absolute
var/cachepaths can be used.
phpUnit- optional key
configDir- custom directory path with
phpunit.xml.distfile. This is useful for example for old Symfony app, where
phpunit.xml.distis located at
customPath- custom path to PHPUnit executable. This is useful when you run tests by external shared phar file that is located outside project root.
ignoreMsiWithNoMutations- optional key, whether to ignore MSI violations with zero mutations
minMsi- optional key, a value for the Minimum Mutation Score Indicator (MSI) percentage value
minCoveredMsi- optional key, a value for the Minimum Covered Code Mutation Score Indicator (MSI) percentage value
mutators: optional key, it contains the settings for different mutations and profiles, read more about it here
testFramework: optional key, it sets the framework to use for testing. Defaults to
phpunit. This gets overridden by the
--test-frameworkcommand line argument.
bootstrap: optional key, use to specify a file to include as part of the startup to pre-configure the Infection environment. Useful for adding custom autoloaders not included in composer.
initialTestsPhpOptions: optional key, specify additional php options for the initial test (IE: Enabling X-Debug).
--initial-tests-php-optionswill override this option.
testFrameworkOptions: optional key, specify additional options to pass to the test framework (IE: Enabling Verbose Mode).
--test-framework-optionswill override this option.
If you have a custom autoloader or bootstrap file for your application, you should tell Infection about it.
For example you have
then you have to add it to the
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.
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:
or if you cloned it to some folder:
# cd /path/to/project/root
In order to run Infection with Xdebug, you have several options:
In this case just run
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"
In order to run Infection with
phpdbg instead of Xdebug, you need to execute the following command:
phpdbg -qrr infection.phar
It is possible to run Infection without any debugger enabled. However, in this case you should provide already generated code coverage as an option
Read more what types of coverage Infection requires and how to do it.
@codeCoverageIgnore annotation on class and method level.
The following class will not be mutated, because it does not produce any code coverage.
In this example, method
generate() will be skipped from mutation logic, but
getDependencies() will be mutated as usual method.
Infection exposes a couple of environment variables:
INFECTION=1this can be used in test environment to check whether the tests are executed from Infection or not.
TEST_TOKEN=<int>for each process that Infection creates for running tests for particular Mutant, it adds
TEST_TOKEN=<int>environment variable to be used for setting up connections to different databases. Read more here.