The previous lesson left CicloUrbana with one test: StandardFareTest, twelve lines stating that thirty minutes cost €4.10. It served to illustrate the Arrange-Act-Assert pattern, but it is plainly not enough. Ribalta has three fares, each with its own allowance of free minutes, and the cases that matter are the boundaries: zero minutes, exactly fifteen, exactly thirty. Writing twelve almost identical classes would be the worst possible route.

This lesson fills the base of the pyramid with the right tool. We will look at the architecture of JUnit 5, the annotation catalogue with its lifecycle demonstrated at run time, AssertJ in depth —the assertion style of the whole course— with its BigDecimal traps and its soft assertions, parameterised tests applied to Ribalta's fares in a single readable class, organising by scenario with @Nested, the Clock.fixed that makes a rental duration calculation deterministic, and good practice for test data. All of it without starting the Spring context even once: it is not needed here, and that is precisely the lesson.

1. The architecture of JUnit 5
2. The core annotations and their lifecycle
3. AssertJ: why it is the style of this course
4. The assertion catalogue by type
5. Exceptions and soft assertions
6. Parameterised tests
7. The parameterised FareCalculator
8. Organising with @Nested, @DisplayName and @Tag
9. Testing time-dependent code
10. @TempDir, assumptions and @RepeatedTest
11. StationService without Spring
12. Test data: Object Mother and builders
13. Common Mistakes and Tips
14. Exercises

JUnit 5 is not a library, it is three modules with separate responsibilities:

The separation has a practical consequence: the Platform can run several engines at once, so a project mid-migration runs Jupiter and Vintage in the same build. CicloUrbana was born on JUnit 5, so Vintage is not on the classpath and must not be added: all it does is drag debt along.

The associated mistake you will meet most often: mixing org.junit.Test (JUnit 4) with org.junit.jupiter.api.Test (JUnit 5) in the same file. The test compiles and is never run, without warning. If a method "does not show up" in the report, look at the import before anything else.

The point that surprises anyone coming from JUnit 4 is the second box: JUnit creates a new instance of the test class for every @Test method. It is deliberate isolation: a field one test modifies will not be seen by the next, because the next one runs on a different object. This test proves it:

What matters is in two numbers: counter is 1 in both tests, not 1 and 2, and the hashCode is different, which is the cause. That is the independence guarantee everything else rests on; the execution order is deterministic but it is not the order in the file, and it must never matter.

Two details with consequences. @BeforeAll and @AfterAll must be static, precisely because there is no instance that outlives a single test; there is an alternative, @TestInstance(Lifecycle.PER_CLASS), which this course does not use because it opens the door to one test's state contaminating the next. And a @Disabled with no reason is accumulated rubbish: write @Disabled("Blocked by CU-412; re-enable once it is fixed"), or the test will stay switched off forever while giving the impression that something is covered.

The TestInfo parameter in the example is no accident: JUnit 5 injects method parameters through resolvers, and it is the same mechanism with which @ExtendWith(MockitoExtension.class) will inject the mocks in 06-03.

JUnit brings its own assertions and they work. AssertJ, also included in spring-boot-starter-test, does the same job far better:

Swapping the arguments produces messages that lie: assertEquals(amount, new BigDecimal("4.10")) reports "expected: 5.00 but was: 4.10", the wrong way round, and off you go debugging. With AssertJ the mistake is impossible. Course rule: every assertion is written with AssertJ; the only exception is Hamcrest inside jsonPath(...) in MockMvc (06-04), because that API demands it.

General objects:

usingRecursiveComparison() solves a real problem: the JPA entities of 04-03 define equals by identifier, so isEqualTo would say two stations with the same id are equal even if one has had its name changed. The usual form is assertThat(saved).usingRecursiveComparison().ignoringFields("id", "version", "createdAt", "updatedAt").isEqualTo(expected), ignoring whatever the database assigns.

Strings and numbers:

BigDecimal: the trap to commit to memory.

BigDecimal.equals compares value and scale: 4.1 has scale 1 and 4.10 has scale 2, so they are not equals even though compareTo returns 0. Since isEqualTo uses equals, a correct test can fail merely because the calculation produced one more decimal place. With money, always isEqualByComparingTo. In CicloUrbana that affects every amount and every fare.

