Annotations

Au-delà de fournir une configuration de la génération des squelettes de tests, PhpUnitGen apporte aussi des annotations PHPDoc que vous pouvez utilisez dans vos fichiers à tester :

  • Instanciation de classe : @PhpUnitGen\construct.
  • Génération de tests unitaires pour les méthodes getters et setters : @PhpUnitGen\get et @PhpUnitGen\set.
  • Paramètres des méthodes : @PhpUnitGen\params.
  • Méthodes d'assertion de PHPUnit : @PhpUnitGen\... avec une assertion PHPUnit (@PhpUnitGen\assertTrue par exemple).
  • Création de mock : @PhpUnitGen\mock.

Ces annotations DOIVENT être écrites dans le bloc PHPDoc. Elles commencent toujours par @PhpUnitGen ou @Pug (qui n'est pas sensible à la casse, donc vous pouvez écrire @phpunitgen).


<?php
/**
 * Les suivantes marchent !
 * @PhpUnitGen\assertTrue()
 * @Pug\assertTrue()
 * @pug\assertTrue()
 * @phpUnitGen\assertTrue()
 *
 * Celle-ci ne marche pas :
 * @PhpUnitGenerator\assertTrue()
 */
function validateSomething(): bool { /* du code PHP */ }

Vous pouvez trouver quelques exemples basiques d'utilisation des annotations ici open_in_new avec des fichiers d'entrée et leurs résultats avec PhpUnitGen.

infoNote

Les annotations PhpUnitGen sont créées pour générer des tests simples. Si vous voulez tester des méthodes complexes, vous devriez écrire vos tests unitaires vous-même.

Génération automatique

Quand vous utilisez le paramètre auto de la configuration, PhpUnitGen détectera les méthodes getter / setter et générera les tests unitaires pour ces méthodes.

Dans PhpUnitGen, pour une propriété $name, un getter est une méthode getName, un setter est une méthode setName, et la classe ou le trait doit avoir une propriété $name.

PhpUnitGen va tester ces méthodes avec un paramètre généré automatiquement, qui aura le type de retour de la méthode pour un getter, ou le type d'argument de la méthode pour un setter.

PhpUnitGen va aussi générer les instanciations des classes ou des traits si ils ont une méthode __construct. Il utilisera ici aussi des paramètres générés automatiquement, alors soyez prudent avec ces instanciations automatiques.

Arguments des annotations

Certaines annotations auront besoin de paramètres. Quand il génère les squelettes, PhpUnitGen analyse ces paramètres comme du contenu JSON, alors tous les paramètres doivent être indiqués par des " lorsque ceux ne sont pas des tableaux ou des objets. Dans ces paramètres, vous pouvez écrire du code PHP, comme une création de Mock : "$this->createMock('MaClasse')".

N'oubliez pas d'échaper l'anti-slash \ ou le guillemet " avec un anti-slash \.

Instanciation de classes

Quand PhpUnitGen génère un squelette de tests, il ne pourra pas toujours détecter le constructeur, car il n'analyse qu'un seul fichier. Si vous fournissez cette annotation dans la documentation de la classe, il créera l'instanciation pour les tests avec vos paramètres.


<?php
namespace Company;
/**
 * Construit l'instance de tests avec 'new Employee("John", "0123456789")'
 * @PhpUnitGen\construct(["'John'", "'012-345-6789'"])
 */
class Employee extends AbstractPerson
{
    public function __construct(string $name, string $cellphone) { /* du code PHP */ }
}

Si vous voulez instancier une autre classe que celle d'origine (quand vous écrivez les tests d'une classe abstraite par exemple), vous pouvez fournir un argument indiquant la classe à instancier :


<?php
namespace Company;
/**
 * Construit l'instance de tests avec 'new \Company\Employee("John", "0123456789")'
 * @PhpUnitGen\construct("\Company\Employee", ["'John'", "'0123456789'"])
 */
abstract class AbstractPerson { /* du code PHP */ }

Getter et setter

