Tutorial JUnit Matchers. Tutorial JUnit Hamcrest.

JUnit Matchers. Hamcrest lib.

---

Hamcrest es una librería basada en Matchers para poder hacer nuestras pruebas unitarias en JUnit mucho mas fuertes, esta librería incluso nos permite hacer pruebas equivalentes a cualquier método assert o assume, el lenguaje en el cual hacemos las pruebas unitarias es mas legible y los mensajes de error son mas descriptivos.

En este tutorial te voy hablar acerca de los org.hamcrest.CoreMatchers que son los más usados de esta librería para nuestras pruebas unitarias en JUnit, primero lo que tenemos que hacer es tener un poco de conocimiento acerca de:

• JUnit.
• JUnit Assert.

Por lo menos para comprender un poco mas esta librería. Ahora si, mira este tutorial y aprende mas!

Estos son los Matchers que posee la librería Hamcrest, específicamente org.hamcrest.CoreMatchers:

Matcher	Descripción
allOf(matcher, matcher, ..)	Es un Matcher en el cual se pueden evaluar varios Matchers en sus parámetros y solo coincide si el objeto examinado es igual a TODOS los Matchers.
any(java.lang.Class type)	Es un Matcher en el cual se evalúa si el objeto examinado es una instancia de ese tipo.
anyOf(matcher, matcher, ..)	Es un Matcher en el cual se pueden evaluar varios Matchers en sus parametros y solo coincide si el objeto examinado es igual a CUALQUIERA de los Matchers.
anything()	Es un Matcher en el cual el objeto examinado siempre coincidirá independientemente del objeto examinado.
equalTo()	Es un Matcher en el cual hacemos la comparación lógica del objeto examinado.
instanceOf(java.lang.Class<?> type)	Es un Matcher en el cual se evalúa si la clase examinada es una instancia de ese tipo.
is()	Es un Matcher en el cual se puede evaluar objetos, tipo de clases, valores y otro Matcher envuelto.
not()	Es un Matcher en el cual se puede evaluar objetos, tipo de clases, valores y otro Matcher envuelto. Es lo inverso al is().
notNullValue()	Es un Matcher en el cual se puede confirmar que un objeto o una clase no estan null.
nullValue()	Es un Matcher en el cual se puede confirmar que un objeto o una clase estan null.

Ok los Matcher que están en la tabla de arriba se pueden usar de distintas formas, con muchas variables, eso es lo que hace que cuando estamos implementando nuestras pruebas unitarias las hagamos más fuertes y por ende a menor riesgo de error. Para implementar la librería Hamcrest vamos a usar el método de JUnit assertThat que es el que trabaja con Matcher. Para este tutorial la clase donde vamos a crear las pruebas unitarias tiene que importar

 import org.hamcrest.CoreMatchers;

y aparte la clase tiene que extender de CoreMatchers

 public class DatojavaJUnitTest extends CoreMatchers

Te dejo los ejemplos de org.hamcrest.CoreMatchers para que los pongas en práctica:

allOf:

Como comente en la parte de arriba este Matcher puede evaluar varios Matcher envueltos en sus parámetros. Supongamos que tenemos este método que devuelve una suma de dos números.

 public int sumar(int num1, int num2) {
  return num1 + num2;
 }

Podríamos hacer esto:

 @Test
 public void testHamcrestAllOf() {
  int resultado = 18;
  assertThat(resultado, allOf(is(18), is(sumar(10, 8)), not(29)));
  // Coincide si:

  // resultado = 18       ---is(18)
  // resultado = 10 + 8   ---sumar(10, 8)
  // resultado != 29      ---not(29)
 }

Explicando un poco el código de arriba, estamos examinando la variable resultado, en este caso el objeto examinado coincide con todos los Matcher que los estamos evaluando y pasa la prueba.

any:

Como explique en la descripción este se utiliza para ver si el objeto examinado es del tipo especifico. Por ejemplo:

 @Test
 public void testHamcrestAny() {
  assertThat(new DatojavaJUnitTest(), any(DatojavaJUnitTest.class));
 }

Estoy diciendo que la clase es una instancia de la DatojavaJUnitTest que es el nombre de la clase en este tutorial. Este Matcher se utiliza más que todo para examinar tipos genéricos. Por ejemplo:

 @Test
 public void testHamcrestAny() {
  int numero = 0;
  assertThat(0, any(Integer.class));
 }

Las dos pruebas unitarias coinciden así que pasa sin problemas.

anyOf:

Este Matcher es parecido al allof() solo que no examina el objeto y si coincide por lo menos con alguno de los Matcher pasa la prueba. Por ejemplo:

 @Test
 public void testHamcrestAnyOf() {
  int numero = 98;

  assertThat(
    "No coincide con ningun Matcher",
    numero,
    anyOf(is(9 + 8), is(not(98)), is(nullValue()),
      allOf(is(sumar(1, 98)), is(not(98)))));

  // numero = 9 + 8                                 --- is(9 + 8)
  // numero != 98                                   --- is(not(98))
  // numero = null                                  --- is(nullValue())
  // ((numero = 1 + 98) && (numero != 98)) --- allOf(is(sumar(1, 98)), is(not(98)))
 }

