• Guide
• Playground
• GitHub
• Ecosystem

  • Help

  • • Twitter
    • Mastodon
    • Discord
    • Infection Discussions

  • Resource Lists

  • • Official Repos

Usage

Configuration

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

{
"source": {
"directories": [
"src"
        ],
"excludes": [
"Config",
"Folder/with/File.php",
"/\\.interface\\.php/",
"{Infrastructure/.*}"
        ]
    },
"timeout":10,
"threads":"max",
"logs": {
"text":"infection.log",
"html":"infection.html",
"summary":"summary.log",
"json":"infection-log.json",
"perMutator":"per-mutator.md",
"github":true,
"gitlab":"gitlab-code-quality.json",
"stryker": {
"badge":"/^release-.*$/"
        },
"summaryJson":"summary.json"
    },
"tmpDir":"/opt/tmp-folder",
"phpUnit": {
"configDir":"app",
"customPath":"\/path\/to\/phpunit-6.1.phar"
    },
"mutators": {
"global-ignore": [
"FooClass::__construct"
        ],
"global-ignoreSourceCodeByRegex": [
"Assert::.*"
        ],
"@default":true,
"@function_signature":false,
"TrueValue": {
"ignore": [
"NameSpace\\*\\Class::method"
            ],
"ignoreSourceCodeByRegex": [
"\\$this->logger.*"
            ]
        }
    },
"testFramework":"phpunit",
"bootstrap":"./infection-bootstrap.php",
"initialTestsPhpOptions":"-d zend_extension=xdebug.so",
"testFrameworkOptions":"--filter=Unit"
}

If you want to override settings locally, create and commit to VCSinfection.json5.dist but locally useinfection.json5 which should be ignored (e.g. in.gitignore).

By default, Infection usesjson5 format for configuration file. It allows using comments, ES5-like keys and many more. But if you for some reason can’t use it, Infection also supportsjson format.

Configuration settings

• source section:
  • directories - array, contains all folders with source code you want to mutate. Can be., but make sure to excludevendor in this case.
  • excludes - array, contains all folders or files you want to exclude within your source folders. It accepts full paths, as well as regular expressions, enclosedby any delimiter accepted by PHP. It accepts glob pattern too. However, its usage is discouraged, as it does not work exactly the same in all OS.
    Infection automatically excludesvendor,test,tests folders if the source folder is. (current dir). Make sure to not mutate your test suite.
    Paths underexcludes key are relative to thesource.directories folders.
    Here are some examples ofexcludes, assuming thatsrc is defined insource.directories:
    • "excludes": ["Config"] skips the foldersrc/Config.
    • "excludes": ["Folder/with/File.php"] skips the filesrc/Folder/with/File.php.
    • "excludes": ["/\\.interface\\.php/"] skips all files containing.interface.php in the name.
    • "excludes": ["{Infrastructure/.*}"] skips all files withinsrc/Infrastructure folder. Note that braces ({}) is a valid regex delimiter in PHP.
    • "excludes": ["{.*/Infrastructure/.*}"] skips all files within theInfrastructure path of the second level of directories withinsrc. Therefore,src/Shared/Infrastructure orsrc/SomeBoundedContext/Infrastructure would be excluded, whereassrc/Shared/Domain orsrc/SomeBoundedContext/Application would not.
• 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.
• threads - the number of threads to use by the runner when executing the mutations. Use “max” to auto calculate it.
• logs
  • text - human-readable text log file. Must see to understand what is going on during mutation process.
  • html - human-readable report, similar to PHPUnit HTML report. Based onStryker Elements. Here isan example for Infection itself. If you want to store HTML report in the cloud (useful for OSS projects), seeStryker Dashboard integration.
  • 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 (eginfection.log), or you can write to the terminal usingphp://stdout orphp://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--logger-github, but usually not necessary as it is automatically detected.
  • gitlab - GitLab (Code Climate) code quality report. Can be processed as acodequality report artifact in Gitlab.
  • summaryJson - machine-readable file in JSON format likejson but containing only general stats. Can be programmatically analyzed, for example on CI.
• 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/tmp/folder or relativevar/cache paths can be used.
• phpUnit - optional key
  • configDir - custom directory path withphpunit.xml.dist file. This is useful for example for old Symfony app, wherephpunit.xml.dist is located at./app
  • 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 ithere
• testFramework: optional key, it sets the framework to use for testing. Defaults tophpunit. This gets overridden by the--test-framework command line argument.
• bootstrap: optional key, use it 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-options will override this option.
• testFrameworkOptions: optional key, specify additional options to pass to the test framework (IE: Enabling Verbose Mode).--test-framework-options will override this option.

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 theinfection.json5 file:

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

Thus, Infection will know how to autoloadNonPsr4CompliantFile class. Without adding it to the config, Infection will not be able to create Mutations because internally it usesnew \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 withXdebug

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 Xdebugonly 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 withphpdbg

In order to run Infection withphpdbg 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.

@infection-ignore-all support

Infection supports@infection-ignore-all annotation on class, method, and statement level.

The following class will not be mutated even though it might have few covered lines.

/**
 *@infection-ignore-all
 */
classCalculator
{
publicfunctionadd(float $a, float $b):float
{
return $a + $b;
    }
}

In this example, methodgenerate() will be skipped from mutation logic, butgetDependencies() will be mutated as usual method.

classProductFixture
{
/**
     *@infection-ignore-all
     */
publicfunctiongenerate():void
{
// generate logic
    }

publicfunctiongetDependencies():array
{
return [CategoryFixture::class];
    }
}

Likewise, given this annotation Infection won’t consider anything in this loop:

/**@infection-ignore-all */
foreach ($fooas $bar) {
//
}

Exposed environment variables

Infection exposes a couple of environment variables:

• INFECTION=1 this 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 addsTEST_TOKEN=<int> environment variable to be used for setting up connections to different databases. Read morehere.