JUnit (Unit Testing)

JUnit 5 renames the lifecycle annotations: @Before becomes @BeforeEach, @After becomes @AfterEach, @BeforeClass becomes @BeforeAll, @AfterClass becomes @AfterEach's partner @AfterAll, and @Ignore becomes @Disabled. They also move to the org.junit.jupiter.api package.

JUnit 5 is three pieces: the Platform (launches tests and lets build tools/IDEs run them), Jupiter (the new way to write and run tests), and Vintage (an engine that runs your old JUnit 4 tests). JUnit 4 was a single library with no such separation.

JUnit 5 assertions live in org.junit.jupiter.api.Assertions, the optional message moved to the last argument (it was first in JUnit 4), and you test exceptions with assertThrows(...) instead of @Test(expected=...). JUnit 5 also adds assertAll and assertThrows returning the caught exception.

JUnit 4 customized test behavior with @RunWith (only one runner per class) and @Rule objects. JUnit 5 replaces both with extensions registered via @ExtendWith, and you can apply as many as you want, composing them freely.

Add the JUnit 5 dependencies including the Vintage engine, so old JUnit 4 tests keep running while you write all new tests in JUnit 5. Then migrate old tests gradually, removing Vintage once they're all converted.

@Test marks a method as a test case so JUnit runs it. The method must return void and take no parameters (unless something is injected), and should not be static or private.

JUnit 5's @Test has no expected or timeout attributes. Instead you use assertThrows to check an exception is thrown and assertTimeout (or @Timeout) to bound how long code may run.

Usual causes: importing JUnit 4's org.junit.Test instead of org.junit.jupiter.api.Test, the method being private or static, the test class or method matching no naming/include pattern in the build config, or the JUnit Platform/Jupiter engine not being on the runtime classpath.

JUnit 5 has a Platform that launches tests, a Jupiter engine that finds @Test methods by scanning classes via reflection, and the API (@Test) you annotate with. The engine builds a test plan, creates an instance per test, runs lifecycle callbacks, then invokes each @Test method.

JUnit 5 keeps @Test a bare marker and moves behavior (exceptions, timeouts, conditions) into separate assertions, annotations, and extensions. That makes @Test composable: you can build your own annotations that combine @Test with tags or extensions, and add cross-cutting behavior without changing @Test itself.

@BeforeEach runs before every test method and @AfterEach runs after each one. You use them to set up a fresh starting state (like creating objects) before each test and to clean up afterward, so tests don't affect each other.

@BeforeEach/@AfterEach run before and after every single test. @BeforeAll/@AfterAll run only once for the whole test class — before any test and after all tests. The 'Each' ones are for per-test setup; the 'All' ones are for expensive shared setup.

Superclass @BeforeEach methods run before subclass @BeforeEach methods, and subclass @AfterEach methods run before superclass @AfterEach methods. It nests like constructors: setup goes top-down (parent first), cleanup goes bottom-up (child first).

@BeforeEach rebuilds the test's objects before every test, so no test sees leftovers from another — tests stay independent and can run in any order. @BeforeAll runs once and any mutable state it creates is shared, so one test can corrupt it for the next, causing order-dependent, flaky failures.

Because JUnit makes a new test-class instance for each test, the constructor and field initializers also run before every test, so simple setup works there too. Prefer @BeforeEach when setup needs framework features (like injected parameters) or should run as the documented lifecycle step; use the constructor for plain field assignment.

@BeforeAll runs once before all the tests in a class; @AfterAll runs once after all of them. @BeforeEach and @AfterEach run before and after every single test method instead.

Put setup in @BeforeAll if it's expensive and the same for every test and safe to share (it runs once). Put it in @BeforeEach if each test needs its own fresh copy (it runs every time). The trade-off is speed (BeforeAll) versus isolation (BeforeEach).

By default JUnit 5 creates a new instance of the test class for every test method. @BeforeAll/@AfterAll run once, before any instance exists, so they can't belong to an instance — they must be static (belong to the class itself).

Start the expensive resource (e.g. a database container) once in @BeforeAll and stop it once in @AfterAll, so all tests in the class reuse it instead of paying the startup cost each time. Make sure each test cleans up its own data so tests stay independent.