Pour générer les tests pour un getter ou un setter, PhpUnitGen propose deux annotations.


<?php
class Employee {
    private $name;
    /**
     * Vérifie que quand la méthode est appelée, la valeur de la propriété $name est retournée.
     * @PhpUnitGen\get
     */
    public function getName(): string
    {
        return $this->name;
    }
    /**
     * Vérifie que quand la méthode est appelée, la valeur de la propriété $name est changée.
     * @PhpUnitGen\set
     */
    public function setName(string $name): void
    {
        $this->name = $name;
    }
}

Si voulez indiquer à PhpUnitGen que la méthode n'est pas nommée à partir de la propriété, ajoutez juste le nom de la propriété dans l'annotation.


<?php
class Employee {
    private $phone;
    /**
     * Vérifie que quand la méthode est appelée, la valeur de la propriété $phone est retournée.
     * @PhpUnitGen\get("phone")
     */
    public function getCellphone(): string
    {
        return $this->phone;
    }
    /**
     * Vérifie que quand la méthode est appelée, la valeur de la propriété $phone est changée.
     * @PhpUnitGen\set("phone")
     */
    public function setCellphone(string $phone): void
    {
        $this->phone = $phone;
    }
}

infoNote

Les annotations get et set supportent les méthodes statiques ou d'instance pour les classes, les traits et les interfaces, mais ne supportent pas les méthodes globales (en dehors des classes, traits ou interfaces). PhpUnitGen autorisent les méthodes get ou set privées / protégées.

Assertions sur les résultats d'une méthode

PhpUnitGen apporte aussi des annotations pour générer des assertions simples :


<?php
class Employee {
    private $phone;
    /**
     * Vérifie que la méthode ne retourne pas un résultat null.
     * @PhpUnitGen\assertNotNull()
     * Vérifie que la méthode retourne la chaîne de caractères '012-345-6789'.
     * @PhpUnitGen\assertEquals("'0123456789'")
     */
    public function getCellphone(): string
    {
        return $this->phone;
    }
}

Une annotation d'assertion se composent d'un paramètre optionel qui décrit la valeur attendue de l'assertion PHPUnit.

  • Il peut être n'importe quelle expression PHP.
  • Si il n'est pas fourni, PhpUnitGen considérera que l'assertion n'a pas besoin de paramètre, comme assertTrue par exemple.

Paramètres de méthode

Si la méthode que vous voulez tester a besoin de paramètres, vous pouvez utiliser l'annotation params.


<?php
class Employee {
    /**
     * Appelle la méthode avec les paramètres, et effectue les assertions sur le résultat.
     * @PhpUnitGen\params("'John'", "'0123456789'")
     * @PhpUnitGen\assertNotNull()
     * @PhpUnitGen\assertEquals("'John: 0123456789'")
     */
    public static function getEmployeeInfo(string $name, string $phone): string
    {
        return $name . ': ' . $phone;
    }
}

Cette annotation fonctionne comme l'annotation construct, mais les paramètres ne sont pas fournis dans un tableau JSON.

Création de Mock

L'annotation mock vous permet de créer un mock, qui pourra être défini en tant que propriété de la classe de test ou juste en variable de méthode.


<?php
namespace Company;
/**
 * Crée un mock de "\Company\Employee" et l'ajoute dans une propriété de classe "$employee".
 * @PhpUnitGen\mock("\\Company\\Employee", "employee")
 *
 * Utilise le mock créé "$employee" à partir de $this dans le constructeur.
 * @PhpUnitGen\construct(["$this->employee"])
 */
class EmployeeCard {
    public function __construct(Employee $employee) { /* du code PHP */ }

    /**
     * Crée un mock uniquement dans le test de la méthode.
     * @PhpUnitGen\mock("\\DateTime", "date")
     *
     * Utilise le mock dans les tests.
     * @PhpUnitGen\params("$date")
     * @PhpUnitGen\assertFalse()
     */
    public function isExpired(\DateTime $date): bool { /* du code PHP */ }
}

share