feat: Add references method for two-way test-source linking

[mertasan]

What:

• Bug Fix
• New Feature

Description:

In this pull request, I am adding a reference method to address an adaptation issue we encountered during our transition from PHPUnit to PEST. While using PHPUnit, we heavily rely on the @see annotation to provide direct references from test methods to source code methods.

This makes navigation in IDEs like PHPStorm smoother and improves the development process. However, when we transition to PEST, this functionality is lost.

To solve this, the reference() method comes into play. This method restores the lost functionality in PEST, enabling direct references between test callbacks and the source code methods. IDEs like PHPStorm will be able to navigate from test functions directly to the source code methods, similar to how it worked with @see in PHPUnit. Additionally, the method is lightweight and doesn't introduce any performance overhead.

---

If we had just added a @see annotation to the test, we’d only be able to navigate to the source code. The real goal here is two-way navigation: allowing us to jump from the test to the source code and also back from the source code to the test.

Benefits of this Method:

Improved IDE Support:

With the reference method, developers using PHPStorm will be able to maintain the connection between test functions and the source code methods. This makes it easier to navigate between tests and code, just like when using @see in PHPUnit.

Easier Migration:

One of the key challenges for companies migrating from PHPUnit to PEST is the loss of reference functionality provided by @see. This reference method helps alleviate this issue and makes the transition smoother while keeping the tests readable and maintainable.

No Performance Impact:

Since the method is empty, it has no performance impact on PEST. It simply serves as a way to provide IDE integration and navigation without adding any overhead.

Broad Applicability:

We believe this solution is not only beneficial to our company but also for many other teams that rely on strong references between tests and the source code methods. Any company using @see annotations in their tests will find this method useful in PEST.

With the recent release of PEST PHP version 3, this method provides a lightweight solution that enhances IDE integration without imposing any additional burden or disrupting the framework’s structure. For developers using powerful IDEs like PHPStorm, this feature will be highly beneficial, offering improved functionality without adding unnecessary overhead to PEST.

Note: This method could be made even more functional in the future. It might be a good idea to highlight the test's source in console output, providing further clarity during debugging.

pestphp_reference.mov

[cengsemihsahin]

Usefully, perfect!!

[faytekin]

Smart solution, and definitely a needed one. Thanks for addressing this.

[dshafik]

@mertasan why not use the covers() method? It actually ensures that you aren't accidentally marking coverage for code you aren't testing (which is valuable functionality) and provides the navigability you want. With #1239 it works for methods too…(if @nunomaduro accepts it)

[mertasan]

@dshafik thank you for your suggestion. however, I believe that methods should be used according to their intended purpose.

the covers() method is primarily designed for code coverage, ensuring tests mark specific parts of the code they cover. the reference() method, on the other hand, is focused on navigation between test cases and source methods. using covers() for navigation might confuse its role and lead to unintended usage. keeping these functionalities distinct ensures each method remains clear and purposeful.

[nozdogan]

Thanks for this PR @mertasan . In complex projects, identifying the method a particular test is targeting can become increasingly difficult. So this PR offers a great solution to help us overcome this difficulty.

[HakanKorkz]

A very super approach to a topic that is definitely needed, thank you very much.

[faytekin]

I just came across this PR and wanted to express my support for this feature! We’ve been in the same situation, where we heavily rely on the ability to navigate between tests and source code, especially as we transition our suite to PEST. Losing that seamless connection has slowed us down quite a bit, so the reference() method would truly be a game-changer for our workflow as well.

This feature would be a great addition for anyone moving from PHPUnit to PEST and using powerful IDEs like PHPStorm. It would make the migration smoother for many teams, which I think would benefit PEST’s growing community.

Would it be possible to get some feedback or updates on this PR? Thanks so much for considering, and thank you to the contributor for the work done here!

@nunomaduro