From 5241b71ee4947d9a823c17e5eb4143b307756c46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9o=20FIDRY?= Date: Mon, 9 Nov 2026 21:17:52 +0100 Subject: [PATCH] add doc --- guide/arguments.md | 273 +++++++++++++++++++++++++++++++++- guide/command-line-options.md | 2 +- 2 files changed, 267 insertions(+), 8 deletions(-) diff --git a/guide/arguments.md b/guide/arguments.md index 5907801..01f3715 100644 --- a/guide/arguments.md +++ b/guide/arguments.md @@ -7,7 +7,11 @@ is_new: true # Command Line Arguments -Starting from version 0.34, Infection supports positional arguments to scope Mutation Analysis to source paths, tests paths or both. +Starting from version 0.34, Infection supports positional source and test paths to scope Mutation Analysis. +If you're working on a particular class or method, you can also pass its name to `infection` without looking up its file path or changing `infection.json5`. +These source symbol selectors can be combined with source and test paths. + +When an argument points to a readable file or directory, Infection treats it as a path. Files and directories inside the configured `source.directories` are source paths; those outside are test paths. ```shell infection src/Domain @@ -55,7 +59,7 @@ infection 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. -> You can check the result of the filter applied by using `infection config:list-sources ` +> `infection config:list-sources ` shows which files match a path filter. It lists whole files, so symbol selectors won't narrow what appears in this list. ---- @@ -95,17 +99,269 @@ infection tests/Domain/UserRepositoryTest.php ## Partial name matching -If you don't want to provide full paths, Infection also accepts bare filenames (with or without the `.php` extension), matching any file whose name contains the given string: +You can also pass a filename such as `Mailer.php` or `Plus_.php`. Infection looks for source files whose paths contain that string: ```shell -infection Mailer infection Mailer.php -infection Plus_ +infection Plus_.php +``` + +A bare name such as `Mailer` has a more specific meaning when it doesn't point to a readable file or directory: it selects classes named `Mailer` in files whose paths also contain `Mailer`. +For example, `infection Mailer` can mutate `App\Mailer` in `src/Service/Mailer.php`. It leaves out `App\MailerHelper` in `src/Service/MailerHelper.php`, because the class name differs and `App\Mailer` in `src/Service/Transport.php`, because the path doesn't match. + +## Source symbol selectors + +Available in Infection 0.35.11+ + +For a closer look at one part of your code, a selector can name a class, a namespace or a method. Adding `::32` narrows it to code spanning line 32 of the source file: + +| Selector | Mutation scope | +| --- | --- | +| `Mailer` | Classes named `Mailer` in files whose paths contain `Mailer` | +| `Mailer::send` | `send()` methods in classes named `Mailer`, across configured source files | +| `Mailer::32` | Syntax nodes spanning source line 32 in classes named `Mailer` | +| `Mailer::send::32` | Syntax nodes spanning line 32 within those `send()` methods | +| `'App\Service\Mailer'` | The class `App\Service\Mailer` | +| `'App\Service\Mailer::send'` | The `send()` method in that qualified class | +| `'App\Service\'` | Classes under `App\Service`, including nested namespaces | +| `'\Mailer'` | Only the global class `Mailer` | + +### Selecting classes and methods + +Suppose your configured `src/` directory contains these files. Each `Mailer` class has `send()` and `preview()` methods; `MailerHelper` also has a `send()` method. + +```text +src/ + Service/ + Mailer.php # App\Service\Mailer + MailerHelper.php # App\Service\MailerHelper + Transport.php # App\Service\Delivery\Mailer + Legacy/ + Mailer.php # App\Legacy\Mailer + Global.php # Mailer (global namespace) +``` + +If you're working on `send()`, its short name is enough to select that method in all four `Mailer` classes: + +```shell +infection Mailer::send +``` + +The `preview()` methods and `MailerHelper::send()` are left out. Class and method names match exactly, ignoring case, so `mailer::SEND` gives the same result. + +When you only want the service class, its qualified name makes that distinction: + +```shell +infection 'App\Service\Mailer::send' +``` + +This selects only `send()` in `src/Service/Mailer.php`. Without `::send`, the whole `App\Service\Mailer` class is selected, including `preview()`. +The quotes keep the shell from interpreting the backslashes. + +The same source tree also illustrates how a class name, a filename and a namespace can select different code: + +| Command | Selected code in this example | +| --- | --- | +| `infection Mailer` | The `Mailer` classes in `Service/Mailer.php` and `Legacy/Mailer.php`; the other two `Mailer` classes have no `Mailer` in their paths | +| `infection Mailer.php` | All eligible code in `Service/Mailer.php` and `Legacy/Mailer.php`, regardless of class name | +| `infection src/Service/` | All eligible code in the three files under `Service/` | +| `infection 'App\Service\'` | The `App\Service\Mailer`, `App\Service\MailerHelper` and `App\Service\Delivery\Mailer` classes | +| `infection '\Mailer'` | Only the global `Mailer` in `Global.php` | + +A namespace selector includes nested namespaces. For example: + +```shell +infection 'App\Service\' +``` + +This includes `App\Service\Delivery\Mailer` from `Transport.php`, even though its filename doesn't contain `Mailer`. Classes in `App\ServiceTools` or `Other\App\Service` would be outside this namespace prefix. + +Names in selectors are literal; glob wildcards and regular expressions aren't supported. A trailing backslash is the only form of prefix matching. +Infection still looks within your configured source directories and respects their exclusions. + +### When a name could mean a path or a class + +A name like `Differ` could refer to a directory, part of a filename or a class. If it doesn't point to a readable file or directory, Infection combines the path and class-name filters. This can be surprising when the names don't line up. + +For example, suppose your source tree looks like this and there's no readable file or directory named `Differ` at the location where the argument is resolved: + +```text +src/ + Differ/ + Differ.php # App\Differ\Differ + Helper.php # App\Differ\Helper + Other/ + ColorizedDiffer.php # Differ\ColorizedDiffer + Namespaced.php # App\Other\Differ + Global.php # Differ (global namespace) +``` + +With this command: + +```shell +infection Differ +``` + +The path filter finds `Differ.php`, `Helper.php` and `ColorizedDiffer.php`, since all three paths contain `Differ`. Within those files, only classes whose short name is exactly `Differ` are selected for mutation: + +| File | Selected for mutation | Why | +| --- | --- | --- | +| `src/Differ/Differ.php` | Yes | The path contains `Differ` and the class is named `Differ` | +| `src/Differ/Helper.php` | No | The class is named `Helper` | +| `src/Other/ColorizedDiffer.php` | No | The class is named `ColorizedDiffer` | +| `src/Other/Namespaced.php` | No | The path doesn't contain `Differ` | +| `src/Other/Global.php` | No | The path doesn't contain `Differ` | + +::: warning Behavior before Infection 0.35.11 +Before Infection 0.35.11, `infection Differ` only applied the path filter. In this example, `Helper.php` and `ColorizedDiffer.php` could also produce mutations even though their classes aren't named `Differ`. +::: + +Adding a slash or a backslash makes the intended scope explicit: + +| Command | Selected code in this example | +| --- | --- | +| `infection Differ/` | Both classes under `src/Differ/`, including `Helper` | +| `infection 'Differ\'` | `Differ\ColorizedDiffer` in `src/Other/ColorizedDiffer.php`; nested namespaces under `Differ` would also be included | +| `infection '\Differ'` | Only the global class `Differ` in `src/Other/Global.php` | + +Readable paths still take precedence. If the argument `Differ` resolves to a readable source directory, `infection Differ` selects that directory's files without adding a class-name filter. A qualified class name, such as `'App\Differ\Differ'`, can help when you meant the class instead. + +### Finding selector names + +If you're unsure which name to pass, `debug:list-symbols` shows the symbols Infection tracks in a PHP file. For the service `Mailer` above, the output would look like this: + +```console +$ infection debug:list-symbols src/Service/Mailer.php +App\Service\Mailer +App\Service\Mailer::send +App\Service\Mailer::preview +``` + +Each name can be copied into a selector: + +```shell +infection 'App\Service\Mailer::send' +``` + +The command lists names in declaration order, without executing the file or autoloading its declarations. It helps identify selectors; whether the selected code produces mutations still depends on coverage, exclusions and the enabled mutators. + +### Selecting a source line + +For a smaller change, a line selector can help focus the run. Consider this version of `src/Service/Mailer.php`: + +```php:line-numbers +Deprecated since Infection 0.34.0 -This option is deprecated. Use positional arguments instead: +This option is deprecated in favour of [positional arguments](/guide/arguments.html): ```shell infection src/Service/Mailer.php