https://github.com/roave/infection-static-analysis-plugin
:white_check_mark: :dragon_face: Static analysis on top of mutation testing - prevents escaped mutants from being invalid according to static analysis
https://github.com/roave/infection-static-analysis-plugin
Last synced: 6 months ago
JSON representation
:white_check_mark: :dragon_face: Static analysis on top of mutation testing - prevents escaped mutants from being invalid according to static analysis
- Host: GitHub
- URL: https://github.com/roave/infection-static-analysis-plugin
- Owner: Roave
- License: mit
- Created: 2020-09-02T16:47:15.000Z (almost 6 years ago)
- Default Branch: 1.38.x
- Last Pushed: 2025-05-12T07:53:38.000Z (about 1 year ago)
- Last Synced: 2025-05-13T16:53:31.550Z (about 1 year ago)
- Language: PHP
- Homepage:
- Size: 1.38 MB
- Stars: 124
- Watchers: 7
- Forks: 19
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Infection Static Analysis Plugin
This plugin is designed to run static analysis on top of [`infection/infection`](https://github.com/infection/infection)
test runs in order to discover if [escaped mutants](https://en.wikipedia.org/wiki/Mutation_testing)
are valid mutations, or if they do not respect the type signature of your
program. If the mutation would result in a type error, it is "killed".
TL;DR:
- This will improve your mutation score, since mutations which result in
type errors become killed.
- This is very hacky, and replaces `vendor/bin/infection` essentially.
Please read the `Stability` section below first for details.
- This is currently much slower than running infection by itself.
There are ideas/suggestions to improve this in the future.
## Usage
The current design of this tool requires you to run `vendor/bin/roave-infection-static-analysis-plugin`
instead of running `vendor/bin/infection`:
```sh
composer require --dev roave/infection-static-analysis-plugin
vendor/bin/roave-infection-static-analysis-plugin
```
### Configuration
The `roave-infection-static-analysis-plugin` binary accepts all of `infection` flags and arguments, and an additional `--psalm-config` argument.
Using `--psalm-config`, you can specify the psalm configuration file to use when analysing the generated mutations:
```sh
vendor/bin/roave-infection-static-analysis-plugin --psalm-config config/psalm.xml
```
## Background
If you come from a statically typed language with AoT compilers, you may be
confused about the scope of this project, but in the PHP ecosystem, producing
runnable code that does not respect the type system is very easy, and mutation
testing tools do this all the time.
Take for example following snippet:
```php
/**
* @template T
* @param array $values
* @return list
*/
function makeAList(array $values): array
{
return array_values($values);
}
```
Given a valid test as follows:
```php
function test_makes_a_list(): void
{
$list = makeAList(['a' => 'b', 'c' => 'd']);
assert(count($list) === 2);
assert(in_array('b', $list, true));
assert(in_array('d', $list, true));
}
```
The mutation testing framework will produce following mutation, since we
failed to verify the output in a more precise way:
```diff
/**
* @template T
* @param array $values
* @return list
*/
function makeAList(array $values): array
{
- return array_values($values);
+ return $values;
}
```
The code above is valid PHP, but not valid according to our type declarations.
While we can indeed write a test for this, such test would probably be
unnecessary, as existing type checkers can detect that our actual return value is
no longer a `list`, but a map of `array`, which is in conflict
with what we declared.
This plugin detects such mutations, and prevents them from making you write
unnecessary tests, leveraging the full power of existing PHP type checkers
such as [phpstan](https://github.com/phpstan/phpstan) and [psalm](https://github.com/vimeo/psalm).
## Stability
Since [`infection/infection`](https://github.com/infection/infection) is not yet
designed to support plugins, this tool uses a very aggressive approach to bootstrap
itself, and relies on internal details of the underlying runner.
To prevent compatibility issues, it therefore always pins to a very specific version
of `infection/infection`, so please be patient when you wish to use the latest and
greatest version of `infection/infection`, as we may still be catching up to it.
Eventually, we will contribute patches to `infection/infection` so that there is a
proper way to design and use plugins, without the need for dirty hacks.
## PHPStan? Psalm? Where's my favourite static analysis tool?
Our initial scope of work for `1.0.x` is to provide `vimeo/psalm` support as a start,
while other static analysers will be included at a later point in time.