Besides general Symfony Console application command line options, Infection has its own ones.
--filter
If you’re only interested in mutating a subset of your files, you can pass a--filter
option containing:
a relative file path:
infection --filter=src/Service/Mailer.php |
a filename:
infection --filter=Mailer.php |
a relative directory path:
infection --filter=src/Service/ |
a comma separated list of relative paths:
infection --filter=src/Service/Mailer.php,src/Entity/Foobar.php |
a comma separated list of filenames:
infection --filter=Mailer.php,Foobar.php |
This in no way restricts the initial Infection check on the overall test suite which is still executed in full to ensure all tests are passing correctly before proceeding.
--threads
or-j
If you want to run tests for mutated code in parallel, set this to something > 1. It willdramatically speed up mutation process. Please note that if your tests somehow depends on each other or use database, this option can lead to failing tests which give many false-positives results.
To automatically detect the number of CPU cores, use--threads=max
.
For Infection versions below0.26.15
, you can detect the number of CPU cores depending on OS:
# on Linux |
Running Infection with more threads does not necessarily lead to better performance. Consider benchmarking several numbers to find one that works best for your particular case.
--test-framework
This is a name of the Test Framework to use. Currently, Infection supportsPHPUnit
,PhpSpec
andCodeception
.
If you are usinginfection/infection
Composer package,PHPUnit
is installed by default. Other test framework adapters will be automatically installed on demand.
PHAR distribution is bundled with all available adapters.
Feel free to request a new test framework to be supported out of the box in GitHub’s issues.
--test-framework-options
This option allows passing additional options to the test framework. Example forPHPUnit
:
infection.phar --test-framework-options="--verbose --filter=just/unit/tests" |
This will execute thePHPUnit
as:
phpunit [...infection options] --verbose --filter=just/unit/tests |
Please note that if you choose to use
--configuration
,--filter
, or--testsuite
forPHPUnit
, these options will only be applied to theinitial test run. Each mutation has a customphpunit.xml
file generated for it which defines a single testsuite containing the tests which should be executed for that mutation. Applying--filter
or--testsuite
would not make sense in this context as the tests have already been filtered down.
--coverage
Path to the existing coverage reports.
When you use Continuous Integration for your project, probably you are already generating code coverage metrics and runPHPUnit
withXdebug
/phpdbg
enabled. Then, you run Infection for mutation testing, which in its turn, generates Code Coverage again for internal needs. This dramatically increases the build time because running your tests with debuggertwice requires too much time.
With this option it’s possible to reuse already generated coverage in Infection.
ForPHPUnit
andCodeception
:
xml
andjunit
reports to workbuild/coverage
path is provided, it should containcoverage-xml
folder andjunit.xml
filebuild/coverage/coverage-xml/*
build/coverage/junit.xml
ForPhpSpec
:
xml
report to workbuild/coverage
path is provided, it should containphpspec-coverage-xml
folderExample:
# collect coverage |
--git-diff-filter
Allows filtering files to mutate by usinggit diff
with--diff-filter
option. Sensible values are:AM
- added and modified files.A
- only added files.
Best to be used during pull request builds on CI, e.g. with GitHub Actions, Travis CI and so on.
Usage:
# this is needed on GitHub Actions to fetch the base branch to make a diff |
This command will mutate only those files that were added in the Pull Request. The diff is done between the current branch and a common ancestor of it and the base branch. If there is no common ancestor available, perhaps because your CI server used a shallow checkout, or you have unrelated branches, infection will use a direct diff between branches as a fallback.
It’s possible to configure the base branch, see
--git-diff-base
option
It’s possible to mutate only touchedlines, see
--git-diff-lines
option
--git-diff-base
Supposed to be used only with--git-diff-filter
option. Configures the base branch forgit diff
command.
Usage:
# this is needed on GitHub Actions to fetch the base branch to make a diff |
--git-diff-lines
Allows mutating only touchedlines of code. Under the hood, this option mutates only added and changed files, comparing your current branch withmaster
branch by default.
Base branch can be changed by using--git-diff-base=main
option. In this case, your current branch will be compared withmain
branch.
Useful to check how your changes impacts MSI in a feature branch. Useful for those who do not want / can’t write tests for the whole touched legacy file, but wants to cover their own changes (only modified lines).
Can significantly improve performance since fewer Mutants are generated in comparison to using--git-diff-filter=AM
or mutating all files.
--map-source-class-to-test
Meant to be used together with
--git-diff-lines
/--git-diff-filter
/--filter
This option can dramatically decrease the time needed for “Initial Tests Run” stage.
If project hasN
tests files and we run Infection with, for example,infection --git-diff-lines
and only 1 fileFoo.php
is updated/added in a Pull Request - it doesn’t make sense to run all theN
tests to generate code coverage if we know that only 1 file ofN
covers the source code file -FooTest.php
.
In practice,PHPUnit
even has different methods that help define which test file covers which class:
requireCoverageMetadata
configuration attribute#[CoversClass(...)]
attributeIn the example above, Infection would run onlyFooTest.php
to generate coverage forFoo.php
.
Without this option, Infection will attempt to runall the project’s tests, as it doesn’t know which tests coverFoo.php
.
Currently,--map-source-class-to-test
supports the only one strategy of mapping source class to test file: by adding*Test
postfix to a file name. If source class is namedFoo
, Infection will try to runFooTest
.
Under the hood, it builds a regex for--filter
option:--filter='FooTest|BarTest'
.
--id
Available in Infection 0.30.0+
Run only one Mutant by its ID. Can be used multiple times. If source code is changed, this value can be invalidated. Pass all previous options with this one.
Example of usage: you completed a feature and wrote tests, then you run
infection --git-diff-lines |
to get all mutations for the new and changed lines. But if there are too many mutations, it can be more convenient to focus on just 1 mutant at a time.
Imagine you want to work on this Mutant:
11) src/SourceClass.php:9 [M] Minus [ID] 6fa7eadad5b9fd1a72e4d80c83a61cc3 |
So you copy6fa7eadad5b9fd1a72e4d80c83a61cc3
value and run the same command as previously, just adding--id=6fa7eadad5b9fd1a72e4d80c83a61cc3
:
infection --git-diff-lines --id=6fa7eadad5b9fd1a72e4d80c83a61cc3 |
With this, Infection will only produce one mutant, and you can update your tests and re-run this command to check if it’s killed or still not.
--logger-github
Supposed to be used only with GitHub Actions. This logger prints GitHub Annotation warnings for escaped Mutants right in the Pull Request.
Use--logger-github=true
to force-enable or--logger-github=false
to force-disable it.
Note that the GitHub Actions environment is automatically detected and this switch isn’t actually necessary when executed there.
Usage:
# this is needed on GitHub Actions to fetch the base branch to make a diff |
Here isa real example how Infection uses it itself.
Note: Infection automatically detects
GITHUB_WORKSPACE
environment variable for report linking.
--logger-gitlab
This option is used to provide a path to the generated GitLab (Code Climate) Code Quality Report:
infection.phar --logger-gitlab='gitlab-coverage.json' |
After Infection completes its job, thegitlab-coverage.json
file will be generated. This file can than be included as acodequality
report artifact.
Takes precedence overlogger.gitlab
setting insideinfection.json5
file. If you want to always generate the GitLab Coverage report it’s better to configure it insideinfection.json5
, seehere.
Seethis sample repository as an example of how to configure Code Quality with Infection
This is how it works on PR main page:
This is how it works on diff view:
Note that “See findings in merge request diff view” isnot available on free tier
Note: Infection automatically detects
CI_PROJECT_DIR
environment variable for report linking.
--logger-project-root-directory
While generating GitHub and GitLab reports, Infection need to replace some links to their correct path according to your
repository. To do so, it will auto-detectGITHUB_WORKSPACE
GitHub environment variable, andCI_PROJECT_DIR
GitLab
environment variable as project root directory.
If this auto-detection does not fit your needs (for instance, while using custom Docker image and custom project path in
GitLab CI), you can customize the path to replace using--logger-project-root-directory
option:
infection.phar --logger-project-root-directory='/custom/project/root/directory/path' |
Note: if
GITHUB_WORKSPACE
andCI_PROJECT_DIR
cannot be detected, and--logger-project-root-directory
option is
not set, Infection will try to retrieve the project root directory usinggit rev-parse --show-toplevel
.
--logger-html
This option is used to provide a path to the generated HTML Report:
infection.phar --logger-html='mutation-report.html' |
After Infection completes its job, themutation-report.html
file will be generated with HTML report (example).
Takes precedence overlogger.html
setting insideinfection.json5
file. If you want to always generate HTML report, it’s better to configure it insideinfection.json5
, seehere.
If you want to store HTML report in the cloud (useful for OSS projects), seeStryker Dashboard integration
--skip-initial-tests
If you have already run the test suite to ensure it is passing, and you are providing coverage using--coverage
then you can use this option to increase performance by not running the entire test suite again.
Note that it is extremely important that you ensure the test suite is passing when using this option, otherwise test failures would appear like caught mutations and those mutations may be reported incorrectly.
--only-covered
Run the mutation testing only for covered by tests files.
--only-covering-test-cases
Execute only those test cases that cover mutated line, not the whole test file with covering test cases. Can dramatically speed up Mutation Testing for slow test suites, like functional or integration.
ForPHPUnit
it uses--filter
option under the hood. This option is not applicable for other test frameworks.
Read more about the problem and solution inthis blog post
--show-mutations
or-s
Limits how many colorized diffs of mutated files are shown to the console. 20 mutated diffs are shown by default.
infection --show-mutations=0# don't show any diffs |
Please note that all mutations can be logged to files as well, if enabled. See
logs
inusage section.
--configuration
or-c
If you want to use custom configuration file path or name, use this option for it.
--min-msi
This is a minimum threshold of Mutation Score Indicator (MSI) in percentage. Can be used with CI server to automatically control tests quality.
Read more aboutusing Infection in CI server
--min-covered-msi
This is a minimum threshold of Covered Code Mutation Score Indicator (MSI) in percentage. Can be used with CI server to automatically control tests quality.
--mutators
This is a comma separated option to specify a particular set of mutators orprofiles that need to be executed. Example:
infection --mutators=PublicVisibility,Plus,Decrement,@number |
Seehere to find all mutator names.
--no-progress
This option has two effects:
Disabling progress bars removes the following lines from output on Continuous Integration servers:
Processingsource code files: 0/5678 |
Progress bar display will be automatically disabled with or without this option when eitherCI
orCONTINUOUS_INTEGRATION
environment variables are set to"true"
.
For example, there is no need to enable this option manually on Travis CI just to hide progress bars.
--noop
Use noop mutators that do not change the AST. For debugging purposes.
Read about debugging issues with
--noop
optionhere
--force-progress
Outputs progress bars and mutation count during progress even if a CI is detected.
This option also reverts optimizations made by--no-progress
option, readhere.
--formatter
This is a name of console output formatter. Possible values are:dot
,progress
. Default isdot
formatter.
--log-verbosity
The verbosity of the log file,all
- this mode will add “Killed mutants” into log file and add additional information,default
- normal mode will skip “Killed mutants” section in the log file,none
- which will disable logging to files.
infection --log-verbosity=all |
--initial-tests-php-options
Run Initial Tests process with additional php options. For example with-d zend_extension=xdebug.so
which will runXdebug
only for code coverage.
May be useful for cases whenXdebug
is not enabled globally. Also it’s useful from performance point of view.infection --initial-tests-php-options="-d zend_extension=xdebug.so"
--ignore-msi-with-no-mutations
Ignore MSI violations when no mutations are generated. This will force Infection to return a zero exit code even when the required MSI is not reached.
--debug
Run Infection in a debug mode. With this option Infection will not erasetmpDir
and this might be useful to run particular unit test with a mutated code for example.
Also, this option will add test framework’s output to log file so you can analyze by which test particular Mutant was killed, and additional information about executed command lines will be added.