Create 5.11 upgrade guide wiki page

[sbrannen]

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

• Align method and field search algorithms with Java semantics #3553
• JUnit 5 computes overrides relationships incorrectly #2390
• @BeforeAll method in super class skipped when it has same name as a @BeforeEach method in subclass #3498
• @TempDir field in super class skipped when it has same name as a @TempDir field in subclass #3532
• Introduce @FieldSource for parameterized tests #2014

Deliverables

• Create a migration guide wiki page for 5.11

[sbrannen]

I created the wiki page with an initial draft: https://github.com/junit-team/junit5/wiki/Upgrading-to-JUnit-5.11

[sbrannen]

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.