JUnit

It is a composed annotation: your own annotation type that is itself annotated with JUnit's @Test, @Tag, @ExtendWith and so on. Jupiter looks up annotations recursively, so anything meta-annotated with @Test is discovered and run as a test.

@Disabled skips a test instead of running it, reporting it as skipped rather than failed. On a method it skips that method; on a class it skips every test in the class, including its nested classes. The string argument is the reason, shown in reports and IDEs.

Annotate it with org.junit.jupiter.api.Test. The method must not be private, static or abstract, and must return void. Parameters are allowed only if a ParameterResolver supplies them (TestInfo, TestReporter, @TempDir...). The class must not be abstract and needs a single constructor; neither class nor method has to be public.

Annotate the test with JUnit Jupiter's @Timeout, e.g. @Timeout(value = 500, unit = TimeUnit.MILLISECONDS). The default unit is seconds. When the limit elapses the test fails with a TimeoutException naming the method and the configured duration.

@Retention(RetentionPolicy.RUNTIME) is mandatory — the default CLASS retention hides the annotation from reflection, so JUnit never sees it. @Target must include the element you annotate (METHOD for a test marker, TYPE for class-level, ANNOTATION_TYPE to allow further composition).

Call Assumptions.assumeTrue(condition) (or assumeFalse) at the top of the test. If the condition does not hold, a TestAbortedException is thrown, the rest of the method never runs, and the test is reported as aborted or skipped — the build stays green rather than red.

assertEquals compares with equals() — value equality. assertSame compares with == — the same object in memory. Use assertSame only when identity is the contract you are testing: caches, interned or flyweight instances, singletons, or a method that returns this.

Call assertThrows(ExpectedType.class, () -> codeUnderTest()). It fails if nothing is thrown or if the thrown type does not match, and on success it returns the thrown exception, typed, so you can go on asserting its message, cause or custom fields.

assertAll takes lambdas, runs every one of them even after some fail, then reports all failures together in one aggregated error. Use it for independent checks on the same object so a single run shows every problem instead of only the first.

Use Assertions.assertTimeout(Duration.ofMillis(500), () -> code). It runs the block on the test thread, then fails if it took longer, reporting the expected budget and how much it overran. A supplier form returns the block's value.

@BeforeAll runs once before any test in the class; @AfterAll runs once after the last one. @BeforeEach runs before every individual test and @AfterEach after every one, so for three tests you get one BeforeAll, three BeforeEach/test/AfterEach cycles, then one AfterAll.

Three. Jupiter's default lifecycle is PER_METHOD: a brand-new instance of the test class is constructed before each @Test method. Instance fields therefore start fresh every time, so one test cannot leak state into another through fields.

Jupiter applies no orderer by default, so methods run in a deterministic but intentionally non-obvious order — not source order, not alphabetical — and it may change between versions. Each test must therefore pass independently, in any order.

By default JUnit creates a new test-class instance for every test method, so there is no single instance a class-level hook could belong to; it must be static to be callable once per class. Without static you get a runtime JUnitException telling you the method must be static, not a compile error.

Jupiter creates one instance of the class for all its test methods instead of one per method. Instance fields then survive between tests, and @BeforeAll/@AfterAll (and non-static @MethodSource factory methods) may be non-static because there is now an instance to own them.

@CsvSource sits next to @ParameterizedTest and holds an array of comma-separated row strings. JUnit runs the test method once per row, splitting the row on commas and passing the pieces, left to right, as the method's parameters.

@MethodSource names a factory method that returns a Stream (or Iterable/array) of arguments; JUnit runs the test once per element. If you leave the value empty, JUnit looks for a factory method with the same name as the test method.

Set the name attribute of @ParameterizedTest, e.g. @ParameterizedTest(name = "[{index}] input={0}"). JUnit fills placeholders per invocation: {index} (1-based), {arguments}, {argumentsWithNames}, {displayName}, and positional {0}, {1}. Default pattern is "[{index}] {argumentsWithNames}".

Mark the method @ParameterizedTest and add @ValueSource(ints = {1, 2, 3}); it runs once per value, passing one argument each time. Limits: exactly one array attribute, only primitives plus String and Class, values must be compile-time constants, and null cannot be supplied.

Declare one parameter of type ArgumentsAccessor. JUnit passes it the whole argument array for that invocation instead of consuming a single column. You read values positionally: getString(0), getInteger(3), get(5, LocalDate.class), plus size(), toList() and toArray().

Declaratively, with @ExtendWith(SomeExtension.class). It can go on a test class, on a single test method, on a field or parameter, or on your own meta-annotation. JUnit builds the extension with its no-arg constructor, and class-level registration is inherited by subclasses and @Nested classes.

Annotate a field or a method parameter of type java.nio.file.Path or java.io.File with JUnit Jupiter's @TempDir. Jupiter's built-in extension creates a fresh empty directory in the OS temp location before use and recursively deletes it, with its contents, afterwards.

Order is BeforeAllCallback, @BeforeAll, BeforeEachCallback, @BeforeEach, BeforeTestExecutionCallback, the test, AfterTestExecutionCallback, @AfterEach, AfterEachCallback, @AfterAll, AfterAllCallback. Multiple extensions nest like an onion: Before* in registration order, After* in reverse.

Implement JUnit 5's ExecutionCondition extension. Its evaluateExecutionCondition(ExtensionContext) returns ConditionEvaluationResult.enabled(reason) or disabled(reason). JUnit calls it for every container and test it is registered on; a disabled result skips that node, reported as skipped rather than failed.

