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

[jfredon]

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:

pest/src/Functions.php

Line 141 in cf00e58

function test(?string $description = null, ?Closure $closure = null): HigherOrderTapProxy|TestCall

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,