Optional and collections, where AssertJ is peerless:

The difference between the content methods is always forgotten:

And on maps, applied to the FareSelector of 02-02, assertThat(selector.available()).hasSize(3).containsKeys("standard", "student", "senior").doesNotContainKey("StandardFare") verifies the whole registry at once and, with that last clause, the failure of forgetting name() on a new fare.

Three ways of verifying a failure, in order of preference:

Checking the code —the stable field of CicloUrbanaException from 03-06— is what turns the assertion into a verification of the contract with the API client. The dangerously weak assertion is isInstanceOf(RuntimeException.class): any accidental NullPointerException satisfies it and paints the test green.

Soft assertions. When a test has several assertions, the first one that fails hides the rest: you fix one, run again, the second fails. assertSoftly evaluates them all:

They are ideal for verifying a single composite object: one concept expressed across several fields. They are not a licence to cram five unrelated checks into one test.

A parameterised test runs the same method with different data. It is the answer to the problem the lesson opened with, and junit-jupiter-params already comes in the starter.

The name attribute deserves attention: without it the report shows [1], [2], [3]; with it, "a capacity of -5 docks must be rejected". The placeholders are {0}, {1}... for the arguments, {index} for the case number and {displayName}.

The lesson's central example: Ribalta's three fares, with their rules and their boundaries, in one single readable class. The rules from 02-02:

What makes this design good:

• The boundary cases of each allowance sit together and in plain sight: 14, 15 and 16 minutes for the student; 30 and 31 for the senior. Reading the list you can see the boundary is inclusive. It is the living documentation of 06-01 in its purest form.
• @CsvSource converts automatically from "4.10" to BigDecimal, from "30" to long and from "MAINTENANCE" to the enum constant (for your own types there is @ConvertWith), and @MethodSource is the source for complex objects: its method must be static, except under Lifecycle.PER_CLASS.
• A failure pinpoints the exact case: the report will say [5] student: 16 min -> €0.08, not "the fare test failed".

When the list grows and is shared between classes, @ArgumentsSource extracts it into a reusable ArgumentsProvider, shaped just like fareCases but implementing provideArguments(ExtensionContext).

A class with twenty flat methods is as unreadable as a two-hundred-line method. @Nested groups by scenario, and each group has its own @BeforeEach:

Rules you need to know: the inner class cannot be static —it needs the outer instance— and the @BeforeEach methods stack from the outside in, which is what makes incremental arrangement possible. The report is shown hierarchically and reads like a specification:

@DisplayName is not a substitute for a good method name: the name is what appears in failure stack traces and in -Dtest= filters.

@Tag slices the suite by criteria that cut across the file name:

Use few tags, with clear meaning: in CicloUrbana slow and security are enough. And remember that for separating unit from integration tests we already have a better mechanism, the *IT suffix with Failsafe from 06-01, which does not depend on anyone remembering to annotate.

Here a decision taken back in 02-01 pays off. CommonConfig declares @Bean Clock ribaltaClock(), and at the time it looked like a formality. If RentalService calculated the duration with Instant.now(), testing a two-hour rental would mean waiting two hours, changing the system clock or mocking a static method (06-03: you can, and you almost never should). With the injected Clock —Instant.now(clock)— time is just another argument:

The two factories used in tests:

The second is what lets you test that a JWT token expires after fifteen minutes: it is generated with one clock and validated with another one sixteen minutes ahead. Without waiting sixteen minutes.

The general rule: any source of non-determinism must be injectable. The clock, the random generator —the Random with a fixed seed from 02-01 answers the same idea— and the identifier generator. A new Random() or a UUID.randomUUID() embedded in the logic makes an exact assertion impossible.

@TempDir gives you a directory that JUnit creates beforehand and deletes afterwards, with no clean-up code:

Assumptions abort a test without marking it as failed when the conditions are not met: assumeTrue(DockerClientFactory.instance().isDockerAvailable(), "Docker not available") skips it entirely, and assumingThat(condition, () -> assertThat(...)) skips only one block of assertions. The difference from @Disabled is that the latter disables always while an assumption decides at run time. The nuance to watch: a skipped test shows up green in the summary, so a lax assumption hides the fact that something is never run. Always give them a message.

