Support programmatic extension registration via fields

[sbrannen]

Status Quo

It is currently possible to register extensions declaratively via @ExtendWith on a class or method but not on a field.

Furthermore, it is currently impossible for a user of an extension to provide input to the extension programmatically. Rather, in order to make an extension configurable, current extension implementations typically provide a custom annotation, but such an annotation is hindered by the limitations of what can be declared as an annotation attribute in Java.

See the discussion in Spring REST Docs for further background information.

Related Issues

• Support @ExtendWith on fields #416
• Introduce mechanism for programmatic extension management #506
• Support declarative extension registration on fields and parameters #864

Proposal for Programmatic Extension Registration

In general, it should be possible for an extension to be registered programmatically -- for example, via a field or a factory method. This would allow a user to pass arguments to the extension's constructor (or static factory method) or to construct the extension programmatically, for example, via a method that returns the configured extension instance.

With regard to migrations from JUnit 4 to JUnit Jupiter, it should be possible to migrate a JUnit 4 rule from this:

@Rule
public JUnitRestDocumentation restDocumentation =
        new JUnitRestDocumentation("target/generated-snippets");

... to the following in JUnit Jupiter:

@RegisterExtension
RestDocumentationExtension restDocumentation =
        new RestDocumentationExtension("target/generated-snippets");

Considerations

• Although the existing @ExtendWith annotation could technically be repurposed for such use cases, the JUnit Team feels it would be better to introduce a new annotation dedicated to this purpose. The current proposed name is @RegisterExtension, but this may change.

Deliverables

• Support programmatic registration of a single extension via a field annotated with @RegisterExtension where the field's value is used as the extension instance.
• Document in User Guide.
• Document in Release Notes.

[juergenzimmermann]

@sbrannen do you have a coarse estimation when M3 might be available?

[sbrannen]

@juergenzimmermann, perhaps by the end of October. The core team is swamped with work, so we are unfortunately forced to push back the release dates.