Testing for backend upgrades, refactors of code, and overall any new feature that cannot be “touched or seen” regularly feels very challenging for most WordPress developers.

Sometimes unit-testing can do part of the heavy lifting, especially when having expertise in TDD, as a great deliverable could be provided.

The problem with unit-tests is that sometimes they are completely biased to our thoughts and ideas. It’s extremely difficult to think outside the box (especially when you are absorbed into a development that takes most of our attention), and this could potentially leave behind some scenarios you have not considered testing.

Adding up, when finally code is delivered, including sometimes those unit-tests, the rest of the people who are going to review it will not have the full understanding of the problem, with all the nuances, edge cases, or scenarios that could pop out of your resulting code.

As a WordPress developer, you have to consider that other reviewers in the team could range from a coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. committer with 15 years of code to a brand-new testing contributor out of a WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. willing to start lending a hand. And getting them to review if the unit tests are right, or even to review the code and add new unit-tests for more edge cases is, in numerous instances, even for the most experienced reviewers, a hard task and something to avoid.

Here is why a Testing Use-Case could become really handy for these scenarios, a paradigm of testing that could be easily learned and applied and would help further progress many reports with patches that have been stuck for ages.

Let’s dive into the Testing Use-Case

Ideally, from a Testing perspective, the best code refactor, patch, upgrade, or feature is the one that actually addresses a problem you are already having.

For example, as a patch creator, you can find any of these scenarios:

• Have a theme or a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party that is missing this functionality.
• Find a deprecation notice in the logs.
• Find an error in code that requires not only a quick fix but a whole revamp of the code.
• Have a real-life requirement by any real stakeholder in our business or life in general, and we can express the entire demand down to the last detail.

These are all examples of Testing-Use Cases

But what happens if you don’t have any of those? What if you are a code freestyler that likes to sort things before they actually happen? Or maybe you have been developing somewhere else and out of sudden you think about an alternative fix that could be improved, despite not really having a real-life example to showcase our idea?

Here is where building a Testing Use-Case becomes handy.

Ideas to Build Your Testing Use-Case

Not it’s time to put some examples of the most common issues that were found lately and how implementing a Testing Use-Cases could help to move forward the patch and overall any report that could potentially get stuck.

The Hook

One of the most common reports with troubles to be tested, and many end up in the “pending box” because of new HooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.. Most hooks come out of a specific need from a dev, but for some reason, many devs fear that explaining their use-case could feel “agendistic” and not usable by the majority. Also, it’s very common that there is almost always a workaround using outlandish PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php. functions that bypass many standards and are not ideal by any means to achieve the same result as what a hook could provide us. So it’s very common that Hooks fade into oblivion.

Ideally, the #1 Testing Use-Case is, by far, explaining your business scenario without fearing any critique. Say you have a client that is paying you a big ticket, and you need that damned hook to get that attribute to do that selective filtering for the membership plugin you are building. This is totally fine if you need this hook for a commercial case. You can think that your case is unique and explanation will reveal it, but if you feel the need for this hook and there is no other straightforward way to achieve the same result without workarounds and hacks, it should be enough. Explaining the alternative solutions that were investigated will support your case. You may think that adding a hook to code is a simple thing, but when it is added, there will be no way to remove it or make changes that will break backwards compatibility, so the hook should be in the right place when it is definitely needed and have the right name and parameters. In addition, it should be documented in the code and in the Field guide and other documentation later. That one line of code requires a lot of support to happen.

Now to create the Testing Use-Case we have two options:

1. You can actually provide some of the code of that plugin you are building that showcases the feature where the new hook you are willing to implement is going to be applied.
2. If you would rather not showcase your code for copyright dilemmas with your client (funny in a GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples. environment, but we all know that this still happens), reproduce a minimal MVPMinimum Viable Product "A minimum viable product (MVP) is a product with just enough features to satisfy early customers, and to provide feedback for future product development." - WikiPedia version of what you are willing to achieve, mocking some data or building a hydration function to fill whatever content is required to display the issue, and creating a very simple plugin that delivers that and uses that hook and executes successfully.

Choose whatever you prefer. But be aware that what is actually problematic is making your way through it without explaining much, without any testing at all, and despite the hook being super simple, straightforward, and unlikely to be problematic at all, this always leads to distrust and leans towards the forgotten zone where it will never be reviewed and integrated into the core. It’s always better to be transparent and clear of what needs to be done in a GPL environment, and in the worst case, discuss the feasibility and maybe a better clean code alternative if possible.

Do you want to review a Hook Testing Use-Case plugin example?
Check this one: https://github.com/SirLouen/testing-41757/
Used in this report: https://core.trac.wordpress.org/ticket/41757

Code Refactors