Implement ParameterResolver: supportsParameter(ParameterContext, ExtensionContext) returns true only for parameters you own, and resolveParameter(...) returns the object. Register it with @ExtendWith. Narrow supportsParameter by both a custom annotation and the parameter type so it never competes with another resolver.

@Before becomes @BeforeEach, @BeforeClass becomes @BeforeAll, @After becomes @AfterEach, @AfterClass becomes @AfterAll, @Ignore becomes @Disabled, @Category(X.class) becomes @Tag("x"). Packages change to org.junit.jupiter.api, assertions move to Assertions, and the message argument moves to last.

A @Rule is a public, non-static field holding an object that wraps each test method. Because it wraps the call, it can run code before and after the test and also catch failures, retry, time out or skip it. @Before/@After only run beside the test.

@RunWith(X.class) names the Runner class that takes over running that test class. Without it, JUnit falls back to its default runner — org.junit.runners.JUnit4, a subclass of BlockJUnit4ClassRunner — which finds the @Test methods, creates a new instance per method and applies @Before/@After and rules.

junit-vintage-engine is a TestEngine implementation for the JUnit Platform. It discovers JUnit 3 (junit.framework.TestCase) and JUnit 4 classes, delegates execution to JUnit 4's own runners, and reports results back to the platform. The tests keep pure JUnit 4 semantics and gain no Jupiter features.

Use Assertions.assertThrows(SomeException.class, () -> code()), which returns the thrown exception so you can assert its message or cause. It scopes the expectation to one statement, unlike @Test(expected=), which passes if any line in the method throws that type.

A DynamicTest is a test case created at runtime as an object, via DynamicTest.dynamicTest(displayName, executable) — a display-name string plus a lambda holding the assertions. Unlike a @Test method it is not discovered by annotation scanning and carries no annotations of its own.

@Nested makes an inner class a child test container: its tests run under the outer class and reuse the outer class's fields and @BeforeEach setup. It must be non-static so every nested instance is bound to a live enclosing instance.

Dynamic tests are generated at runtime, so Jupiter's per-test callbacks bind to the generating method, not to each generated case: @BeforeEach and @AfterEach run once around the whole factory. Put setup and teardown inside each executable, typically via a shared wrapper helper.

@BeforeEach runs outside-in (outer then nested), @AfterEach inside-out. With the default per-method lifecycle each test gets a fresh outer instance plus a fresh nested instance. @BeforeAll must be static, which needs Java 16+ or @TestInstance(PER_CLASS) on the nested class.

A @TestFactory method is not a test; it is a factory invoked at runtime that returns dynamic test nodes, which JUnit then executes. Cases are produced during execution rather than fixed at discovery, so the number and names of tests can depend on runtime data.

JUnit 5 has @EnabledOnOs/@DisabledOnOs, @EnabledOnJre/@DisabledOnJre and @EnabledForJreRange/@DisabledForJreRange, plus @EnabledIfSystemProperty/@EnabledIfEnvironmentVariable and method-based @EnabledIf/@DisabledIf. They go on a test method or a whole class, and a switched-off test is reported as skipped with a reason — it never runs.

Parallel execution is off by default. Set junit.jupiter.execution.parallel.enabled=true, then set the default execution modes: junit.jupiter.execution.parallel.mode.default and junit.jupiter.execution.parallel.mode.classes.default to concurrent. Put them in junit-platform.properties on the test classpath, or pass them as JVM system properties.

@Tag("slow") labels a test class or method; it is metadata and changes nothing by itself. The runner passes a tag expression (Gradle includeTags/excludeTags, Maven groups/excludedGroups) and the JUnit Platform filters non-matching tests out of the run.

mode.classes.default decides whether top-level test classes may run concurrently with each other; mode.default is the default mode for the rest of the tree — methods and nested classes. Both take same_thread or concurrent. @Execution(CONCURRENT|SAME_THREAD) on a class or method overrides the configured default for that node and everything nested inside it.

@ResourceLock declares that a test class or method needs a named shared resource. When tests run in parallel, JUnit will not let two tests hold conflicting locks on the same key at once, so tests that touch the same shared state are serialised while everything else keeps running concurrently.

JUnit 5 = Platform + Jupiter + Vintage. The Platform is the foundation: it launches tests and defines the TestEngine plug-in interface. Jupiter is the new programming model (annotations, assertions) plus its own engine. Vintage is an engine that runs old JUnit 3 and 4 tests.

Use the JUnit Platform Launcher API from junit-platform-launcher: build a LauncherDiscoveryRequest with selectors and filters, open a LauncherSession to get a Launcher, register a TestExecutionListener, then call discover() to inspect the TestPlan or execute() to run it.

Put @Suite on a plain class, then add selectors: @SelectClasses lists test classes explicitly, @SelectPackages scans whole packages. The junit-platform-suite-engine artifact must be on the test runtime classpath, otherwise the suite class runs nothing.

Test code compiles only against the API (annotations, assertions, extensions); the engine is an implementation found at runtime through ServiceLoader. Keeping the engine off the compile path stops code depending on engine internals. The aggregate junit-jupiter artifact bundles api plus params, with the engine at runtime.

Configuration parameters are simple key/value settings. They can come from the LauncherDiscoveryRequest, a JVM system property, or a junit-platform.properties file at the root of the classpath — and that is also the precedence order, request first, file last.