Create 5.11 upgrade guide wiki page
sbrannen opened this issue · comments
Overview
In light of the impact of the changes resulting from #3553, I think it might be a good idea to create a "5.11 Migration Guide" wiki page where we can highlight some of the known issues, migration advice, and workarounds (where applicable).
As can be seen below, these changes will impact not only developers writing tests but also potentially the behavior of third party extensions.
I'd rather document the "migration help" in the wiki than in the User Guide or Release Notes, since we will be able to update the wiki with additional tips after the release.
Topics to Cover
We should probably cover topics similar to the following.
- fields no longer hide fields from super types -- applies to non-static and static fields (
@TempDir
,@RegisterExtension
, etc.) - methods no longer hide methods from super types unless a given method literally overrides the other method -- applies to non-static and static methods (
@BeforeAll
,@BeforeEach
,@Test
, etc.) - extensions may have to revise their search algorithms for fields and methods (see case study below)
Case Study
I originally implemented the @FieldSource
feature before #3553 had been implemented. When I rebased that work on main
after #3553 had been merged, the @FieldSource
feature failed to find the first field in the type hierarchy with a given name if a field with the same name also existed higher in the type hierarchy (i.e., in a superclass). With #3553 in place, the @FieldSource
feature started finding all such fields instead of the first one, which resulted in a PreconditionViolationException
stating that the field could not be found.
The "Before" section below shows the naïve approach I had originally taken.
The "After" section shows the current approach.
In retrospect, I probably should have written it like in the "After" section originally, since that code literally implements the correct logic: find the first field with a given name in the type hierarchy, searching up the type hierarchy beginning with the test class.
However, the "Before" section effectively achieved the same goal previously, since it depended on the existing "legacy search semantics" for fields, whereby the field in the subclass "hid" the field in the superclass.
Before
Predicate<Field> nameMatches = field -> field.getName().equals(fieldName);
List<Field> fields = ReflectionUtils.findFields(testClass, nameMatches, HierarchyTraversalMode.TOP_DOWN);
Preconditions.condition(fields.size() == 1,
() -> format("Could not find field named [%s] in class [%s]", fieldName, testClass.getName()));
return fields.get(0);
After
Predicate<Field> nameMatches = field -> field.getName().equals(resolvedFieldName);
Field field = ReflectionUtils.streamFields(resolvedClass, nameMatches, HierarchyTraversalMode.BOTTOM_UP)//
.findFirst()//
.orElse(null);
Preconditions.notNull(field,
() -> format("Could not find field named [%s] in class [%s]", resolvedFieldName, resolvedClass.getName()));
return field;
Related Issues
Deliverables
- Create a migration guide wiki page for 5.11
I created the wiki page with an initial draft: https://github.com/junit-team/junit5/wiki/Upgrading-to-JUnit-5.11
I linked to the new wiki page from the Release Notes in 64be598 and have closed this issue in order to ensure all issues are closed for the 5.11 M1 milestone.
We can of course update the wiki page with additional information and tips at any time.