Asercje JUnit - Pisz lepsze testy, unikaj typowych błędów

W testach jednostkowych w Javie asercje decydują o tym, czy test mówi coś konkretnego, czy tylko „przeszedł”. Dla porządku: zapytanie junit assert najczęściej prowadzi do jednego tematu - jak poprawnie używać asercji w JUnit 5, żeby testy były czytelne, szybkie w diagnozie i sensowne w automatyzacji. W tym tekście pokazuję, jak działają najważniejsze metody, kiedy wybrać każdą z nich i jakie błędy najczęściej psują wartość testów.

Jak czytać asercje w JUnit i po co one naprawdę są

W praktyce asercja to kontrakt testu: „jeżeli kod zachowuje się poprawnie, ten warunek musi być spełniony”. Gdy warunek nie przechodzi, JUnit przerywa test przez AssertionError, dzięki czemu pipeline CI dostaje jednoznaczny sygnał, że coś się zepsuło. Ja traktuję to jako punkt kontrolny między zachowaniem aplikacji a oczekiwaniem biznesowym, a nie jako zwykłe „sprawdzenie wartości”.

W JUnit 5 wszystkie główne metody są dostępne jako statyczne wywołania z Assertions. To ważne, bo czytelny test zwykle zaczyna się od statycznych importów, a kończy na krótkich, konkretnych porównaniach. Dokumentacja JUnit 5 podkreśla też, że komunikat błędu jest opcjonalny i może być przekazany jako String albo Supplier, więc przy droższych komunikatach można uniknąć zbędnego budowania tekstu, jeśli test przechodzi.

Jest jeszcze jedna praktyczna różnica, którą dobrze znać przy migracji z JUnit 4: w Jupiterze argument z komunikatem zwykle stoi na końcu, a nie na początku listy parametrów. To drobiazg, ale w starych testach bywa źródłem nieporozumień i przypadkowych błędów przy refaktoryzacji. Z tego powodu od początku warto pisać testy w stylu, który nie wymaga późniejszego „rozplątywania” sygnatur.

Gdy ten fundament jest jasny, łatwiej wybrać właściwą metodę do konkretnego scenariusza.

Najczęściej używane asercje i kiedy po nie sięgam

W codziennej automatyzacji testów nie potrzebuję całego katalogu metod. Najczęściej wracam do kilku podstawowych asercji, które pokrywają większość przypadków w testach jednostkowych i kontraktowych. Poniżej zestawiam je tak, jak sam patrzę na nie podczas pisania testów: nie jako encyklopedię, tylko jako narzędzia do różnych typów ryzyk.

Właśnie tutaj najlepiej widać, że asercje nie są zamiennikami dla siebie nawzajem. Każda rozwiązuje inny problem: jedne porównują wartości, inne pilnują błędów, jeszcze inne mierzą czas albo grupują wyniki. Jeżeli dobierzesz metodę do ryzyka, test staje się prostszy do utrzymania. Następny krok to już samo pisanie testu tak, żeby ten wybór był widoczny od pierwszego spojrzenia.

Jak pisać testy, które zostają czytelne po pół roku

Ja w testach lubię zasadę: jedna metoda testowa, jedno zachowanie, ale niekoniecznie tylko jedna asercja. Jeśli sprawdzam jeden scenariusz biznesowy, mogę mieć kilka sprawdzeń wewnątrz tego samego testu, o ile wszystkie opisują ten sam efekt. Wtedy assertAll jest naturalnym wyborem, bo nie urywa diagnozy po pierwszym niepowodzeniu.

import static org.junit.jupiter.api.Assertions.assertAll;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertThrows;

import org.junit.jupiter.api.Test;

class RegistrationServiceTest {

    private final RegistrationService service = new RegistrationService();

    @Test
    void shouldCreateUserWithConsistentData() {
        User user = service.register("anna.kowalska@example.pl", "Anna", "Kowalska");

        assertAll("user",
            () -> assertEquals("Anna", user.firstName()),
            () -> assertEquals("Kowalska", user.lastName()),
            () -> assertNotNull(user.id())
        );
    }

    @Test
    void shouldRejectInvalidEmail() {
        IllegalArgumentException exception = assertThrows(
            IllegalArgumentException.class,
            () -> service.register("zly-email", "Anna", "Kowalska")
        );

        assertEquals("Invalid email", exception.getMessage());
    }
}

Taki styl daje dwie korzyści. Po pierwsze, test mówi wprost, co jest ważne z punktu widzenia zachowania systemu. Po drugie, gdy coś pęknie, otrzymujesz więcej niż jedną informację diagnostyczną, więc nie musisz odpalać testu po każdym drobnym poprawieniu. To ma duże znaczenie w automatyzacji, gdzie szybkość diagnozy bywa ważniejsza niż sama liczba testów.

Jeśli komunikat błędu jest kosztowny do zbudowania albo zawiera sporo danych pomocniczych, używam dostawcy Supplier. To drobny detal, ale przy większych zestawach testów chroni przed niepotrzebnym składaniem długich napisów w scenariuszach, które i tak kończą się sukcesem. W praktyce to dobra reguła: komunikat ma pomagać po porażce, nie spowalniać codziennych zielonych przebiegów.

Przy takim podejściu szybko wychodzą też błędy, które nie są problemem samego JUnit, tylko sposobu pisania testów.

Typowe błędy, które obniżają wartość testów