There is a rule in the WordPress community: never refactor if you don’t have a good reason for this. This is mainly because it takes many resources to test and debug issues coming from the refactor, and most code reviewers are busy enough just with the regular bugs to be fixed and pending improvements to be implemented to invest time in this protocol, so refactoring could be important but not as critical as other topics.

But very occasionally, there could a good reason for a code refactor, for example, an upcoming PHP deprecation.

In these cases, the best scenario, unfortunately, is waiting for the deprecation notice reports to appear, and start fixing from there, one by one. Bear in mind that deprecations take ages to be converted into unsupported features; hence, waiting is probably the best and easiest bet.

But what if you are a restless soul and like to have everything bleeding edge updated?

The following steps are recommended after the patch has been built (or before):

1. First, identify which core functions you have modified. If there are unit-tests already, you can edit them to cover your new code; otherwise you could always build them later.
2. Consider that the current function was working as-is with the current premise. You should start building a very simple plugin that uses this old premise with all the functions you modified, test them, and display the results.
3. After that, you will think about your new premise and again, in the same plugin, apply it once more to all the functions you modified.

Remember that both, before and after, you should be passing the test with the new premises. Yes, with a unit-test you are doing this. But, as it was commented in the beginning, unit-tests can become very convoluted (because they are not generally designed for simplicity, but for heavy-lifting the future-proof of the whole system). On the other side, a plugin can be elegant, simple, and easy to showcase all we want to test. Any coder, regardless of his coding level, will probably be able to inspect it, understand it, and maybe think in more edge cases based on what he sees. It’s a new paradigm of simplicity and support for your peer reviewers. And perhaps the difference between a lost into oblivion patch or a patch that will be reviewed comfortably and steadily. As a rule of thumb, it’s easier to port a test use-case plugin to unit-tests than the other way around.

Do you want to review a Hook Testing Use-Case plugin example?
Check this one: https://github.com/SirLouen/test-block-attributes/
Used in this report: https://core.trac.wordpress.org/ticket/61154

Back-End Enhancements and New Features

This categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. is like a hodgepodge because here you could find very different examples, and it’s going to be very difficult to make a general assumption on how to always proceed. But some rule of thumb could apply here, similar to the two previous sections:

1. If you have a real use case, a feature required by your client, or a snippet of code that can prove your enhancement, this will be sufficient. You simply need something more than unit-tests, that again, can be biased. Something that can be replicated in the WP front-end or admin panel and be tested with real data, not just with the mock samples from the unit-testing framework. Finding any of these is going to be the ideal scenario for most cases.
2. If, for some reason in life, it happens that you have come to this enhancement almost out of nowhere, while reviewing some other thing or for whatever other reason, a plugin that proves the new feature is clearly needed. The steps are very similar to the previous section, “Code Refactors” but adapting to the potential new functions we have developed.

Do you want to review an Enhancement Testing Use-Case plugin example?
Check this one: https://github.com/SirLouen/testing-template-loading/
Used in this report: https://core.trac.wordpress.org/ticket/58905

Performance Upgrades

Finally, the crown’s jewel of backend patches. In fact, most devs in the performance team are relatively familiar with this; hence, not much to be explained here for them. But just some general ideas for those who are still not very familiar with this.

A performance upgrade must factually test that there is a performance upgrade. It’s not enough with “before this it took 2 seconds and not it takes 1.” Real data that could be deployedDeploy Launching code from a local development environment to the production web server, so that it's available to visitors. in multiple computers, environments, etc. is required, and really show that there is a real performance improvement.

For this, you will need to write a plugin that does, at minimal, these two things:

1. A hydration system to generate X number of whatever we need to test. If a WP_Query with 10K posts should be tested, then a hydration plugin that actually creates those 10K dummy posts for us is required. If there is a plugin out there that works and does this, refer to it. Don’t suppose we all know it.
2. A plugin that, actually, makes use of those 10K posts and tests this performance improvement with functions like microtime and get_num_queries (including SAVEQUERIES)

This could feel pretty obvious, but these two parts are essential to building a Testing Use-Case for performance upgrades. And it’s still surprising the massive number of times that they cannot be found in the Performance tickets. Simply don’t expect anyone to write them for you. Take the lead and send it the whole pack by yourself: the patch + the plugin with performance tests. Otherwise, there is a big risk that the ticket ends forever in the forgotten box of unreleased patches.

Do you want to review a Performance Upgrade Use-Case plugin example?
Check this one: https://github.com/SirLouen/wp-query-benchmarking-v2
Used in this report: https://core.trac.wordpress.org/ticket/18836

Future Improvements

More examples in the future will be provided as they become available because some categories, like the Back-End Enhancements and New Features, certainly need them.

If you have any comments, any questions, or any ideas to improve this guide on how to build your Testing Use-Case, please comment.

Props to @oglekler and @audrasjb for helping review this article and offering feedback

Changelog

08/05/2025 – Initial Article.

#good-practices, #handbook, #use-case