@RepeatedTest(100) runs the same test several times; its legitimate use is checking something with internal randomness, such as a generator of RB-\d{4} plates. It is no use for detecting concurrency problems: repeating a hundred times on the same thread creates no contention. And if a test passes 99 times out of 100, you do not have a flaky test: you have a bug.

Putting it all together on a real class. StationService receives its repository through the constructor (02-02), so we hand it the InMemoryStationRepository from 02-01 —the fake from the table of doubles in 06-01— and nothing else is needed:

Why this test does not start the context, even though StationService is a @Service:

The @Service annotation does not prevent instantiating the class with new: it is metadata that Spring reads at start-up. A unit test does not start the context because it is not testing the context. That the wiring works is checked once, in the integration tests of 06-04, not in each of the two hundred logic tests.

TestStations.mainSquare() has now appeared several times. It is the Object Mother pattern: a factory in src/test/java that produces valid domain objects with business names.

When objects have many fields and each test varies one of them, the builder is more flexible:

What you gain is substantial: the test only mentions what it cares about. The other six fields exist with valid values but do not clutter the reading, and if tomorrow Rental gains a mandatory field you change the builder, not the forty tests.

A word of advice about the line that separates this from an anti-pattern: the test object is built, not calculated. If the builder starts to contain logic —"if it is finished, work out the amount from the fare"— you have duplicated the implementation inside the tests, and then the test passes even when the code is wrong.

Mixing org.junit.Test with org.junit.jupiter.api.Test. The test compiles and is never run; if the number of tests in the report does not add up, check the imports. In the same family is forgetting the static on @BeforeAll, @AfterAll or on the @MethodSource method: the configuration error is clear, but it is hard to recognise the first time.

isEqualTo on BigDecimal. It fails because of the scale even when the value is correct. With amounts of money, always isEqualByComparingTo. It is the failure that wastes the most time in a money-handling domain like CicloUrbana's.

Depending on the execution order. JUnit does not guarantee it and creates a new instance per test precisely to prevent it. If a test only passes when another one runs first, there is shared state —a static field, a file, a singleton—: fix it, do not order it with @TestMethodOrder. In the same family is the lax assertion (isNotNull() as the only check, or isInstanceOf(RuntimeException.class) when expecting a specific exception): it always passes and protects against nothing.

Conditional logic inside a test. An if (isWeekend) { ... } else { ... } means there are two tests written as one and that each run only checks one branch. The solution is a parameterised test, or two methods.

Tip: one reason to fail per test. That does not mean a single assertThat, but a single concept. Five assertions on the five fields of a RentalResponse are one concept; checking the amount and that the event was published are two, and they deserve two methods.

Tip: if you need more than three or four lines of arrangement, look at the class. A long arrangement is the test complaining about the design: too many dependencies, too much state, too many responsibilities.

Extend FareCalculatorTest with a parameterised test that verifies the cross-cutting property of all three fares: no amount can be negative and all of them must have a scale of exactly two decimal places. Use @MethodSource to combine the three fares with durations of 0, 1, 15, 30, 45 and 120 minutes, and assertSoftly to report every failure of a case at once. Explain why this test and the ones in section 7 do not overlap.

Write JwtServiceExpiryTest with two tests that use Clock to verify the rule from 05-04 —the access token expires after fifteen minutes— without waiting fifteen minutes: one checking that a token issued 14 minutes ago is still valid and another that one issued 16 minutes ago is not. Assume JwtService receives JwtProperties and Clock through the constructor. Reason why the sixteen-minute test is the more important one, and what clockSkewSeconds(30) does with the case of 15 minutes and 10 seconds.

Refactor this test, which gathers five of the defects seen in the lesson, and list what they are:

Solution 1