Najczęstszy błąd, jaki widzę, to używanie niewłaściwej asercji do niewłaściwego problemu. Ktoś pisze assertTrue(a.equals(b)), gdy powinien użyć assertEquals, albo sięga po assertSame, chociaż test ma sprawdzać równoważność, a nie tożsamość obiektu. To drobiazg tylko z pozoru, bo zła asercja utrudnia diagnozę i zaciera intencję testu.

• Sprawdzanie implementacji zamiast zachowania. Test powinien weryfikować rezultat widoczny z zewnątrz, a nie prywatne szczegóły, które zmienią się przy pierwszym refaktorze.
• Testowanie wyjątku tylko po typie. Sam typ często nie wystarcza, jeśli znaczenie ma także komunikat lub stan obiektu po błędzie.
• Ignorowanie ryzyk przy timeoutach. assertTimeoutPreemptively wykonuje kod w innym wątku, więc przy mechanizmach opartych o ThreadLocal albo transakcjach może dać wyniki, które wyglądają poprawnie tylko na papierze.
• Brak jasnego rozróżnienia między równością a identycznością. assertEquals i assertSame rozwiązują dwa różne problemy, a ich pomieszanie prowadzi do testów, którym nie można ufać.
• Zbyt ogólne komunikaty. Krótkie „should work” nie pomaga po porażce. Lepiej opisać, co dokładnie miało się wydarzyć, nawet jeśli komunikat ma zostać użyty rzadko.

Jeżeli ma to dotyczyć całego testu, a nie jednego fragmentu, czasem lepszym wyborem jest adnotacja @Timeout niż asercja czasowa w środku metody. Wtedy reguła jest bardziej deklaratywna i łatwiej ją utrzymać, zwłaszcza w większych zestawach testów. Z takimi błędami najłatwiej walczyć, kiedy w zespole jest jasne, co zmieniło się między JUnit 4 a JUnit 5.

Co zmienia przejście z JUnit 4 na JUnit 5

W migracji najwięcej problemów nie robi sama logika testów, tylko API i przyzwyczajenia. JUnit 5 uporządkował asercje w org.junit.jupiter.api.Assertions, dodał kilka bardzo praktycznych metod i zmienił niektóre sygnatury tak, żeby komunikat był ostatnim argumentem. To ma sens projektowy, ale przy ręcznym przenoszeniu kodu łatwo o bałagan importów i subtelne pomyłki.

W praktyce migracja jest prostsza, jeśli nie próbujesz przepisać wszystkiego naraz. Ja zwykle zaczynam od importów, potem porządkuję testy wyjątków i dopiero na końcu dotykam bardziej złożonych przypadków, takich jak timeouty czy grupowanie asercji. To ogranicza ryzyko, że w trakcie migracji przestaniesz ufać samym testom.

Kiedy zespół już pracuje na Jupiterze, pojawia się jeszcze jedno pytanie: czy same asercje JUnit wystarczą na dłuższą metę.

Kiedy same asercje nie wystarczą

JUnit pokrywa bardzo dużo scenariuszy, ale nie każdy problem da się wygodnie opisać jego natywnymi metodami. Gdy porównujesz złożone obiekty, kolekcje albo chcesz bardziej płynnego, naturalnego języka testów, rozsądne staje się sięgnięcie po zewnętrzne biblioteki. Sam JUnit wprost rekomenduje takie rozwiązania jak AssertJ, Hamcrest czy Truth, jeśli potrzebujesz matcherów albo bardziej ekspresyjnego stylu.

• Gdy test porównuje wiele pól zagnieżdżonych obiektów i zwykłe assertEquals robi się mało czytelne.
• Gdy chcesz pisać asercje w stylu fluent, czyli krok po kroku, bez nadmiaru szumu składniowego.
• Gdy potrzebujesz bardziej opisowych komunikatów błędu niż to, co daje natywne API.
• Gdy w projekcie rośnie liczba własnych helperów do porównywania tych samych struktur.

Ja podchodzę do tego pragmatycznie: jeśli dodatkowa biblioteka skraca test i poprawia jego zrozumiałość, ma sens. Jeśli jednak zaczyna dublować prostą logikę i wprowadza dodatkową warstwę, zostaję przy JUnit. W automatyzacji najważniejsze jest nie to, żeby użyć najbardziej rozbudowanego narzędzia, ale żeby test szybko i jednoznacznie powiedział, co działa, a co nie.

To prowadzi do ostatniego punktu, który traktuję bardziej jak standard zespołowy niż techniczny detal.

Co warto zostawić w zespole jako prosty standard

• Używaj JUnit 5 jako domyślnego API, a stare testy migruj stopniowo, nie chaotycznie.
• Dobieraj asercję do rodzaju ryzyka: wartość, wyjątek, tożsamość, czas, kolekcja, stan obiektu.
• Sprawdzaj kilka niezależnych pól przez assertAll, zamiast rozbijać jeden scenariusz na wiele niezależnych testów bez potrzeby.
• Do limitów czasowych podchodź ostrożnie, szczególnie gdy kod korzysta z mechanizmów wrażliwych na wątek, takich jak ThreadLocal.
• Jeśli test staje się trudny do czytania, uprość go albo przenieś bardziej ekspresyjne porównania do biblioteki zewnętrznej.

Jeżeli mam zostawić jedną praktyczną wskazówkę, to tę: wybieraj asercję zgodną z intencją testu, nie tylko z wynikiem, który chcesz porównać. To właśnie ta decyzja najczęściej odróżnia test, który naprawdę pomaga w automatyzacji, od testu, który tylko istnieje.