Inherited @BeforeAll methods from a superclass run before the subclass's @BeforeAll; @AfterAll runs in the reverse order (subclass first, then superclass). Multiple @BeforeAll methods in the same class run in an unspecified order unless you set one with @Order.

The order is assertEquals(expected, actual). The first value is what you expect, the second is what your code produced. Swapping them still passes or fails correctly, but the failure message reads backwards and confuses you.

assertArrayEquals compares two arrays element by element (in order). assertIterableEquals walks two iterables (like Lists) and compares elements pairwise. assertEquals on raw arrays compares references, not contents, so it usually fails even when contents match.

assertEquals checks that two objects are equal by value (using .equals()). assertSame checks they are the exact same object in memory (using ==). Use assertSame only when identity matters, like verifying a cache returns the same instance.

Use the overload assertEquals(expected, actual, delta), where delta is a small tolerance. Floating-point math has rounding errors, so 0.1 + 0.2 isn't exactly 0.3. The delta says 'close enough'.

You can pass a String message as the last argument, shown only when the assertion fails. JUnit also accepts a Supplier<String> lambda; the lambda runs only on failure, so a costly message isn't built every time the test passes.

assertThrows runs a piece of code and checks it throws the exception type you expect. You pass the expected exception class and a lambda holding the code. The test passes only if that code throws that type (or a subtype).

assertThrows returns the exception, so you store it in a variable and call getMessage() or getCause() on it, then assert with normal assertEquals/assertTrue. To stay robust, check a stable substring or the cause's type rather than the entire exact message text.

assertThrows passes if the code throws the expected type or any subclass of it. assertThrowsExactly passes only if the thrown exception is exactly that class — a subclass fails. Use exactly when the precise type matters.

@Test(expected=...) only checked the type and let any line in the test throw it, so it was imprecise and couldn't check the message easily. ExpectedException needed setup before the call. assertThrows scopes the check to exact lines and returns the exception to inspect.

Don't put many lines in the lambda — an earlier line could throw the expected type and make the test pass for the wrong reason. Wrap only the call you expect to throw. And don't use assertThrows just to silence a checked exception in a test.

assertAll runs a group of assertions together and reports every failure at once. With plain asserts, the test stops at the first failure, so you only see one problem. assertAll shows all of them in one run.

Each assertion is a lambda so assertAll can decide when to run it and catch its failure. If you called the asserts directly, the first failing one would throw right away and the rest would never run — defeating the point.

Use assertAll when you check several independent properties of one thing and want to see every failure at once. Avoid it when a later check depends on an earlier one passing, because assertAll runs them all even after a failure.

You can nest an assertAll inside another. If only one check fails, assertAll rethrows that exact failure; if several fail, it throws one MultipleFailuresError bundling them. Nesting groups related checks and keeps the failure tree organized.

@ParameterizedTest runs the same test method many times, once per set of input values. A plain @Test runs once with no arguments. You pair it with a source annotation (like @ValueSource) that supplies the values.

@MethodSource names a method that returns the test data, usually a Stream of Arguments. Use it when the inputs are real objects or computed at runtime — things you can't write as plain literals in @ValueSource or @CsvSource.

@ValueSource gives a single column of values to a one-parameter method. @CsvSource gives comma-separated rows, so each row maps to several parameters. Use @ValueSource for one input; use @CsvSource when you need input-plus-expected pairs.

@EnumSource runs the test once per constant of an enum, injecting each constant. You can include or exclude specific names with its mode/names attributes. The name attribute on @ParameterizedTest sets each invocation's display label using placeholders like {index} and {0}.

JUnit automatically converts string source values (like from @CsvSource) into the parameter's type — that's implicit conversion. When the built-in rules can't do it, you supply a converter with @ConvertWith. To bundle many columns into one object, you use an ArgumentsAccessor or a custom aggregator via @AggregateWith.

@DisplayName is a JUnit 5 annotation that gives a test method or class a custom, human-readable name shown in reports and IDEs instead of the method name. It can contain spaces, punctuation, and even emojis.

A DisplayNameGenerator is a JUnit 5 strategy that builds a test's display name from its class/method automatically. You attach one with @DisplayNameGeneration so you do not have to write @DisplayName on every test.

@DisplayName names the whole parameterized or repeated test. Each individual invocation gets its own name from the test's name pattern (the name attribute), not from @DisplayName.