Comment: they do not overlap because they check different things. The ones in section 7 are example-based tests: they verify an exact value for an exact input and catch formula errors. This one is a property-based test: it does not know what the price should be, but it states invariants that always hold. It catches a different class of bug —a negative amount from a subtraction without Math.max, or a lost scale from forgetting setScale— and it stays valid when the council changes the prices, which the section 7 ones do not. The as(...) adds context to the failure message, indispensable with 18 combinations. And .scale() is demanding on purpose: a fare returning BigDecimal.ZERO (scale 0) instead of new BigDecimal("0.00") will fail, and it is right that it should: an invoiced amount must be formatted as €0.00.

Solution 2

About clockSkewSeconds(30): the tolerance from 05-04 means a token of 15 minutes and 10 seconds is still accepted, because it falls inside the margin allowed for drift between machines. That is correct and deliberate, but it means an expiry test must not sit within a few seconds of the boundary: it would be brittle and ambiguous. That is why the chosen cases are 14 and 16 minutes, comfortably either side. If you wanted to verify the tolerance itself, that is a third case with a name of its own: acceptsTheTokenWithinTheThirtySecondSkew.

Solution 3

The five defects:

1. static List<Station> stations: state shared between tests. It breaks the isolation and makes the result depend on the order.
2. StationTests and test1: names that describe no rule. When it fails in continuous integration you will have to open the file.
3. if (stations.size() > 0): conditional logic. If the list were empty, the test would pass without checking anything.
4. Two concepts in one method: managing stations and calculating the fare are unrelated. Two reasons to fail, and no name can describe them both.
5. assertEquals(new BigDecimal("4.1"), amount): it fails because of the scale, it uses JUnit assertions instead of AssertJ and it puts the arguments in expected-actual order, which is easy to swap. On top of that, assertNotNull on an object the test itself has just created verifies nothing about the production code.

Refactored, it becomes two classes:

The assertion on findById is what turns the second one into a real test: it does not check that the object just created is not null —we already knew that— but that the service has saved it and knows how to retrieve it, which is the real responsibility of create.

The base of CicloUrbana's pyramid now has foundations. You know the architecture of JUnit 5 —Platform, Jupiter and Vintage— and the wrong-import trap that stops a test ever running without saying so. You have mastered the full lifecycle and, above all, the decision that governs it: a new instance of the class for every @Test, the isolation guarantee on which the irrelevance of the execution order rests. You know how to use @BeforeEach for incremental arrangement, why @BeforeAll is static and why a @Disabled with no reason is worse than not having the test at all.

You have the AssertJ catalogue by data type with its delicate cases: usingRecursiveComparison for entities whose equals compares by identifier, the difference between containsExactly, containsExactlyInAnyOrder and contains, extracting with tuples and, the one that saves the most grief, isEqualByComparingTo for every BigDecimal, because equals compares the scale and Ribalta invoices in euros. You know how to demand the specific exception type with assertThatThrownBy, to check the stable code of the exceptions from 03-06 and to group the assertions of a composite object with assertSoftly. And you have written the module's flagship example: Ribalta's three fares with their allowances and their exact boundaries —14, 15 and 16 minutes; 30 and 31— in a single parameterised class, where @CsvSource covers the simple cases and @MethodSource the complex ones, and where the name of each case identifies the failure without opening the file. You know how to organise by scenario with @Nested, give readable names with @DisplayName, slice the suite with @Tag without overdoing it, isolate files with @TempDir and skip with judgement using assumptions. And you have collected the debt from module 2: the injected Clock turns time into an argument, and Clock.fixed makes a two-hour rental testable in two milliseconds. You close with StationService tested without a single line of Spring —twenty milliseconds against several seconds— and with the data encapsulated in TestStations and a rental builder, so that each test mentions only what it cares about.

One limit remains obvious. StationService could be tested this way because InMemoryStationRepository exists, a fake we wrote in module 2 that no longer represents the real implementation. RentalService is another story: it depends on four JPA repositories, on FareSelector, on the Clock and on the event publisher, and there is no fake for any of them. Writing them by hand would be absurd. The next lesson, Mocking with Mockito, solves exactly that: creating doubles on the fly, programming their answers, forcing the difficult scenarios —the unavailable bike, the full station, the repository failure— and verifying that RentalService published the RentalStarted event it was supposed to. With that, the most important class in CicloUrbana will be under test.