livexample

Exemple en direct

Il s'agit d'un framework de test orienté documentation pour PHP 5.3 à 7.x. Son objectif est de garantir que vos exemples de codes fonctionnent par tests unitaires. Inspiré par les tests Golang "Exemples".

Un exemple de cas de test simple

Voir un exemple ci-dessous. La première section est un exemple de code qui sera testé. Le commentaire qui commence par Output est le code de test.

 <?php

function hello ( string $ name ): string {
	return ' hello ' . $ name ;
}
echo hello ( ' alice ' ) . "n" ;
echo hello ( ' bob ' ) . "n" ;

// Output:
// hello alice
// hello carol

Cet exemple de code est cassé. Le mot « Carol » est attendu en sortie, mais il n'apparaît pas. Ce scénario de test échoue, mais vous pouvez savoir que l'exemple de code présente un problème et vous pouvez le résoudre.

Comment ça marche ?

Livexample effectue les étapes suivantes :

1. Recherchez l’instruction Output dans l’exemple de code en l’analysant.
2. Exécutez le code dans PHPUnit et capturez le résultat.
3. Comparez le résultat attendu et le résultat réel.

Avantages

Parfois, les exemples de codes sont cassés, en ajoutant de nouvelles fonctionnalités, en oubliant de les mettre à jour, en effectuant des pull-requests qui ne prennent pas en charge les exemples de codes, etc.

Les exemples de codes brisés sont une mauvaise expérience pour les utilisateurs de la bibliothèque.

En utilisant Livexample, vous bénéficierez des avantages suivants :

• Vos exemples de codes sont protégés contre toute régression inattendue.
• Vous pouvez facilement vérifier que vos exemples de codes sont valides.
• Les utilisateurs de votre bibliothèque peuvent utiliser les exemples de codes valides par copier-coller.
• Vous n'avez pas besoin d'ajouter de grandes modifications à vos exemples de codes existants ; j'ajoute juste quelques commentaires.

Caractéristiques

• Livexample fait partie de PHPUnit.
• Coût d'apprentissage très faible.

Commencer

Installez suin/livexample via Composer :

 composer require --dev suin/livexample

Ajoutez ExampleTest.php à votre répertoire de tests :

 use Livexample  PHPUnit  ExampleTestCase ;

class ExampleTest extends ExampleTestCase
{
    public function exampleFiles ()
    {
        // specify your example code directory.
        return self :: exampleDirectory ( ' example ' );
    }
}

Exécutez phpunit :

 phpunit

Syntaxe d'assertion

Il existe deux syntaxes pour l'assertion :

• Long : // Output: {expected output}
• Court : //=> {expected output}

 echo 1 ; // Output: 1 

 echo " hello " ; //=> hello 

 var_dump ([ 1 , 2 , 3 ]);
// Output:
// array(3) {
// 	[0] =>
// 	int(1)
// 	[1] =>
// 	int(2)
// 	[2] =>
// 	int(3)
// } 

Astuces : var_dump($object)

La fonction var_dump() imprime les identifiants d'objet, qui sont #some-number à côté du nom de la classe. Étant donné que les identifiants dépendent de l'environnement d'exécution, vous ne pouvez pas les coder en dur dans l'instruction Output: Au lieu de coder en dur l'identifiant, vous pouvez utiliser un espace réservé %d pour le numéro :

 <?php
var_dump ( new stdClass );
// Output:
// object(stdClass)#%d (0) {
// } 

Astuces : exécutez un exemple de script avec la commande php

 php -d auto_prepend_file=vendor/autoload.php 
    -d xdebug.overload_var_dump=0 
    example/simple-usage.php

Pourquoi prend en charge PHP 5.3 en 2017 ?

Le support officiel de PHP 5.3 a pris fin, cependant, RHEL/CentOS continue de prendre en charge PHP 5.3 même en 2017. Les anciens environnements PHP restent toujours dans le service en cours d'exécution aujourd'hui. Livexample est également censé être utilisé pour refactoriser ces anciens environnements.

Journal des modifications

Veuillez consulter CHANGELOG pour plus de détails.

Contribuer

Veuillez consulter CONTRIBUER pour plus de détails. S'il vous plaît, corrigez mon anglais.