Introduce extension API for container templates

[marcphilipp]

Overview

Analogous to @TestTemplate on the method level, this PR introduces a class-level @ContainerTemplate annotation with an accompanying ContainerTemplateInvocationContextProvider extension API.

Resolves #871.

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

---

Definition of Done

• There are no TODOs left in the code
• Method preconditions are checked and documented in the method's Javadoc
• Coding conventions (e.g. for logging) have been followed
• Change is covered by automated tests including corner cases, errors, and exception handling
• Public API has Javadoc and @API annotations
• Change is documented in the User Guide and Release Notes

[georgberky]

Holy smokes, thanks for your work! I've been waiting for this. Can I help with testing this somehow?

[marcphilipp]

Sure thing! There will be follow-up work (most importantly #878) but if you could review the code and try using it guided by the docs in this PR, I'd be very interested in your feedback.

[Sola-ris]

I have two questions about the container templates, hope it's Ok to ask them here

• Are there plans to make the container template invocations interceptable via an InvocationInterceptor
  like test method templates?
• Change return type to Stream<? extends TestTemplateInvocationContext> #3577 talks about declaring the return type of TestTemplateInvocationContextProvider#provideTestTemplateInvocationContexts
  as Stream<? extends TestTemplateInvocationContext> instead of Stream<TestTemplateInvocationContext>.
  Was ContainerTemplateInvocationContextProvider#provideContainerTemplateInvocationContexts's return type declared without the upper bound to be in sync with TestTemplateInvocationContextProvider?

[marcphilipp]

• Are there plans to make the container template invocations interceptable via an InvocationInterceptor
  like test method templates?

We don't currently have plans to support intercepting the entire invocation of a container template which would encompass all of its test methods, nested test classes etc. Instead, we will add new lifecycle methods and extension points, specifically for container templates in #4320.

• Change return type to Stream<? extends TestTemplateInvocationContext> #3577 talks about declaring the return type of TestTemplateInvocationContextProvider#provideTestTemplateInvocationContexts
  as Stream<? extends TestTemplateInvocationContext> instead of Stream<TestTemplateInvocationContext>.
  Was ContainerTemplateInvocationContextProvider#provideContainerTemplateInvocationContexts's return type declared without the upper bound to be in sync with TestTemplateInvocationContextProvider?

Thanks for reminding me of that issue! I've changed ContainerTemplateInvocationContextProvider accordingly in bffb6c7. TestTemplateInvocationContextProvider will have to wait until 6.0 (which is planned for later this year) because changing it is binary incompatible with previous releases.

[Sola-ris]

We don't currently have plans to support intercepting the entire invocation of a container template which would encompass all of its test methods, nested test classes etc. Instead, we will add new lifecycle methods and extension points, specifically for container templates in #4320.

Those should also cover the use case I had in mind, thank you.

Thanks for reminding me of that issue! I've changed ContainerTemplateInvocationContextProvider accordingly in bffb6c7. TestTemplateInvocationContextProvider will have to wait until 6.0 (which is planned for later this year) because changing it is binary incompatible with previous releases.

You're welcome :D

[marcphilipp]

As discussed in the team, I'll go ahead and merge this to make it easier to work on #878 next. Feedback is still appreciated, though, even post-merge!

[bruderj15]

This is awesome! I was awaiting this feature for a long time!
Will I have to wait a little bit longer until 5.13.0 or may you release it earlier?
Either way, great work!

[marcphilipp]

Will I have to wait a little bit longer until 5.13.0 or may you release it earlier?

You will have to wait until 5.13. However, if you're willing to use a milestone version, we will probably release an 5.13.0-M1 early on to make it easier to try out this new feature and provide feedback.