Configura PHPUnit y Local WP para tus proyectos WordPress

PHPUnit y Local WP es algo fuera de lo común cuando se trata de desarrollar plugins y temas.

Sin embargo, es posible. PHPUnit y Local WP son esas herramientas que mejoran tu nivel de desarrollador WordPress. Integrarlas se escucha y lee difícil.

Pero no lo es. Créeme. Pensaba que era muy tedioso integrar PHPUnit y Local WP, pero después de, al fin, intentarlo, solo me tomó 5 minutos.

Este post es el primero de una serie de posts dentro de Local WP Hub y al finalizar estas guías, vas a poder integrar PHPUnit y Local WP, escribir pruebas y ver que tu código funcione como lo esperas.

Requisitos

Este post lo considero de nivel intermedio, así que debes de saber (al menos lo básico) y tener instalado, lo siguiente:

Configurando el proyecto

En primera, debes crear el sitio en Local donde harás las pruebas a tu plugin. Después, dentro del sitio creado, ve a la carpeta wp-content/plugins y clona el repositorio del proyecto de prueba con:

git clone https://github.com/roelmagdaleno/wp-phpunit-plugin-example.git

El comando anterior descargará el plugin de prueba dentro de la carpeta wp-content/plugins/wp-phpunit-plugin-example.

La rama main del repositorio que has descargado tiene los archivos PHP originales y la rama plugin_with_tests tiene los archivos originales con los tests.

Solo tienes que ejecutar el siguiente comando para acceder a la rama plugin_with_tests:

git checkout plugin_with_tests

Abre WP-CLI en Local

Cualquier plugin que quieras integrar con PHPUnit deberá existir dentro de un sitio creado por Local.

Ahora debemos abrir el WP-CLI de nuestro sitio, para eso debes hacer click derecho a tu sitio y seleccionarás “Open Site Shell“:

Abre la terminal del sitio en Local con Open Site Shell donde integraremos PHPUnit.
Abre la terminal del sitio en Local con Open Site Shell.

Eso debe abrirte una terminal donde cargará WP-CLI automáticamente, una vez cargada, asegúrate que la ruta de la carpeta actual esté dentro de /tu-sitio/app/public/ ya que solo en esa ruta estará disponible WP-CLI:

Terminal del sitio en Local By Flywheel con WP-CLI cargado donde se usará PHPUnit.
Terminal del sitio en Local con WP-CLI cargado.

Para verificar si WP-CLI ha sido cargado, puedes correr el siguiente comando para ver la versión actual del WP-CLI:

wp --version # WP-CLI 2.5.0-alpha

wp scaffold a tu proyecto

Ya que tenemos abierta la terminal con WP-CLI cargado, podemos integrar PHPUnit a nuestro WordPress plugin con el comando wp scaffold.

Ese comando nos da la opción para crear un plugin desde cero e incluyendo PHPUnit (wp scaffold plugin) y otro comando para integrar PHPUnit a un proyecto ya creado por nosotros (wp scaffold plugin-tests).

En este post nos enfocaremos en integrar PHPUnit a un plugin (nuestro proyecto de prueba) ya existente en Local, es decir, usaremos el comando wp scaffold plugin-tests.

Para lograr eso tenemos que ir a la terminal con WP-CLI (el paso anterior) e ir al directorio donde existen los plugins:

cd wp-content/plugins

En mi caso, mi directorio actual (en Windows 10) de los plugins es:

E:\Sites\phpunit\app\public\wp-content\plugins

Ya estando dentro del directorio plugins, ahora tenemos que ejecutar el comando para crear los archivos principales de nuestras pruebas:

wp scaffold plugin-tests wp-phpunit-plugin-example

Si vas a crear otros archivos para pruebas de otro plugin, debes correr el mismo comando pero en vez de wp-phpunit-plugin-example debes poner el nombre (slug) del plugin.

El comando anterior creará los siguientes archivos dentro de la carpeta del plugin especificado:

