Pruebas sencillas de unidades de JavaScript en WordPress con Jest

WordPress tiene un largo historial de pruebas unitarias de su código PHP. Sin embargo, escribir pruebas unitarias de JavaScript y pruebas de integración para el código en temas y complementos no disfruta del mismo estado. Veamos cómo probar JavaScript en nuestros complementos y temas de WordPress usando Jest.

Estos son los contenidos que trataremos en este artículo:

Pruebas unitarias de JavaScript en WordPress

Entonces, ¿por qué escribir pruebas unitarias y pruebas de integración? Son excelentes para garantizar que una función, un método de clase o incluso un componente de React hagan lo que se supone que deben hacer. Ayuda a detectar errores en el código y también ayuda a preservar la integridad cuando se introducen cambios más tarde en el código al verificar que sigue funcionando según lo previsto después de la actualización.

Los complementos y temas de WordPress están escritos principalmente en PHP y pueden usar la suite PHPUnit para ejecutar pruebas, hacer afirmaciones, burlar funciones y más. El manual incluso tiene una sección que explica cómo configurar rápidamente las pruebas unitarias con WP-CLI.

Para JavaScript, hay una página sobre cómo ejecutar pruebas QUnit en el Manual, aunque se trata más de probar el código JavaScript en el núcleo de WordPress.

Si bien nada de esto está estandarizado para JavaScript en WordPress, podemos escribir excelentes pruebas unitarias utilizando el conjunto de pruebas Jest. En este artículo, aprenderemos cómo escribir pruebas unitarias de JavaScript para un complemento de ejemplo que carga 5 publicaciones a través de la API REST de WP utilizando la fetchfunción de JavaScript y las representa en un determinado elemento DOM en la página.

Beneficios de usar Jest para pruebas unitarias de JavaScript en WordPress

En el pasado, escribir pruebas unitarias de JavaScript implicaba configurar Mocha para ejecutar pruebas, Chai para hacer afirmaciones y Sinon para simular funciones y espiarlas. Si bien ofrecen una gran flexibilidad, es mucho más complejo trabajar con tres paquetes que con uno. Jest proporciona todo esto en un solo paquete:

• puede ejecutar pruebas declarándolos con describey itotest
• puedes hacer afirmaciones con expecty toBe, toHaveLengthy muchas más
• puede simular funciones y espiarlas, y hay varias formas de hacerlo

Antes de continuar

Para mantener este artículo centrado en las pruebas con Jest, hay una configuración adicional externa al proceso de prueba como Babel o Webpack que no se tratará aquí. Todo esto se puede encontrar en el repositorio de WP Jest Tests que acompaña a este artículo. Para mantener las cosas contextuales, cada sección se vinculará a uno de los archivos relevantes que escribiremos.

Descripción general del lado de PHP

El PHP para el complemento de ejemplo que usaremos para aprender a escribir las pruebas unitarias de JavaScript es bastante estándar. Las únicas líneas interesantes son aquellas cuando ponemos en cola nuestro archivo JavaScript y agregamos un script en línea para pasarle variables:

Después de enquear nuestro archivo JavaScript, agregamos una variable global wpJestTestscon wp_add_inline_script(). Esta variable es particularmente interesante y difícil de manejar porque es externa a nuestro archivo JavaScript y tendremos que simularla en nuestras pruebas.

Configurar pruebas Jest

Primero tendremos que inicializar npmnuestro proyecto de complemento para poder instalar Jest con él. Navegue en la línea de comando a su carpeta de complementos y ejecute:

npm inity siga la serie de indicaciones aquí

Edite el archivo package.json que se creó y agregue una nueva entrada para ejecutar nuestras pruebas en la scriptssección:

"test": "jest"

Este será el comando que usaremos para decirle a Jest que ejecute nuestras pruebas unitarias de JavaScript. Esta es una ejecución única, pero Jest también admite la visualización de archivos, por lo que puede ingresar uno adicional:

"test-watch": "jest --watch"

Ahora instale Jest como una dependencia de desarrollo ejecutando

npm install -D jest

Mientras se instala, cree un archivo llamado jest.config.js. Esto mantendrá toda la configuración necesaria. Agregue lo siguiente:

module.exports = {
    verbose: true,
    setupFiles: [
        '/__mocks__/globals.js'
    ],
    moduleNameMapper: {
        '.(css|less|sass|scss)$': '/__mocks__/styleMock.js'
   }
};

Repasemos cada uno:

