Un test qui crée des entrées de cache dans un groupe personnalisé et qui ne les nettoie pas laisse un résidu invisible pour le test suivant. Ce résidu ne provoque pas toujours un échec immédiat : il fausse discrètement une assertion qui suppose un cache vide, parfois plusieurs tests plus loin.
Depuis WordPress 6.1, la fonction wp_cache_flush_group() permet de cibler un groupe de cache précis plutôt que de recourir systématiquement à un vidage complet. Voici comment l’utiliser pour garantir qu’un test d’intégration ne laisse rien derrière lui.
Pourquoi le cache objet pollue les tests
Le cache objet de WordPress fonctionne par groupes : options, posts, terms, ou tout groupe personnalisé déclaré par une extension via wp_cache_add() avec un troisième argument précisant le groupe. Sur l’environnement de test par défaut, ce cache reste en mémoire pour la durée du process PHP, ce qui veut dire qu’il survit d’un test à l’autre à l’intérieur d’une même exécution de la suite.
Avant WordPress 6.1, la seule fonction disponible pour repartir d’un cache propre était wp_cache_flush(), qui vide indistinctement tous les groupes. Appeler cette fonction après chaque test fonctionne, mais elle a un effet de bord : elle supprime aussi le cache que WordPress lui-même construit pendant l’exécution (options, métadonnées), ce qui peut ralentir la suite en forçant des requêtes SQL supplémentaires à chaque test suivant.
Cibler un seul groupe avec wp_cache_flush_group
La fonction wp_cache_flush_group( string|int $group ) vide uniquement les entrées appartenant au groupe passé en argument. Dans un test qui exerce une extension déclarant son propre groupe de cache, la méthode tearDown() peut se limiter à ce groupe :
class MonExtension_CacheTest extends WP_UnitTestCase
{
public function tearDown(): void
{
wp_cache_flush_group('mon_extension_stats');
parent::tearDown();
}
public function test_le_compteur_est_mis_en_cache(): void
{
wp_cache_set('compteur_vues', 12, 'mon_extension_stats');
$this->assertSame(12, wp_cache_get('compteur_vues', 'mon_extension_stats'));
}
}
Cette approche garantit que le test suivant repart d’un groupe vide, sans purger au passage le cache des options ou des méta-données que WordPress a construit pour son propre fonctionnement pendant la suite.
Vérifier qu’il ne reste vraiment rien
Il ne suffit pas d’appeler la fonction de nettoyage : encore faut-il vérifier qu’elle a fait son travail. Un test dédié peut s’en assurer explicitement :
- Créer une entrée dans le groupe visé avec
wp_cache_set(). - Appeler
wp_cache_flush_group()sur ce même groupe. - Vérifier que
wp_cache_get()renvoiefalsepour la clé concernée.
Ce test de contrôle a un intérêt qui dépasse la simple vérification unitaire : il documente, pour la personne qui reprendra la suite plus tard, que le nettoyage du groupe est un comportement attendu et testé, pas une convention tacite.
Le cas des groupes non persistants
Certains groupes sont déclarés « non persistants » via wp_cache_add_non_persistent_groups(), ce qui signifie qu’ils ne survivent jamais à une requête HTTP réelle en production, mais restent tout de même actifs en mémoire pendant l’exécution d’une suite de tests PHPUnit, puisque celle-ci se déroule dans un seul et même process. La distinction entre cache persistant et non persistant ne change rien à la nécessité de nettoyer entre deux tests ; elle influence seulement ce qui se passerait en production, ce qui sort du cadre de cet article.
Un piège fréquent : le nom du groupe mal orthographié
Une erreur courante consiste à appeler wp_cache_flush_group() avec un nom de groupe qui ne correspond pas exactement à celui utilisé lors de l’écriture en cache (une faute de frappe, une variable mal interpolée). La fonction ne renvoie aucune erreur dans ce cas : elle vide simplement un groupe qui n’existe pas, et l’entrée fautive reste en mémoire. Un test de contrôle explicite, comme celui décrit plus haut, permet justement de détecter ce genre d’erreur silencieuse avant qu’elle ne pollue une suite entière.
En résumé
Depuis WordPress 6.1, nettoyer un groupe de cache entre deux tests ne nécessite plus de purger l’ensemble du cache objet : wp_cache_flush_group() cible précisément le groupe concerné. Ajouter un test qui vérifie explicitement l’absence de résidu après ce nettoyage transforme une convention implicite en garantie automatisée, ce qui évite les échecs intermittents difficiles à reproduire quand l’ordre des tests change.
Note de rédaction : le titre initial de cette entrée mentionnait wp_cache_delete_group, une fonction qui n’existe pas dans l’API de cache objet de WordPress. La fonction réelle, introduite en WordPress 6.1, est wp_cache_flush_group() ; le titre et le contenu ont été corrigés en conséquence.