ArchivoDescripción
phpunit.xml.distEs el archivo de configuración para PHPUnit.
.travis.ymlArchivo de configuración para Travis CI. En caso de que estés haciendo pruebas en Travis CI.
bin/install-wp-tests.shUn archivo que configura los archivos WordPress y base de datos de prueba.
tests/bootstrap.phpArchivo que activa nuestro plugin cuando las pruebas se ejecutan.
tests/test-sample.phpArchivo que contiene funciones de prueba.
.phpcs.xml.distUna colección de reglas para PHP_CodeSniffer.
Archivos generados cuando se ejecuta wp scaffold plugin-tests <plugin>.

De los archivos creados, puedes borrar los siguientes ya que no son necesarios para este post:

  • .travis.yml
  • tests/test-sample.php
  • .phpcs.xml.dist

WordPress y base de datos para PHPUnit y Local WP

Aquí viene la parte interesante. Tenemos que configurar los archivos WordPress y base de datos que se usarán cuando ejecutemos nuestras pruebas.

Para hacer eso, tienes que entrar a la carpeta del plugin y si ejecutas el siguiente comando verás los archivos creados anteriormente:

$ cd wp-content/plugins/wp-phpunit-plugin-example
$ ls -l
Lista de los archivos creados usados por PHPUnit en el plugin.
Lista de los archivos creados usados por PHPUnit en el plugin.

El archivo que nos interesa para configurar WordPress y la base de datos de prueba es bin/install-wp-tests.sh.

Ese archivo acepta seis parámetros pero los cuatro primeros son los más importantes:

bash ./bin/install-wp-tests.sh <db-name> <db-user> <db-password> <db-host> <wp-version> <skip-database-creation>

Cuando estás usando Local, es necesario especificar el puerto de la base de datos (será usado en el parámetro <db-host> como localhost:<port>) y para obtenerlo es en la siguiente pestaña:

Puerto de base de datos en Local.
Puerto de base de datos en Local.

Ahora ejecuta el siguiente comando para instalar WordPress y la base de datos de prueba:

bash ./bin/install-wp-tests.sh wordpress_tests root root localhost:10064

La instalación creará las carpetas:

  • wordpress. Contiene una instalación limpia de WordPress.
  • wordpress-tests-lib. Contiene PHPUnit compatible con WordPress.

Esas carpetas estarán en el directorio /temp de tu sistema operativo.

Para usuarios Windows, puedes acceder a la carpeta /temp usando Git Bash o usando el explorador de archivos en la siguiente ruta:

C:\Users\<user>\AppData\Local\Temp

Si eres curioso, te invito a leer el archivo bin/install-wp-tests.sh para que veas y aprendas cómo se crean las carpetas wordpress y wordpress-tests-lib.

WordPress, la base de datos y los archivos PHPUnit han sido creados y serán utilizados por tu plugin.

Configura el archivo wp-tests-config.php

Por default, si ejecutas PHPUnit después de que lo instales va a iniciar el archivo wp-tests-config.php dentro de la carpeta wordpress-tests-lib.

Esto está bien si solo estás probando un proyecto pero si en tu Local estás probando plugins en distintos sitios, PHPUnit siempre va a leer el archivo wordpress-tests-lib/wp-tests-config.php.

La solución, y es algo que recomiendo hacer incluso si estás trabajando en un solo sitio, es mover el archivo wordpress-tests-lib/wp-tests-config.php al directorio raíz de tu sitio Local.

Desde la consola, ve al directorio de tu plugin:

$ cd wp-content/plugins/wp-phpunit-plugin-example

Y ejecuta el siguiente comando composer para instalar PHPUnit en tu proyecto:

composer require phpunit/phpunit "^7.0"

Después de instalar, necesitas copiar el archivo wp-tests-config.php, lo encuentras en el siguiente directorio:

# Linux
/temp/wordpress-tests-lib/wp-tests-config.php

# Windows
C:\Users\<user>\AppData\Local\Temp\wordpress-tests-lib\wp-tests-config.php

Y lo pegas dentro de la carpeta raíz de tu sitio Local, por ejemplo:

C:\Users\<user>\Local Sites\phpunit\app\public\

Ahora abre el archivo wp-tests-config.php que acabas de pegar en el directorio raíz de tu sitio Local. Este archivo es similar al archivo wp-config.php y será cargado por WordPress para realizar las pruebas.

Encuentra la constante ABSPATH, en esta constante se define en qué WordPress vamos a ejecutar nuestras pruebas. Por default, la constante luce así:

