livexample

ejemplo en vivo

Este es un marco de prueba orientado a la documentación desde PHP 5.3 a 7.x. Su propósito es garantizar que sus códigos de ejemplo funcionen mediante pruebas unitarias. Inspirado en los "Ejemplos" de prueba de Golang.

Un ejemplo de caso de prueba simple

Vea un ejemplo a continuación. La primera sección es un código de ejemplo que se probará. El comentario que comienza con Output es código de prueba.

 <?php

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

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

Este código de ejemplo está roto. Se espera que aparezca la palabra "villancico", sin embargo, no aparece. Este caso de prueba falla, pero puede saber que el código de ejemplo tiene un problema y puede solucionarlo.

¿Cómo funciona?

Livexample sigue los siguientes pasos:

1. Encuentre la declaración Output en el código de ejemplo analizándola.
2. Ejecute el código en PHPUnit y capture el resultado.
3. Compare la producción esperada y la producción real.

Beneficios

A veces, los códigos de ejemplo se rompen al agregar nuevas funciones, olvidarse de actualizarlas, solicitudes de extracción que no se ocupan de los códigos de ejemplo, etc.

Los códigos de ejemplo rotos son una mala experiencia para los usuarios de la biblioteca.

Al utilizar Livexample, obtendrás beneficios:

• Sus códigos de ejemplo están protegidos contra regresiones inesperadas.
• Puede comprobar fácilmente que sus códigos de ejemplo son válidos.
• Los usuarios de su biblioteca pueden utilizar los códigos de ejemplo válidos copiando y pegando.
• No es necesario agregar grandes cambios a los códigos de muestra existentes; Solo agrego algunos comentarios.

Características

• Livexample funciona como parte de PHPUnit.
• Costo de aprendizaje muy bajo.

Empezando

Instale suin/livexample a través de Composer:

 composer require --dev suin/livexample

Agregue ExampleTest.php a su directorio de pruebas:

 use Livexample  PHPUnit  ExampleTestCase ;

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

Ejecute phpunit:

 phpunit

Sintaxis de afirmación

Hay dos sintaxis para la afirmación:

• Largo: // Output: {expected output}
• Corto: //=> {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)
// } 

Consejos: var_dump($object)

La función var_dump() imprime identificadores de objetos, que son #some-number al lado del nombre de la clase. Dado que los identificadores dependen del entorno de ejecución, no puede codificarlos en la instrucción Output: :. En lugar de codificar el identificador, puede utilizar un marcador de posición %d para el número:

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

Consejos: ejecute un script de ejemplo con el comando php

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

¿Por qué es compatible con PHP 5.3 en 2017?

El soporte oficial para PHP 5.3 ha finalizado; sin embargo, RHEL/CentOS sigue admitiendo PHP 5.3 incluso en 2017. Los antiguos entornos PHP aún permanecen en el servicio en ejecución hoy. También se supone que Livexample se utiliza para refactorizar entornos antiguos.

Registro de cambios

Consulte CHANGELOG para obtener más detalles.

Contribuyendo

Consulte CONTRIBUCIÓN para obtener más detalles. Por favor arregla mi inglés.