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:

• PHP con OOP.
• PHPUnit.
• Desarrollo de WordPress Plugins.
• Local. En este post estoy usando la versión 5.10.1+5267.
• Composer.
• WP-CLI. Ya viene integrado con Local.
• SVN (El comando svn será usado como control de versiones).
• MySQL. (El comando mysqladmin será usado para crear la base de datos).
• Descargar el proyecto de prueba.

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“:

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:

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:

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

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:

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'<strong>, </strong>'E:\Sites\phpunit\app\public/' )<strong>;</strong>

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 = <em>WP_TESTS_CONFIG_FILE_PATH</em><strong>;
</strong>} else {
   $config_file_path = dirname( <em>__DIR__ </em>)<strong>;
   </strong>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 ) )<strong>;
      </strong>}
   }
   $config_file_path .= '/wp-tests-config.php'<strong>;
</strong>}

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:

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.