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.

[SqAutoTestTeam]

We are migrating project from Juni4 to Junit5.
Some of functionality written in Juni4 is based on usage of Rule. The custom rule is used to
send tests results to outer system - where they can be seen later .

Rule provides me with three callback methods
protected void succeeded(Description desc);
protected void failed(Throwable e, Description desc);
protected void skipped(AssumptionViolatedException e, Description desc);

So I can be aware what is the test result - failed, success or skipped -
(AssumptionViolatedException exception is thrown while test execution)

@mmerdes has made a good work of adapting existing junit4 rules to extensions of junit5
but it does support method result callbacks unfortunately.

I've researched this topic and came to realise that for now there is no strait reliable way to implement this feature using only Junit5 extension model.

The closest extension is AfterTestExecutionCallback but its callback method
....
public void afterTestExecution(TestExtensionContext context) throws Exception
....
does not pass so necessary info - test execution result. So none can tell for sure
if test is ok, failed or ignored.
Indirect ways to solve this problem do not look reliable.

Now when you plan UseExtension my question is: Are you planning to provide users with test result callback or pass info of test result ? If not please take it into account. Sooner or later there will be users that encounter the same problem. Although I do not know implementation details I suppose that UseExtension as
a field annotation implies calling methods on field object it annotates.

Suggestion:
Possible solution is to add another Extension sub-interface (TestFinished) that passes test result into its callback method. In this case the task can be easily solved by writing custom extension.

[sbrannen]

@SqAutoTestTeam, this issue focuses solely on programmatic extension registration via fields. Consequently, we are not considering any changes to extension APIs in conjunction with this issue.

If you would like to propose additional Extension APIs, please create a new issue dedicated to your proposal.

Thanks

[leonard84]

I'd like to add some wishes here:

1. It should be possible to use injected extensions, e.g. via @Inject/@Autowired
2. It should be possible for the test code to interact with the extension object similar to TemporaryFolder#newFile(String)

[sbrannen]

Feature branch merged into master in commit 4383792.