@Nested groups related tests into inner classes, each able to carry its own @DisplayName, so reports read as a tree. IndicativeSentences joins the enclosing names with the method name into one readable sentence.

Pick one default strategy for the whole codebase (often a generator like ReplaceUnderscores set via the config property), allow explicit @DisplayName to override where wording matters, and enforce it so reports stay consistent and low-maintenance.

@Disabled tells JUnit to skip a test method or whole test class instead of running it. You should always pass a reason string, like @Disabled("flaky on CI - see TICKET-123"), so it is clear why it is off.

The reason string explains why the test is turned off. JUnit prints it in the report. Without it, nobody knows why the test is disabled or when it is safe to turn back on.

These annotations turn a test on or off based on a condition: the operating system (@EnabledOnOs), a JVM system property (@EnabledIfSystemProperty), an OS environment variable (@EnabledIfEnvironmentVariable), or a custom boolean method (@EnabledIf). Each has a @Disabled... twin that does the opposite.

Use @Disabled when a test is just broken or parked. Use conditional annotations like @EnabledOnOs(WINDOWS) or @DisabledOnOs(MAC) when the test should run only under a real condition - a specific OS, Java version, or environment - so it re-enables itself automatically when that condition holds.

A disabled test is skipped entirely - its body and its @BeforeEach/@AfterEach for that test do not run, though class-level setup may still happen. It shows as 'skipped', not passed. Lots of disabled tests quietly remove coverage, so track and prune them.

A @Nested class must be non-static so it holds a reference to an instance of the outer test class. That lets nested tests read and reuse the outer class's fields and setup. A static nested class would be independent and couldn't share that instance state.

Outer @BeforeEach methods run before inner ones, going from the outermost class inward, then the test runs, then @AfterEach methods run in reverse order — innermost first, outermost last. Each level layers its own setup and teardown around the test.

@Nested marks an inner test class inside another test class. It groups related tests together so you can express scenarios like 'when the cart is empty' as their own block with their own setup, making tests easier to read and organize.

Use @Nested when tests fall into clear scenarios that share setup, so the report reads like sentences and duplication drops. Avoid nesting so deeply that setup becomes hard to follow or scenarios get artificial. Keep nesting shallow and meaningful.

An assertion checks the result you are testing: if it is false, the test FAILS. An assumption checks a precondition: if it is false, the test is SKIPPED (aborted), not failed. So a failed assumption is treated like a test that did not run.

assumeTrue(condition) keeps running the test only if the condition is true; assumeFalse(condition) keeps running only if it is false. Otherwise the test is skipped. Both can take a message, and both have a version that takes a BooleanSupplier so the condition is only evaluated lazily.

assumeTrue aborts the whole test when its condition is false. assumingThat takes a condition AND a block of code (an Executable): it runs that block only if the condition is true, and otherwise just skips the block and lets the rest of the test continue normally. It does not abort the test.

An aborted test counts as 'skipped', not 'passed' and not 'failed'. Lifecycle teardown still runs, but the test's body did not. Skipped tests do not exercise your code, so they contribute nothing to coverage. If many tests silently skip in CI, you can have a green build that actually tested very little.

By default JUnit 5 makes a fresh copy of your test class for every @Test method (PER_METHOD). This keeps tests isolated: fields set by one test can't leak into another, so test order doesn't matter.

@BeforeAll runs once at the start, @AfterAll once at the end. Around every @Test, JUnit runs the constructor then @BeforeEach before, and @AfterEach after. In PER_METHOD the constructor runs once per test; in PER_CLASS it runs only once.

@TestInstance(Lifecycle.PER_CLASS) tells JUnit to create just one instance of the test class and reuse it for every @Test. Because there's now a shared instance, @BeforeAll and @AfterAll can be non-static methods.

PER_METHOD gives each test a fresh instance, so shared fields can't leak and order doesn't matter. PER_CLASS reuses one instance, so mutated fields persist between tests; to stay safe, reset that state in @BeforeEach and don't let tests depend on order.

Under the default PER_METHOD lifecycle JUnit makes a new instance per test, so there's no single instance to run a once-per-class method on — hence @BeforeAll/@AfterAll must be static (called on the class). The bug risk: static fixture fields are shared across all tests and aren't reset, so mutations leak between tests.