define( 'ABSPATH', dirname( __FILE__ ) . '/wordpress/' );

El valor de la constante ABSPATH, en nuestro caso, debe ser la ruta absoluta de nuestro sitio Local, por ejemplo:

define( 'ABSPATH', 'E:\Sites\phpunit\app\public/' );

Si revisas el archivo wp-tests-config.php verás que las constantes DB_* tiene los datos que especificamos cuando ejecutamos bash ./bin/install-wp-tests.sh.

Integra PHPUnit y Local WP en tu proyecto

Cuando ejecutaste el comando bash ./bin/install-wp-tests.sh, este creó varios archivos, entre ellos phpunit.xml.dist. Este archivo es para configurar PHPUnit de acuerdo a nuestras necesidades con nuestras pruebas.

Originalmente, el archivo phpunit.xml.dist luce así:

<?xml version="1.0"?>
<phpunit
   bootstrap="tests/bootstrap.php"
   backupGlobals="false"
   colors="true"
   convertErrorsToExceptions="true"
   convertNoticesToExceptions="true"
   convertWarningsToExceptions="true"
   >
   <testsuites>
      <testsuite name="wp-phpunit-plugin-example">
         <directory prefix="test-" suffix=".php">./tests/</directory>
      </testsuite>
   </testsuites>
</phpunit>

El código XML anterior determina que nuestro directorio de pruebas es ./tests/ (directorio que existe dentro del directorio raíz de tu plugin), entre otras configuraciones como colores, el archivo bootstrap.php, etc.

Lo importante por hacer en este archivo es agregar una directiva que defina desde dónde va a leer el archivo de configuración: wp-tests-config.php. Recuerda que ese archivo lo hemos copiado al directorio raíz de nuestro sitio Local.

El pedazo de código a pegar en phpunit.xml.dist es:

<php>
    <const name="WP_TESTS_CONFIG_FILE_PATH" value="E:\Sites\phpunit\app\public\wp-tests-config.php" />
</php>

La directiva <php> y <const> inicializa una constante por default llamada WP_TESTS_CONFIG_FILE_PATH y su valor es la ruta absoluta del archivo wp-tests-config.php.

Internamente, esa constante está declarada y siendo validada en el siguiente archivo:

C:\Users\<user>\AppData\Local\Temp\wordpress-tests-lib\includes\bootstrap.php

Si abres el archivo, encontrarás el siguiente código donde trata de cargar el archivo wp-tests-config.php, el cual contiene la información necesaria para iniciar WordPress:

if ( defined( 'WP_TESTS_CONFIG_FILE_PATH' ) ) {
   $config_file_path = WP_TESTS_CONFIG_FILE_PATH;
} else {
   $config_file_path = dirname( __DIR__ );
   if ( ! file_exists( $config_file_path . '/wp-tests-config.php' ) ) {
      // Support the config file from the root of the develop repository.
      if ( basename( $config_file_path ) === 'phpunit' && basename( dirname( $config_file_path ) ) === 'tests' ) {
         $config_file_path = dirname( dirname( $config_file_path ) );
      }
   }
   $config_file_path .= '/wp-tests-config.php';
}

Al final, tu código phpunit.xml.dist debe lucir de la siguiente manera (ya con la directiva <php> y <const>):

<?xml version="1.0"?>
<phpunit
   bootstrap="tests/bootstrap.php"
   backupGlobals="false"
   colors="true"
   convertErrorsToExceptions="true"
   convertNoticesToExceptions="true"
   convertWarningsToExceptions="true"
   >
    <php>
        <const name="WP_TESTS_CONFIG_FILE_PATH" value="E:\Sites\phpunit\app\public\wp-tests-config.php" />
    </php>
   <testsuites>
      <testsuite name="wp-phpunit-plugin-example">
         <directory prefix="test-" suffix=".php">./tests/</directory>
      </testsuite>
   </testsuites>
</phpunit>

¿PHPUnit está bien configurado?

Después de que has hecho todo, puedes abrir tu terminal e ir al directorio del plugin de prueba y luego ejecutar el siguiente comando para ver si los tests dentro del plugin wp-phpunit-plugin-example funcionan:

$ cd /e/Sites/phpunit/app/public/wp-content/plugins/wp-phpunit-plugin-example/
$ vendor/bin/phpunit

