Documentation
- Introduction
- Installation
- Usage
- Command Line Options
- Mutators
- Profiles
- Using with CI
- Mutation Badge
- How-to Guides
- Caveats
- Debugging Issues
- Infection Playground
- GitHub Sponsors ♥️
Miscellaneous
- Compare with competitors
Posts
- 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
Command Line Options
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 will dramatically 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.
On most platforms where GNU coreutils are available, which includes all variants of Linux, there is nproc
command that returns the number of processors available. It can be used as such to let Infection run at the full speed:
# on Linux |
--test-framework
This is a name of the Test framework to use. Currently Infection supports PHPUnit
, PhpSpec
and Codeception
.
If you are using infection/infection
Composer package, only PHPUnit
is installed by default. Other test framework adapter 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 options allows to pass additional options to the test framework. Example for PHPUnit
:
infection.phar --test-framework-options="--verbose --filter=just/unit/tests" |
This will execute the phpunit as:
phpunit [...infection options] --verbose --filter=just/unit/tests |
Please note that if you choose to use
--configuration
,--filter
, or--testsuite
for PHPUnit, these options will only be applied to the initial 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 run PHPUnit with XDebug
/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 debugger twice requires too much time.
With this option it’s possible to reuse already generated coverage in Infection.
For PHPUnit
and Codeception
:
- Infection requires both the
xml
andjunit
reports to work - If
build/coverage
path is provided, it should containcoverage-xml
folder andjunit.xml
filebuild/coverage/coverage-xml/*
build/coverage/junit.xml
For PhpSpec
:
- Infection requires the
xml
report to work - If
build/coverage
path is provided, it should containphpspec-coverage-xml
folder
Example:
# collect coverage |
--git-diff-filter
Allows filtering files to mutate by using git 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 the base branch.
It’s possible to configure the base branch, see
--git-diff-base
option
--git-diff-base
Supposed to be used only with --git-diff-filter
option. Configures the base branch for git diff
command.
Usage:
# this is needed on GitHub Actions to fetch the base branch to make a diff |
--logger-github
Supposed to be used only with GitHub Actions. This logger prints GitHub Annotation warnings for escaped Mutants right in the Pull Request:
Usage:
# this is needed on GitHub Actions to fetch the base branch to make a diff |
Here is a real example how Infection uses it itself.
--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.
--show-mutations
or -s
Show colorized diffs of mutated files to the console.
Please note that all mutations are logged to the
infection.log
file as well.
--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 about using 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 or profiles that need to be executed. Example:
infection --mutators=PublicVisibility,Plus,Decrement,@number |
See here to find all mutator names.
--no-progress
This option has two effects:
- It disables intermediate buffering of mutations used to count them. This causes progress bars to not have a total number of mutations displayed, while also reducing memory usage and speeding up the entire process. It is beneficial during CI, and for larger projects.
- It disables dynamic progress bars output to reduce the amount of generated text output.
Disabling progress bars removes the following lines from output on Continuous Integration servers:
Processing source code files: 0/5678 |
Progress bar display will be automatically disabled with or without this option when either CI
or CONTINUOUS_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
option here
--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, read here.
--formatter
This is a name of console output formatter. Possible values are: dot
, progress
. Default is dot
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 run Xebug only for code coverage.
May be useful for cases when XDebug 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 erase tmpDir
and this might be useful to run particular unit test with a mutated code for example.