What does Pest's --type-coverage option measure, and how does it differ from running Pest with --coverage?

## What type coverage measures **Type coverage** is the percentage of places in your code that could carry a type declaration and actually do: function and method parameters, return types, and properties. In Pest it comes from a separate plugin: ```bash composer require pestphp/pest-plugin-type-coverage --dev ./vendor/bin/pest --type-coverage ``` The report lists each file with its percentage and, for files below 100 percent, a marker per missing declaration. The docs define two of them: `rt31` means the **return type** of the function on line 31 is missing, and `pa31` means a **parameter type** on line 31 is missing. A total percentage closes the report. ## How it differs from code coverage | | `--type-coverage` | `--coverage` | |---|---|---| | Question answered | how much of the code declares types | how much of the code the tests executed | | Runs the tests | no | yes | | Needs Xdebug or PCOV | no | yes | | Plugin | `pestphp/pest-plugin-type-coverage` | built into Pest, on PHPUnit's coverage | | Gate | `--type-coverage --min=100` | `--coverage --min=80` | - Type coverage is a **static** check. It looks at declarations in the source, so it is fast and works on code that has no tests at all. - Code coverage is **dynamic**. It depends on which tests exist and what they exercise, and it says nothing about types. - The two are independent: a fully typed class can have zero tests, and a heavily tested class can be untyped. ## What it does not tell you 1. It does not check that a declared type is **correct** or consistent with how the value is used. That is the job of a static analyser such as PHPStan. 2. It does not say whether a type is **precise**: the useful reading is "was a type written", not "is it the narrowest type that fits". 3. It is not a substitute for `declare(strict_types=1)`: a declared `int` parameter can still receive a coercible string from a caller that runs in coercive mode. ## Using it as a gate - Enforce it in CI with `./vendor/bin/pest --type-coverage --min=100` on new projects, or with the current percentage on an older codebase, raised over time. - `--compact` limits the report to files below 100 percent, which is what you read during a cleanup. - `--type-coverage-json=report.json` writes the result to a file for tooling. - A deliberate gap, for example a framework property whose parent class declares no type, is exempted with a trailing `// @pest-ignore-type` comment on that line. ## Reading a report on a legacy codebase On a codebase written before scalar type declarations were common, the first report is long. A workable reading order: - Start with `--compact` so only files below 100 percent appear. - Fix **return types** first. They are cheap to add, and a declared return type immediately tells callers and static analysers what comes back. - Then fix **parameter types** on public methods, where a wrong value from a caller does the most damage. - Leave properties inherited from framework base classes for last; they are the usual candidates for `@pest-ignore-type`. - Record the total after each pass and raise `--min` to it, so the number can only go up. ## Where it fits in a toolchain A typical PHP 8.5 pipeline pairs three independent signals: - **Type coverage** to make sure declarations are written at all. - **Static analysis** to check the declared and inferred types against each other. - **Tests with code coverage** to check behaviour. Type coverage is the cheapest of the three and the quickest to explain to a team adopting typed PHP, which is why it is often the first gate introduced on a legacy codebase that is being typed file by file.