Documentation officielle de l'outil de génération PHPUnitGen

PhpUnitGen est un outil d'analyse de code PHP et de génération de tests unitaires.

Il a été développé par Paul Thébaud.

PhpUnitGen est utilisable en ligne, car il analyse le code PHP plutôt que d'utiliser les Reflections PHP.

Toutefois, il existe une version installable avec Composer.

Comme de nombreux outils, il est configurable dans son fonctionnement ou son design.
Grâce au bouton de configuration — en haut à droite lorsque vous êtes sur l'application —, vous pouvez modifier ces paramètres :

• Taille de l'éditeur : permet de régler la hauteur de l'éditeur de code PHP.
• Thème : permet de changer les couleurs de l'application (en plus il y a des surprises quand vous utilisez l'application).
• Génération automatique : permet de générer automatiquement les tests unitaires des méthodes getters/setters, ou l'instanciation des classes ou traits.
• Analyse des méthodes privées/protégées : permet d'activer ou de désactiver la génération de squelettes pour les méthodes privées ou protégées.
• Analyse des interfaces : permet d'activer ou de désactiver la génération de squelettes pour les interfaces PHP.
• PHPDoc des tests générés : permet de gérer une liste des annotations PHPDoc (@author par exemple) qui se trouveront dans l'entête de la classe de test.

Note

Cette configuration sera automatiquement sauvegardée à chaque modification, directement dans le stockage de votre navigateur. Il est possible de la réinitialiser avec le bouton « reset », en bas à gauche de la page de configuration.

L'application web peut ensuite être utilisée de deux manières différentes :

• soit vous importez un fichier PHP ;
• soit vous utilisez l'éditeur de code PHP à votre disposition (n'oubliez pas que vous pouvez fournir le nom qu'aura la classe générée, dans le champ au-dessus de l'éditeur).
  Enfin, lorsque vous êtes sur cette documentation, vous pouvez juste cliquer sur le bouton en bas à droite pour aller sur l'application PhpUnitGen.

La meilleure façon d'installer PhpUnitGen est via Composer. Cela permettra d'effectuer facilement les mises à jour.
Composer est le gestionnaire de package pour les projets PHP.

$ composer require --dev paulthebaud/phpunit-generator ^2.0

L'option --dev est utilisée pour installer le package uniquement dans un environnement de développement.
PhpUnitGen utilise PHP 7.1, mais est aussi compatible (et testé avec Travis) avec PHP 7.2.

Voici un exemple d'utilisation de PhpUnitGen dans un script PHP.

<?php

use PhpUnitGen\Configuration\BaseConfig;
use PhpUnitGen\Container\ContainerFactory;
use PhpUnitGen\Executor\ExecutorInterface\ExecutorInterface;

// Importer l'autoload Composer
require 'vendor/autoload.php';

// Créer la configuration
$config = new BaseConfig([ /* ... des options ... */ ]);

// Créer le conteneur de dépendances
$container = (new ContainerFactory())->invoke($config);

$myTestClass = 'MyClassTest';
$myCode = "<?php class MyClass { /* ... du code PHP ... */ }";

// Exécuter PhpUnitGen sur le code et enregistrer les résultats
$myUnitTestsSkeleton = $container->get(ExecutorInterface::class)->invoke($myCode, $myTestClass);

// Afficher les résultats
echo $myUnitTestsSkeleton;

Note

new BaseConfig() ou $container->get(ExecutorInterface::class)->invoke($myCode, $myTestClass) sont susceptibles de lever des exceptions PHP, si la configuration fournie est invalide par exemple.

Quand vous installez le package Composer, vous pouvez utiliser PhpUnitGen en ligne de commande. Il faut vous placer à la racine de votre projet Composer.

$ php ./vendor/bin/phpunitgen

Pour cette commande, vous aurez besoin d'un fichier de configuration écrit en YAML, JSON ou PHP.

• L'exemple YAML se trouve ici here.
• L'exemple JSON se trouve ici here.
• L'exemple PHP se trouve ici here.
  Par défaut (sans option), PhpUnitGen cherchera un fichier de configuration nommé phpunitgen.yml à la racine du projet.
  Mais si vous souhaitez utiliser une configuration personnalisée, vous pouvez utiliser une option :

$ php ./vendor/bin/phpunitgen --config=my/custom/config.yml

$ php ./vendor/bin/phpunitgen -c=my/custom/config.yml

Pour utiliser PhpUnitGen sur un seul fichier (l'utilisation de l'option file aura besoin d'une source et d'une cible étant des fichiers) :

$ php ./vendor/bin/phpunitgen --file source/file.php target/file.php

$ php ./vendor/bin/phpunitgen -f source/file.php target/file.php

Pour utiliser PhpUnitGen sur un seul dossier (l'utilisation de l'option dir aura besoin d'une source et d'une cible étant des dossiers) :

$ php ./vendor/bin/phpunitgen --dir source/dir target/dir

$ php ./vendor/bin/phpunitgen -d source/dir target/dir

Pour utiliser PhpUnitGen avec la configuration par défaut (l'utilisation de l'option default aura besoin d'une source et d'une cible) :

$ php ./vendor/bin/phpunitgen --default --file source/file.php target/file.php
$ php ./vendor/bin/phpunitgen --default --dir source/dir target/dir

$ php ./vendor/bin/phpunitgen -D -f source/file.php target/file.php
$ php ./vendor/bin/phpunitgen -D -d source/dir target/dir

Note

• Si vous utilisez l'option default avec l'option config, la configuration sera ignorée et PhpUnitGen utilisera la configuration par défaut.
• Si vous utilisez l'option default, et que vous ne fournissez pas d'option dir ou file, PhpUnitGen considèrera que les source et cible sont des dossiers.
• Étant donné que PhpUnitGen utilise le package de la Console Symfony, vous pouvez combiner plusieurs raccourcis d'options ensemble : $ php ./vendor/bin/phpunitgen -fc my/custom/config.yml source/file.php target/file.php analysera un seul fichier avec la configuration personnalisée fournie.

IV-A. Paramètres du fichier de Configuration▲

Au-delà de fournir une configuration de la génération des squelettes de tests, PhpUnitGen apporte aussi des annotations PHPDoc que vous pouvez utiliser 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 avec des fichiers d'entrée et leurs résultats avec PhpUnitGen.

Note

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.

V-A. Génération automatique▲

V-B. Arguments des annotations▲

V-C. Instanciation de classes▲

<?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 */ }
}

<?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 */ }

V-D. Getter et setter▲

<?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;
    }
}

<?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;
    }
}

V-E. Assertions sur les résultats d'une méthode▲

<?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;
    }
}

V-F. Paramètres de méthode▲

<?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;
    }
}

V-G. Création de Mock▲

<?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 */ }
}

Nos remerciements à Guillaume SIGUI pour la mise au gabarit, et f-leb pour la relecture orthographique.