Hamcrest-php est l'implémentation officielle du framework Hamcrest pour PHP. Il permet de définir des "matchers" déclaratifs pour construire des assertions de test à la fois flexibles et hautement lisibles. En s'éloignant des assertions booléennes classiques, Hamcrest rapproche le code de test du langage naturel, facilitant ainsi la maintainance à long terme.

Pourquoi adopter Hamcrest-php dans vos suites de tests ?

L'atout majeur de Hamcrest réside dans sa sémantique et sa modularité. Contrairement aux méthodes d'assertion traditionnelles qui se limitent souvent à des comparaisons d'égalité simples, Hamcrest permet de combiner des règles complexes de manière fluide.

• Expressivité : Les échecs de tests produisent des messages d'erreur explicites.
• Composabilité : Possibilité de chaîner plusieurs conditions logiques.
• Extensibilité : Création facile de matchers personnalisés pour des domaines métier spécifiques.

Utilisation optimale des matchers de collections

Les tableaux étant omniprésents en PHP, Hamcrest propose des outils robustes pour valider leur contenu et leur structure sans écrire de boucles complexes dans les tests.

// Vérifier la présence d'une valeur spécifique
assertThat(['docker', 'kubernetes', 'terraform'], hasItem('kubernetes'));

// Valider une paire clé-valeur dans un tableau associatif
assertThat(['status' => 'active', 'retry' => 3], hasKeyValuePair('status', 'active'));

Puissance de la composition logique

Le véritable potentiel de la bibliothèque se révèle lors de l'utilisation de matchers logiques comme allOf, anyOf ou not. Cela permet de valider plusieurs propriétés d'un objet en une seule instruction cohérente.

// Validation multicritères d'un tableau de scores
assertThat($scores, allOf(
    hasItem(greaterThan(90)),
    arrayWithSize(5),
    not(hasItem(lessThan(0)))
));

Stratégies pour améliorer la clarté du code

1. Privilégier les matchers sémantiques

Il est recommandé de choisir le matcher le plus précis possible. Par exemple, préférez containsString() à une vérification générique d'égalité si vous ne testez qu'une partie d'une chaîne de caractères.

2. Structuration visuelle des assertions

Pour les objets complexes, une indentation rigoureuse permet de visualiser immédiatement les règles de validation :

assertThat($accountProfile, allOf(
    hasProperty('username', equalTo('dev_user')),
    hasProperty('role', containsString('ADMIN')),
    hasProperty('permissions', arrayWithSize(greaterThan(1)))
));

3. Exploitation des messages d'erreur natifs

Hamcrest génère automatiquement des descriptions précises en cas d'échec, ce qui réduit le temps de débogage. Un échec affichera : "Expected: an array containing 'premium' but: was ['standard', 'guest']".

Cas d'utilisation concrets

Validation d'un objet de transfert de données (DTO)

public function testUpdateProfileCommand() {
    $command = $this->bus->dispatch(new UpdateUserCommand([
        'display_name' => 'Marc Dupont',
        'email' => 'm.dupont@provider.com',
        'level' => 10
    ]));
    
    assertThat($command, allOf(
        hasProperty('display_name', equalToIgnoringCase('marc dupont')),
        hasProperty('email', containsString('@')),
        hasProperty('level', is(integerValue()))
    ));
}

Inspection des réponses d'une API

public function testEndpointResponse() {
    $payload = $this->client->get('/api/v1/resource/42');
    
    assertThat($payload, allOf(
        hasKeyValuePair('id', 42),
        hasKeyValuePair('type', identicalTo('asset')),
        hasKeyValuePair('tags', not(emptyArray()))
    ));
}

Synthèse des bonnes pratiques

1. Sémantique : Utilisez des matchers qui décrivent l'intention plutôt que l'implémentation.
2. Modularité : Décomposez les assertions complexes en sous-matchers réutilisables.
3. Diagnostic : Profitez de la clarté des messages d'échec pour éviter les commentaires superflus dans le code.
4. Simplicité : Évitez les chaînes de matchers trop longues qui nuisent à la lisibilité globale du cas de test.