Si todo sale bien, el comando empezará a instalar el WordPress y base de datos de prueba. Si existe algún error al ejecutar el comando, lee el error e intenta solucionarlo, si no, puedes pegar el error en los comentarios y con gusto te ayudo.

Después correrá las pruebas escritas en el directorio wp-phpunit-plugin-example/tests y finalmente mostrará los resultados:

Resultados al ejecutar vendor/bin/phpunit.
Resultados al ejecutar vendor/bin/phpunit.

Explicaremos las pruebas que se están ejecutando en el siguiente post de esta serie.

Conclusiones

¡Estás listo para empezar a probar tus plugins usando PHPUnit! Pareciera que los pasos de este post son largos y complicados pero una vez que lo comprendes y lo haces, lo irás haciendo mucho más rápido.

Un punto a tomar en cuenta es que la configuración de este post fue hecha en Windows 10 Pro pero debería funcionar en otros sistemas operativos, solo es cuestión de localizar las rutas de los archivos.

Hacer pruebas de tus plugins usando PHPUnit te permite:

  • Prevenir errores en un futuro.
  • Agregar funcionalidades nuevas eficientemente.
  • Encuentra varios tipos de errores: de seguridad o lógicos.

Tal vez, al principio, parezca que estés perdiendo el tiempo pero valdrá la pena cuando veas que tus pruebas han ayudado a mejorar tu código.

En el siguiente post de esta serie escribiremos nuestras pruebas PHPUnit para nuestro plugin: WP PHPUnit Plugin Example.

0

Comentarios

6 respuestas a “Configura PHPUnit y Local WP para tus proyectos WordPress”

  1. Avatar de Carlos
    Carlos

    Buenos días,

    al ejecutar el siguiente comando:

    bash ./bin/install-wp-tests.sh wordpress_tests root root localhost:10064

    Me genera la BD pero esta está vacía, no tiene tablas.

    ¿Esto es así?

    Saludos

    1. Avatar de Roel Magdaleno

      Buen día Carlos, gracias por pasar por mi blog.

      Estás en lo correcto, cuando el script install-wp-tests.sh se ejecuta solo va a crear la base de datos. Por otra parte, solo va a crear las tablas cuando ya estés corriendo tus pruebas. Ten en cuenta que los datos guardados en la base de datos de prueba se borrarán en cada test que hagas.

      El archivo que hace todo ese proceso es wordpress-tests-lib/includes/bootstrap.php, específicamente, entre la línea 257 a la 265, es donde se llama el script install.php, el cual es el responsable de instalar el WordPress.

      Espero te haya servido, un saludo.

  2. Avatar de Erick
    Erick

    Hola me da este error
    $ vendor/bin/phpunit
    Could not find C:\Windows\TEMP/wordpress-tests-lib/includes/functions.php, have you run bin/install-wp-tests.sh ?

    1. Avatar de Roel Magdaleno

      Buen día Erick. Gracias por pasar por mi blog.

      El mismo error te está diciendo qué es lo que posiblemente esté mal en tu configuración. En este caso, ¿si ejecutaste el archivo bin/install-wp-tests.sh? En este mismo post, en la sección de “WordPress y base de datos para PHPUnit y Local WP” empiezo a describrir la ejecución de dicho archivo.

      Si aún así no funciona, hazme saber y vemos más posibles soluciones, por ejemplo, que la carpeta wordpress-tests-lib ya exista, en este caso, ve a tu directorio C:\Windows\TEMP/ y borra la carpeta wordpress-tests-lib y has la ejecución del archivo bash de nuevo.

      Saludos.

  3. Avatar de Erick
    Erick

    Justamente hizo de borrar la carpeta wordpress-tests-lib y volver a ejecutar el archivo bash y me sigue dando ese mismo error

    1. Avatar de Roel Magdaleno

      Hola Erick. Está muy raro…¿puedes volver a ejecutar el archivo bash y ver si no te tira algún error dentro de la consola? Podría ser también que no está creando la base de datos de prueba o algunos archivos no están donde deberían de estar. Si gustas este fin de semana estoy libre, podemos tener una video llamada donde me muestres el proceso de instalación. Hazme saber en mi correo: roelmagdaleno@gmail.com

      Saludos.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *