JUnit 5 es el framework de pruebas unitarias más utilizado en Java. Permite escribir y ejecutar tests de forma automática, verificando que el código se comporta como se espera. Incluye anotaciones como @Test y @BeforeEach, y assertions como assertEquals y assertThrows. También se integra con AssertJ para aserciones más legibles y con Mockito para crear mocks y stubs.

Pruebas unitarias con JUnit 5 en Java: guía práctica

Última actualización: agosto 2026

Contenido Rápido

• JUnit 5 es el framework de pruebas unitarias para Java
• Usa @Test para marcar métodos de prueba
• @BeforeEach ejecuta código antes de cada test
• Assertions: assertEquals(), assertTrue(), assertThrows()
• Se integra con Mockito para crear mocks y stubs

Comparación rápida: JUnit 4 vs JUnit 5

JUnit 5 es el estándar para escribir pruebas unitarias en el ecosistema Java. En este artículo verás cómo configurarlo con Maven o Gradle, qué módulos y anotaciones incluye, cómo escribir assertions y probar excepciones, y cómo hacer tus aserciones más legibles con AssertJ.

¿Qué es JUnit?

JUnit es el framework de pruebas unitarias más popular en el ecosistema de Java. La versión JUnit 5 contiene una serie de innovaciones interesantes, con el objetivo de admitir nuevas funciones en Java 8 y superior, así como permitir muchos estilos diferentes de prueba.

JUnit 5 dependencias

Configurar JUnit 5.x.0 es bastante sencillo, solo necesitamos agregar la siguiente dependencia:

Maven

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.9.0</version>
    <scope>test</scope>
</dependency>

Gradle

Groovy:

testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.9.0'

Kotlin:

testImplementation("org.junit.jupiter:junit-jupiter-engine:5.9.0")

Arquitectura de JUnit 5

A diferencia de las versiones anteriores de JUnit, JUnit 5 se compone de varios módulos diferentes de tres subproyectos diferentes.

JUnit Platform

La JUnit Platform sirve como base para lanzar marcos de prueba en la JVM. También define la TestEngine API para desarrollar un marco de prueba que se ejecuta en la plataforma. Además, la plataforma proporciona un Lanzador de Consola para iniciar la plataforma desde la línea de comandos y el JUnit Platform Suite Engine para ejecutar un conjunto de pruebas personalizado utilizando uno o más motores de prueba en la plataforma. El soporte de primera clase para JUnit Platform también existe en los IDE populares (IntelliJ IDEA, Eclipse, NetBeans y Visual Studio Code) y herramientas de compilación (Gradle, Maven y Ant).

JUnit Jupiter

Este módulo incluye nuevos modelos de programación y extensión para escribir pruebas en JUnit 5. Las nuevas anotaciones en comparación con JUnit 4 son:

• @TestFactory: denota un método que es una fábrica de pruebas para pruebas dinámicas
• @DisplayName: define un nombre para mostrar personalizado para una clase de prueba o un método de prueba
• @Nested: indica que la clase anotada es una clase de prueba anidada y no estática
• @Tag: declara etiquetas para pruebas de filtrado
• @ExtendWith: registra extensiones personalizadas
• @BeforeEach: indica que el método anotado se ejecutará antes de cada método de prueba (anteriormente @Before)
• @AfterEach: indica que el método anotado se ejecutará después de cada método de prueba (anteriormente @After)
• @BeforeAll: indica que el método anotado se ejecutará antes que todos los métodos de prueba en la clase actual (anteriormente @BeforeClass)
• @AfterAll: indica que el método anotado se ejecutará después de todos los métodos de prueba en la clase actual (anteriormente @AfterClass)
• @Disabled: desactiva una clase o método de prueba (anteriormente @Ignore)

JUnit Vintage

JUnit Vintage proporciona un TestEngine para ejecutar pruebas basadas en JUnit 3 y JUnit 4 en la plataforma. Requiere que JUnit 4.12 o posterior esté añadido en el classpath o en la ruta del módulo (module path).

Ejemplo básico

El siguiente ejemplo proporciona un vistazo a los requisitos mínimos para escribir una prueba en JUnit Jupiter. Las siguientes secciones de este capítulo proporcionarán más detalles sobre todas las funciones disponibles.

import static org.junit.jupiter.api.Assertions.assertEquals;

import ejemplo.util.Calculadora;

import org.junit.jupiter.api.Test;

class MiPrimerJUnitJupiterTests {

    private final Calculadora calculadora = new Calculadora();

    @Test
    void addition() {
        assertEquals(2, calculadora.sumar(1, 1));
    }

}

¿Quieres probarlo sin instalar nada? Ejecuta este código en el Java Playground, el editor online de CodeJa que compila código Java en el navegador.

Anotaciones

@BeforeAll y @BeforeEach

@BeforeEach

@BeforeEach
void init() {
    System.out.println("@BeforeEach - se ejecuta antes de cada método de prueba en esta clase");
}

@BeforeAll

@BeforeAll
static void setup() {
    System.out.println("@BeforeAll - se ejecuta una vez antes de todos los métodos de prueba en esta clase");
}

@DisplayName y @Disabled

@DisplayName

@DisplayName("Prueba individual exitosa")
@Test
void testSimpleTest() {
    System.out.println("Éxito");
}

@Disabled

@Test
@Disabled("Este test está desactivado")
void testVacio() {
}

@AfterEach y @AfterAll

@AfterEach

@AfterEach
void tearDown() {
    System.out.println("@AfterEach - ejecutado después de cada método de prueba.");
}

@AfterAll

@AfterAll
static void despuesDeTodos() {
    System.out.println("@AfterAll - ejecutado después de todos los métodos de prueba.");
}

Assertions y Assumptions

Assertions

JUnit Jupiter viene con muchos de los métodos de aserción (assertions) que tiene JUnit 4 y agrega algunos que se prestan bien para usarse con Java 8 lambdas. Todas las afirmaciones de JUnit Jupiter son métodos estáticos en la clase org.junit.jupiter.api.Assertions.

@Test
void testConExpresionLambda() {
    assertTrue(5 > 4, () -> "5 es más grande que 4");
}

Aunque el ejemplo anterior es trivial, una ventaja de usar la expresión lambda para el mensaje de aserción es que se evalúa de forma perezosa (lazy), lo que puede ahorrar tiempo y recursos si la construcción del mensaje es costosa.

Ahora también es posible agrupar aserciones con assertAll(), que informará cualquier aserción fallida dentro del grupo con un MultipleFailuresError:

@Test
void grupoDeAssertions() {
    int[] nums = {0, 1, 2, 3, 4};
    assertAll("números",
        () -> assertEquals(nums[0], 0),
        () -> assertEquals(nums[3], 3),
        () -> assertEquals(nums[4], 4)
    );
}

Assumptions

Las suposiciones (Assumptions) se utilizan para ejecutar pruebas solo si se cumplen ciertas condiciones. Esto generalmente se usa para condiciones externas que se requieren para que la prueba se ejecute correctamente, pero que no están directamente relacionadas con lo que se está probando.

Podemos declarar una suposición con assumeTrue(), assumeFalse() y assumingThat():

@Test
void trueAssumption() {
    assumeTrue(5 > 1);
    assertEquals(5 + 2, 7);
}

@Test
void falseAssumption() {
    assumeFalse(5 < 1);
    assertEquals(5 + 2, 7);
}

@Test
void assumptionThat() {
    String cadena = "Un string";
    assumingThat(
        cadena.equals("Un string"),
        () -> assertEquals(2 + 2, 4)
    );
}

Si una suposición falla, se lanza una excepción TestAbortedException y la prueba simplemente se omite.

Testeando excepciones

Hay dos formas de probar excepciones en JUnit 5, las cuales podemos implementar usando el método assertThrows():

@Test
void tirarExcepcionTest() {
    Throwable exception = assertThrows(UnsupportedOperationException.class, () -> {
      throw new UnsupportedOperationException("No soportada");
    });
    assertEquals("No soportada", exception.getMessage());
}

@Test
void controlarExcepcionTest() {
    String str = null;
    assertThrows(NumberFormatException.class, () -> {
      Integer.valueOf(str);
    });
}

AssertJ: aserciones más legibles

AssertJ es una librería de aserciones que se usa junto a JUnit 5 para escribir comprobaciones más legibles. En lugar de los métodos estáticos de Assertions, AssertJ ofrece assertThat(), que devuelve un objeto de aserción sobre el que puedes encadenar comprobaciones. Así el test se lee casi como una frase: assertThat(x).isEqualTo(2).

Para usarla, añade la dependencia assertj-core al classpath de test:

testImplementation 'org.assertj:assertj-core:3.24.2'

Con assertThat() puedes comprobar valores y encadenar varias aserciones sobre el mismo objeto:

import static org.assertj.core.api.Assertions.assertThat;

import ejemplo.util.Calculadora;

import org.junit.jupiter.api.Test;

class CalculadoraAssertJTests {

    private final Calculadora calculadora = new Calculadora();

    @Test
    void sumaConAssertJ() {
        assertThat(calculadora.sumar(1, 1)).isEqualTo(2);
    }
}

import static org.assertj.core.api.Assertions.assertThat;

import java.util.List;

import org.junit.jupiter.api.Test;

class ListaAssertJTests {

    @Test
    void listaConAssertJ() {
        List<String> lista = List.of("a", "b");
        assertThat(lista).hasSize(2).contains("a");
    }
}

Preguntas Frecuentes

¿Qué es JUnit 5?

JUnit 5 es el framework de pruebas unitarias más utilizado en Java. Permite escribir y ejecutar tests de forma automática con anotaciones como @Test y assertions como assertEquals. Se compone de tres subproyectos: JUnit Platform, JUnit Jupiter y JUnit Vintage.

¿Cuál es la diferencia entre JUnit 4 y JUnit 5?

JUnit 5 se compone de varios módulos de tres subproyectos diferentes, mientras que JUnit 4 era una única librería. Jupiter renombra anotaciones como @Before a @BeforeEach y @Ignore a @Disabled, y añade otras nuevas como @TestFactory, @DisplayName y @Nested. Además, admite Java 8 y superior con lambdas en las assertions.

¿Qué es la JUnit Platform?

La JUnit Platform sirve como base para lanzar marcos de prueba en la JVM. Define la TestEngine API para desarrollar marcos de prueba que se ejecutan en la plataforma y proporciona un Lanzador de Consola junto al JUnit Platform Suite Engine para ejecutar conjuntos de pruebas personalizados.

¿Cómo probar excepciones en JUnit 5?

Con el método assertThrows(), indicando la clase de la excepción esperada y una expresión lambda con el código que la lanza. El método devuelve la excepción lanzada, sobre la que puedes comprobar atributos como el mensaje con assertEquals.

¿Qué es AssertJ y cómo se usa con JUnit 5?

AssertJ es una librería de aserciones fluida que complementa a JUnit 5. Usa assertThat() para encadenar comprobaciones legibles, como assertThat(lista).hasSize(2).contains("a"). Para usarla solo necesitas añadir la dependencia assertj-core al classpath de test.

Artículos Relacionados

• Mockito para Pruebas Unitarias en Java
• Método main() en Java: Punto de Entrada Explicado
• Try Catch Finally en Java: Manejo de Excepciones