Si analizamos el código anterior vamos a darnos cuenta que la prueba falla porque el objeto examinado no coincide con ningun Matcher, ahora vamos a ver lo descriptivo del mensaje de error de Hamcrest.

anyOf Matcher fail

Esa descripción está bien explicada, esa es una de las ventajas de Hamcrest frente a los métodos convencionales de JUnit.

anything:

Este no se usa mucho ya que siempre coincidirá el objeto examinado no importa lo que le pongas siempre pero siempre va a coincidir. Si también me pregunto para qué lo crearon jajajaja...

 @Test
 public void testHamcrestAnything(){
  String web = "DatoJava";
  assertThat(web, anything());
 }

Siempre pasa la prueba unitaria.

equalTo:

Este método es el que siempre utilizamos para decir lógicamente que un objeto a = a. Este Matcher tiene un comportamiento especial en cuanto a arreglos se refiere, para que un arreglo coincida con otro tiene que ser exactamente igual, los elementos tienen que estar en el mismo índice, es sensible a mayúsculas y minúsculas. Por ejemplo:

 @Test
 public void testHamcrestEqualTo() {
  String[] frameworks = { "JSF", "Primefaces", "ADF", "Quartz" };
  String[] frameworksA = { "JSF", "PRimefaces", "ADF", "Quartz" };

  assertThat("Los arreglos son distintos:", frameworks,
    equalTo(frameworksA));
 }

Fíjense que solo tiene una letra en mayúscula y esto es lo que pasa a la hora de ejecutar la prueba unitaria:

equalTO Matcher fail

instanceOf:

Verificamos si un objeto es una instancia de una clase específica:

 @Test 
 public void testHamcrestInstanceOf(){
  int numero = 9;
  assertThat(numero, instanceOf(Number.class));
 }

La prueba unitaria pasa porque la clase java.lang.Integer extiende de java.lang.Number.

is:

Sin lugar a dudas uno de los más usados de Hamcrest por su potencial y simplicidad, no olvidemos que este Matcher se puede usas con otro Matcher envuelto dentro del, en ese sentido la lógica del mismo de invierte tomando en cuenta si coincide el objeto examinado con el Matcher envuelto en el, en los ejemplos anteriores ya hemos visto como se puede usar, pero igual a poner más ejemplos:

 @Test
 public void testHamcrestIs() {
  String nombre = "DatoJava";

  // Comparando el lengh de un String
  assertThat(nombre.length(), is(8));

  // Comparando con otro Matcher envuelto
  assertThat(nombre, is(notNullValue()));

  // Comparando el valor directo
  assertThat(nombre, is("DatoJava"));

  // Dentro del "is()" hay un Matcher envuelto que a su vez tiene otro
  // Matcher envuelto ya en este caso la logica cambia
  assertThat(nombre, is(not(instanceOf(Integer.class))));
 } 

Como vemos hay distintos usos del is(), esas son sus variables ya los puedes combinar de distintas maneras y crear una prueba unitaria súper fuerte.

not:

También se utiliza como el is(), dependiendo de cómo lo utilizamos se puede invertir la lógica. Vamos a utilizar el mismo ejemplo del is():

 @Test
 public void testHamcrestNot() {
  String nombre = "DatoJava";

  // Comparando el lengh de un String
  assertThat(nombre.length(), not(9));

  // Comparando con otro Matcher envuelto
  assertThat(nombre, not(nullValue()));

  // Comparando el valor directo, es sensible a mayusculas
  assertThat(nombre, not("DATOJAVA"));

  // Dentro del "is()" hay un Matcher envuelto que a su vez tiene otro
  // Matcher envuelto ya en este caso la logica cambia
  assertThat(nombre, not(is(instanceOf(Integer.class))));
 }

Como dije anteriormente es casi el mismo ejemplo anterior, por la similitud que tienen is() y not() es que utilice el mismo ejemplo pero de otra manera, si estas siguiendo el tutorial "eres tú" y sabes que no hay mas nada que hacer con este Matcher jajaja...

notNullValue:

Ya hemos utilizado este notNullValue() para hacer ejemplos más arriba, no está de más explicar que este Matcher viene reemplazando lo que anteriormente se usaba así:

   assertThat(nombre, is(not(nullValue)));
  

Un ejemplo:

 @Test
 public void testHamcrestNotNullValue() {
  String nombre = "DatoJava";

  // No es necesario ningún otro Matcher para chequear el objeto
  assertThat(nombre, notNullValue());
 }
  

nullValue:

Este es lo opuesto del notNullValue(), esta de mas decir eso, te voy a poner el ejemplo por si acaso tienes alguna duda :)..

 @Test
 public void testHamcrestNullValue() {
  String nombre = null;

  // No es necesario ningún otro Matcher para chequear el objeto
  assertThat(nombre, nullValue());
 }

Sin más nada que hacer en este dato java espero hallas podido ver las bondades de esta poderosa librería, créeme que tendrás que usarla bastante si quieres hacer de tus pruebas unitarias las mejores!! No te olvides de comentar y decir gracias por lo menos jajaja...

Temas Relacionados:

• JUnit Tutorial Eclipse/JBoss Developer Studio.
• JUnit Assert Tutorial.
• JUnit Assume Tutorial.
• JUnit Suite.
• Pruebas parametrizadas en JUnit.