When would you register a JUnit 5 Jupiter extension programmatically with @RegisterExtension on a field instead of declaring it with @ExtendWith, and what rules apply to that field?

## The gap @ExtendWith leaves Declarative registration takes a `Class` literal. Jupiter reflectively instantiates it with the default constructor, so there is nowhere to say "listen on this port", "use this fixed clock", "start this image". Many real extensions need exactly that. `@RegisterExtension` closes the gap: instead of a class, you hand Jupiter an **object you constructed**. ```java @RegisterExtension static WireMockExtension wireMock = WireMockExtension.newInstance() .options(wireMockConfig().dynamicPort()) .build(); ``` Jupiter scans the test class for fields annotated `@RegisterExtension`, reads their values, and registers them in the extension registry alongside declaratively registered ones. ## Rules for the field - **Not `private`.** Package-private, protected or public are all fine; `private` is rejected because Jupiter's field discovery deliberately refuses it (the intent is that extensions declared this way are visible to subclasses). - **Type must implement `Extension`.** The compiler will not catch a mistake here, but discovery fails. - **Value must not be `null`** when Jupiter reads it. Assign it inline at the declaration site — assigning it inside `@BeforeEach` is too late, because registration happens before user setup code runs. - **May be `final`.** That is the usual style, and it prevents accidental reassignment mid-run. - **`static` or instance** — the single most important decision, because it determines *when* the extension joins the registry and therefore which callback interfaces are honoured. ## Second benefit: the test can talk to the extension Because it is an ordinary field, the test body can query it. This is how you get a dynamically allocated stub-server port, assert on captured log output, or hand a Testcontainers JDBC URL to a `DynamicPropertySource`. With `@ExtendWith` the instance is hidden inside the engine, so the only way to reach the extension's data is through parameter resolution or the `ExtensionContext` store. ## Ordering Within a context, extensions register in this order: inherited/class-level declarative ones first, then declarative ones in declaration order, then programmatic ones. Among programmatic fields the JVM does **not** guarantee field order, so relative order of two `@RegisterExtension` fields is undefined unless you annotate them with `@Order` (lower value = registered earlier = its "before" callback runs earlier and its "after" callback runs later, since after-callbacks unwind in reverse). If one extension must observe state another produced, make the dependency explicit with `@Order` rather than relying on source order. ## Choosing between the two Use `@ExtendWith` for zero-configuration extensions and for meta-annotations that define your project's test archetypes. Use `@RegisterExtension` when configuration or test access is needed. A common hybrid: a project-specific extension with sensible defaults exposed through `@ExtendWith`, plus a builder-based path via `@RegisterExtension` for tests that need to tune it. ## Interaction with lifecycle One trap: a `static` field is initialised in the static initialiser, so any expensive object it builds is created when the class loads, even if all its tests are filtered out by a condition. If start-up cost matters, have the extension itself start lazily inside a `BeforeAllCallback` rather than in the field initialiser.