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.
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“:
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
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:
Archivo | Descripción |
phpunit.xml.dist | Es el archivo de configuración para PHPUnit. |
.travis.yml | Archivo de configuración para Travis CI. En caso de que estés haciendo pruebas en Travis CI. |
bin/install-wp-tests.sh | Un archivo que configura los archivos WordPress y base de datos de prueba. |
tests/bootstrap.php | Archivo que activa nuestro plugin cuando las pruebas se ejecutan. |
tests/test-sample.php | Archivo que contiene funciones de prueba. |
.phpcs.xml.dist | Una colección de reglas para PHP_CodeSniffer. |
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
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
.
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 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:
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.
Deja un comentario