Prueba tus WordPress Plugins con PHPUnit en Local

Cuando estamos desarrollando nuestros plugins para WordPress, lo último que se nos viene a la mente es, probarlos. Y con probarlos me refiero a integrar PHPUnit y crear pruebas para confirmar que nuestro plugin para WordPress funciona.

SERIE DE ARTÍCULOS

Configura PHPStorm y PHPUnit usando Local

Hay desarrolladores que quieren ejecutar PHPUnit desde su editor en vez de la terminal. Configuremos PHPStorm y PHPUnit junto con Local.

Al principio tal vez pueda ser algo tedioso el configurar PHPUnit y escribir los tests para cualquier aplicación de PHP y más tedioso aún cuando tienes que integrarlo con Local y no sabes qué archivos configurar.

Me di a la tarea de jugar con PHPUnit, WordPress y Local. Al principio pensé que era algo difícil de configurar porque, para ser sinceros, no soy una persona que le guste configurar cosas y para mi sorpresa, lo tuve listo en casi 5 minutos.

Requisitos

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

Los comandos de SVN (svn) y MySQL (mysqladmin) deben ser agregado a tus variables de entorno.

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

Puedes activar o no el plugin, comprobaremos la funcionalidad visual una vez que todas nuestras pruebas sean exitosas.

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

Si la terminal no abre correctamente al principio, en la terminal debes escribir el disco donde está creado el sitio de Local, por ejemplo, si tu sitio está dentro del disco E:, entonces debes escribir E: y presionar ENTER.

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

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.

Si al final de la instalación ocurre algún error, por ejemplo, en los comandos svn o mysqladmin revisa que tengas esos comandos instalados y habilitados en tus variables de entorno.

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/' );

La ruta absoluta del sitio Local debe terminar con un slash (/) para que todos los archivos de WordPress sean leídos y ejecutados.

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 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.

Roel Magdaleno
Escrito por Roel Magdaleno

Roel Magdaleno es un ingeniero informático especializado en desarrollo web desde hace más de 5 años. Desarrolla sitios web, aplicaciones web, plugins para WordPress y scripts con PHP y JavaScript. Además, comparte su conocimiento en su blog personal.

Deja un comentario