Marklogic - Tests Unitarios con xray

Marklogic -  Tests Unitarios con xray

Descripción

Esta guía pretende explicar de manera detallada como utilizar las herramientas básicas que ofrece la librería de Test Unitarios xray ( https://github.com/robwhitby/xray ). Para esto vamos a realizar el paso a paso de la instalación de esta librería en un entorno Marklogic y vamos a explicar como utilizar esta librería en los diferentes proyectos.

Agenda

1. Pre-requisitos
2. Instalación
3. Marklogic, XQuery y xray
4. Ejemplo
5. Conclusiones

1. Pre-requisitos

Para el correcto entendimiento de esta guía debes tener previos conocimientos en el entorno de Marklogic y su lenguaje de programacion XQuery. Si no tienes idea de lo que estoy hablando, te invito a que visites la pagina de tutoriales y guias que ofrece Marklogic.

Se debe tener el código fuente de xray el cual se puede descargar desde el sitio oficial https://github.com/robwhitby/xray.

Debes tener instalado Marklogic, para esta libreria necesitas la version 6.0 o mayor.

2. Instalación

Para iniciar la instalación de la librería xray necesitamos un HTTP server en Marklogic, para esto nos dirigimos al servidor de administración de Marklogic ( http://localhost:8001 ) en la opción 

Groups->Default->App Servers->Create HTTP

 Cuando hayas dado click a esta opción vas a ver el formulario para crear el HTTP, ingresamos los datos del servidor que mas concuerden con tu gusto y con los puertos libres que poseas (ver Imagen 1). Para este ejemplo yo tengo los siguientes datos (los demás datos no son relevantes):

• Server name : xray-http-server
• root : /Users/fabianjaramillo/XQuery/xray
• port : 9000

Imagen 1

Como se puede ver en la imagen, yo descargue el zip de la pagina oficial de xray y lo descargue en la carpeta xray ubicada en "/Users/fabianjaramillo/XQuery/xray" de mi equipo. Esta carpeta debe contener exactamente como lo muestra la imagen a continuación (ver Imagen 2).

Imagen 2

Esta es la estructura de archivos que al descomprimir el zip de xray deben obtener, para nuestro ejemplo vamos a modificar esta estructura y la carpeta finalmente debe lucir así (ver Imagen 3).

Imagen 3

Con todo esto verificado ya solo resta presionar el botón de "ok" y Marklogic creara el servidor, esto puede fallar si el puerto que se le asigno esta siendo ocupado por otro proceso o aplicación. Con este proceso completado ya tendras instalado un servidor HTTP corriendo en el puerto que hayas designado, en mi caso el puerto 9000 corriendo con la libreria de xray para Tests Unitarios con XQuery.

3. Marklogic, XQuery y xray

Marklogic es el entorno que nos permite correr los servidores HTTP con XQuery y sus multiples funcionalidades de manejo, control y transformacion de documentos XML. En este entorno lo primordial es la estructura de nuestros documentos, por tanto xray se convierte en una herramienta muy util a la hora de realizar Test Unitarios para los proyectos que estemos desarrollando sobre Marklogic. 

xray es una librería que esta bajo la licencia Apache 2.0, que esta escrita en XQuery y de la cual pueden encontrar más información en su pagina oficial https://github.com/robwhitby/xray. Esta librería nos permite construir Tests Unitarios de manera muy fácil y organizada, ya que posee la opción de evaluar una carpeta y realizar todos los tests que en ella se encuentren. Habilidad que nos permite mantener los tests organizados por módulos, paginas, archivos, funcionalidad, etc.

xray nos permite realizar diferentes tipos de evaluaciones por tipo, por valor, por namespace, por tipo de transacción, etc. Con todas las posibilidades que ofrece nos deja un campo muy grande respecto a lo que debemos evaluar en nuestros proyectos. Es por ese motivo que yo recomiendo empezar evaluando las estructuras que esperamos deben retornar nuestros procesos, para ir conociendo la librería y luego proceder con evaluaciones de procesos mas complejos que incluyan lógica de negocio y comandos propios de Marklogic.

4. Ejemplo

Para nuestro ejemplo vamos a usar la creación de un usuario como contexto de nuestras pruebas unitarias y vamos a enfocarnos en evaluar las estructuras resultantes de nuestro proceso. Para aterrizar un poco mas el ejemplo voy a redactar un pequeño requerimiento, del cual luego procederemos a realizar el Test Unit que finalmente ejecutaremos en la consola de Marklogic.

Requerimiento: Permitir crear usuarios en el sistema incluyendo toda la información relevante que a continuación se detalla:

• Nombre
• Apellido
• Edad
• Telefono
• Ciudad
• Contraseña
• Usuario

Codigo

xquery version "1.0-ml";

module namespace test = "http://github.com/robwhitby/xray/test";
import module namespace assert = "http://github.com/robwhitby/xray/assertions" at "/src/assertions.xqy";

declare namespace xray = "http://github.com/robwhitby/xray";
import module namespace utils = "utils" at "utils.xqy";


(: all public functions are evaluated by the test-runner :)
declare %test:case function user-create-tests()
{
  let $nombre        := "Fabián"
  let $apellido        := "Jaramillo"
  let $edad             := 25
  let $telefono        := "300-6554-9854"
  let $ciudad          := "Medellin"
  let $contraseña   :=  xdmp:crypt2("123abc")
  let $user              := "fabjaror"
 
  let $user-model  := user:create-user($nombre,$apellido,$edad,$telefono,$ciudad,$user,$contraseña)
  let $user-exists   := //users/user[username eq $user]
 
  return (
    

    assert:not-empty($user-model/ID, "No se pudo crear el usuario"),
    assert:equal(fn:data($user-model/name), $nombre),
    assert:equal(fn:data($user-model/lastname), $apellido),
    assert:equal(fn:data($user-model/age), $edad),
    assert:equal(fn:data($user-model/phone), $telefono),
    assert:equal(fn:data($user-model/city), $ciudad),
    assert:equal(fn:data($user-model/username), $user),
    assert:equal(fn:data($user-model/pass), $contraseña),
    assert:not-equal(fn:data($user-exists/username), $user, "El usuario ya existia en la base de datos")

  )
};

5. Conclusiones

En proyectos elaborados con Marklogic y XQuery aun falta mucho terreno por recorrer en cuanto a mejores practicas, pero esta herramienta de xray nos acerca un poco al modelo normal de programación y de pruebas unitarias que tienen otros lenguajes mas robustos como .NET, Java, C++, etc. 

Aprovecha el uso de esta herramienta y ten en cuenta que no a todo se le puede generar pruebas unitarias y que para el caso particular de Marklogic yo recomiendo aplicar las pruebas inicialmente a las estructuras y luego ir avanzando para agregar procesos lógicos y funciones de Marklogic.

Si tienes preguntas, dudas o sugerencias por favor crea un comentario y te prometo que le daré respuestas lo mas pronto posible.