• verbose: indica si se debe informar cada prueba individual durante la ejecución. Todos los errores también se seguirán mostrando en la parte inferior después de la ejecución. Tenga en cuenta que si solo se está ejecutando un archivo de prueba, el valor predeterminado es true.
• setupFiles: una lista de rutas a módulos que ejecutan algún código para configurar o configurar el entorno de prueba. Cada archivo de configuración se ejecutará una vez por archivo de prueba. Dado que cada prueba se ejecuta en su propio entorno, estos scripts se ejecutarán en el entorno de prueba inmediatamente antes de ejecutar el código de prueba. Usaremos esto para declarar variables globales renderizadas por PHP y WordPress con comandos como wp_add_inline_scripto wp_localize_script.
• moduleNameMapper: este es un mapa de expresiones regulares a nombres de módulos (o matrices de nombres de módulos) que permiten extraer recursos estáticos, como imágenes o estilos con un solo módulo.

Seguramente notó la referencia: este es un token especial que es reemplazado por Jest con la raíz de su proyecto, que generalmente es la ubicación de su archivo package.json.

Profundizaremos en las siguientes dos secciones, pero primero, cree la carpeta y estos dos archivos a los que se hace referencia anteriormente:

• crear una carpeta llamada__mocks__
• dentro de la carpeta, crea los archivos styleMock.jsyglobals.js

Importación de estilos simulados para pruebas Jest

Si, como este complemento, usa Webpack para compilar todo, incluidos los estilos, y está importando el .scssarchivo en el .jsarchivo:

import './main.scss';

necesita usar styleMock.js para simular archivos SASS al importarlos en nuestro archivo JavaScript; de lo contrario, Jest se bloqueará porque no podrá resolver el módulo. No necesita mucho para este archivo, solo agregue

Jest usará este simulacro cada vez que encuentre una .scssimportación y los asignará al simulacro, permitiéndole avanzar con las pruebas sin preocuparse por los estilos.

Configurar globales para Jest

Trabajemos ahora en el archivo globals.js. Una de las ventajas de usar Jest es que ya viene con una jsdomimplementación de estándares web de JavaScript puro ya configurada, que simula un entorno DOM como si estuviera en el navegador, y lo usaremos para simular elementos DOM. para nuestras pruebas.

Cree una carpeta __mocks__y un globals.jsarchivo dentro de ella. Agregue esto al archivo:

import { JSDOM } from 'jsdom';
const dom = new JSDOM();
global.document = dom.window.document;
global.window = dom.window;
global.window.wpJestTests = undefined;

Esto declarará y simulará algunos objetos y métodos que luego usará en sus pruebas. El último es de especial interés.

global.window.wpJestTests = undefined;

Esta es la variable global que escribimos usando wp_add_inline_script. Debe simularlo como una variable global para poder usarlo en sus pruebas.

Descripción general del archivo JavaScript

El complemento de WordPress tiene un solo archivo JavaScript main.js en una /srccarpeta. Esto luego se transpila y se genera en un /js/front.jsarchivo que es lo que cargará el PHP. El JavaScript carga cinco publicaciones de WordPress usando fetch, una función estándar de JavaScript, a través de la API REST de WP e inserta su título, con un enlace a la publicación, en un archivo div.entry-content.

Vas a exportar la función que hace todo el trabajo:

para que puedas usarlo en tus pruebas en Jest.

Escribiendo pruebas unitarias de JavaScript con Jest, ¡por fin!

¡Ahora puedes empezar a escribir pruebas! Jest puede encontrar pruebas de muchas maneras:

• si el nombre del archivo estest.js
• o tiene el prefijo del nombre del archivo que prueba, comomain.test.js
• si son .jsarchivos ubicados en una carpeta llamada__tests__

Cree la __tests__carpeta y dentro de ella, un archivo front.test.js. Puede ver el archivo JavaScript terminado para las pruebas de Jest en el repositorio complementario. Veámoslo en bloques. La primera línea importa el archivo JS que queremos probar:

import { wpJestTestsInit } from '../src/main';

A continuación, borramos todos los simulacros, para que nunca ejecutemos simulacros sucios que contengan valores de pruebas anteriores. Hacer esto puede generar errores ya que, por ejemplo, si estamos espiando cuántas veces se llamó a una función simulada, podríamos obtener una lectura incorrecta si no borramos el simulacro entre prueba y prueba:

La primera prueba que escribiremos hace afirmaciones básicas cuando algunas cosas fallan. Por ejemplo, si la variable global wpJestTestscon la que estábamos escribiendo wp_add_inline_scriptno se escribió por alguna razón:

