[Question] About @return mixed in Pest global helpers (it() / test()) and static analysis tools

Hi,

First of all, thank you for Pest : it’s a cool testing framework and a pleasure to use.

I’m currently cleaning up one of my projects using the static analysis tool Mago (https://mago.carthage.software/
), and I’m running into an issue related to the return types of the Pest global helper functions.

When using datasets with it()->with(...), the analyzer reports:

error[mixed-method-access]: Attempting to access a method on a non-object type (mixed).

┌─ tests/MyTest.php
│
144 │ ╭ it(
145 │ │     'return total number of page views',
146 │ │     function (int $expectedValue, string $from, string $to) {
147 │ │ │       // …
·   │
153 │ │     },
154 │ │ )->with([
│ │    ^^^^ Cannot call method here
│ ╰─' This expression has type mixed

From what I understand, this happens because the PHPDoc for some Pest helper functions declares:

/**
 * @return Expectable|TestCall|TestCase|mixed
 */

while the actual PHP return type is more specific (for example TestCall for it()).

For reference, this is the relevant code in Pest:
https://github.com/pestphp/pest/blob/cf00e58b7d2741eb50a038b20e370c02561d6cfd/src/Functions.php#L141

My question is:

Is the mixed part of the PHPDoc return type still necessary?

It seems to contradict the actual return types and makes static analyzers treat the result as mixed, which then prevents method chaining like ->with() from being recognized safely.

Would it be possible (or desirable) to narrow the PHPDoc return types to match the real return values more closely? That would significantly improve compatibility with static analysis tools.

Thanks a lot for your time, and again for Pest

Best regards,

Read src/Functions.php around line 141 and compare the PHPDoc return types for it() and test() with their actual returns. Reproduce the Mago diagnostic with the dataset example; done means the helper chain is no longer inferred as mixed while the existing type checks remain valid.