En este código,

• describecrea un grupo compuesto por varias pruebas relacionadas
• testes lo que realmente realiza una prueba
• expectenvuelve nuestro sujeto de prueba proporcionando acceso a una serie de "coincidencias" que le permiten hacer diferentes afirmaciones sobre su contenido
• toBees uno de estos emparejadores. Jest tiene muchos comparadores incluidos, e incluso hay otros que puedes agregar con un paquete de terceros.

La primera prueba no define nada, por wpJestTestslo que su valor será el que definió en globals.js. Como es undefined, no podemos trabajar, por lo que queremos confirmar que la función regresa sin hacer nada.

La segunda prueba define wpJestTestsy simula el document.querySelectormétodo para devolver undefinedlo que devolvería si no pudiera encontrar un elemento en el DOM. En tal caso, queremos confirmar que estamos regresando sin hacer nada, y que nuestra función de simulación document.querySelectorfue llamada una vez.

Mock fetch en las pruebas de Jest

El siguiente conjunto de pruebas comienza con

y dentro de esto, tenemos otra función de desmontaje:

a diferencia afterEachde esto se ejecutará después de que se hayan ejecutado todas las pruebas dentro de este describebloque. Dado que nuestro archivo JavaScript se usa fetchpara cargar las publicaciones, debemos verificar que se haya llamado y haya devuelto lo que solicitamos, por lo que vamos a simular la fetchfunción:

Simulamos la primera Promesa que se resuelve en la respuesta, y la segunda en una representación JSON de los datos. Estos datos son similares a los que obtenemos de la API REST de WP. Dado que nuestro código solo necesita el título y el enlace, nos estamos burlando de eso.

Prueba de integración de JavaScript con Jest en código asíncrono que usa fetch

Ahora podemos escribir la prueba usando el archivo simulado fetch. Hay una gran diferencia con esta prueba en comparación con otras pruebas unitarias de JavaScript: esta es una prueba de integración. Las pruebas anteriores exploradas aquí simplemente aseguraron que un componente funcionaba bien. Verificamos que si la variable global de estado inicial no estaba definida, nuestro componente no se renderizaría. Esto es diferente porque vamos a probar cómo funciona todo el sistema cuando se define la variable de estado inicial, activando así una transacción de datos y finalmente insertando los títulos de las publicaciones con sus enlaces en el documento.

Desde el principio, esto es diferente: la función anónima pasada a testrecibe un doneparámetro. Esta es en realidad una función que se llamará cuando finalicemos la prueba. Jest esperará hasta doneque se llame antes de terminar la prueba. Si donenunca se llama, la prueba fallará con un error de tiempo de espera. Eso es interesante para nosotros ya que estamos probando código que involucra fetch, que es una función asíncrona.

El global wpJestTestsestá definido y nuestro simulado document.querySelectorahora devuelve lo que se parece a un elemento HTML, con even classListy su addmétodo secundario.

Llamamos wpJestTestsInity esperamos que termine correctamente. Ahora, dado que es asíncrono, fetchvamos a utilizar process.nextTickdesde Node.js. En nextTickNode.js es la cola que se ejecutará después de que hayan finalizado todos los eventos en el bucle de eventos actual. Esto es genial porque todas nuestras promesas se resolverían entonces, que es exactamente lo que necesitamos para probar este código que involucra fetch.

El resto son más afirmaciones para garantizar que se querySelectorencontró algo con lo que trabajar, que de fetchhecho se llamó, que se agregó una clase a la lista y que los títulos y enlaces de nuestras publicaciones se insertaron en el elemento HTML correspondiente. Una vez que todo está hecho, llamamos doney nuestra prueba asíncrona finaliza.

Ejecute sus pruebas Jest

Ahora puedes escribir

npm run test

y Jest ejecutará las pruebas unitarias de JavaScript para su complemento de WordPress

Conclusión

Entonces, Jest es una solución excelente y simple para escribir pruebas que cubran el código JavaScript de nuestros complementos o temas de WordPress. Pero hay más Si estamos escribiendo una aplicación React para nuestro complemento, es posible que queramos hacer afirmaciones al respecto. Jest también puede ayudar hasta cierto punto, y si necesitamos más, podemos agregar Enzyme a nuestras herramientas y comenzar a escribir pruebas de integración con él.

¡Por favor done!

¡Si esto te resultó útil, no dudes en comprarme un café para que pueda mantenerme despierto y crear más tutoriales útiles para ti!

$3.00