[SUREFIRE-523] Link all reported tests to source XRef (#3445)

Link every reported test name to its test source class while preserving exact source-line links in failure details. Normalize nested classes and report-name suffixes to the corresponding JXR source page, and cover enabled and disabled XRef configurations.

Fixes #1162

Author: wilx

maven-surefire-report-plugin/src/main/java/org/apache/maven/plugins/surefire/report/AbstractSurefireReport.java

@@ -74,8 +74,8 @@ public abstract class AbstractSurefireReport extends AbstractMavenReport {
     private File reportsDirectory;
 
     /**
-     * Link the violation line numbers to the (Test) Source XRef. Links will be created automatically if the JXR plugin is
-     * being used.
+     * Link test names to the (Test) Source XRef. Failure details link to the exact source line when available. Links will
+     * be created automatically if the JXR plugin is being used.
      */
     @Parameter(property = "linkXRef", defaultValue = "true")
     private boolean linkXRef;

maven-surefire-report-plugin/src/main/java/org/apache/maven/plugins/surefire/report/SurefireReportRenderer.java

@@ -366,9 +366,7 @@ private void constructTestCaseSection(ReportTestCase testCase) {
 
         if (!testCase.isSuccessful()) {
             sink.tableCell();
-            sinkAnchor("TC_" + toHtmlId(testCase.getFullName()));
-
-            link("#" + toHtmlId(testCase.getFullName()), testCase.getName());
+            linkTestCaseToSource(testCase);
 
             SinkEventAttributeSet atts = new SinkEventAttributeSet();
             atts.addAttribute(CLASS, "detailToggle");
@@ -398,7 +396,9 @@ private void constructTestCaseSection(ReportTestCase testCase) {
 
             sink.tableCell_();
         } else {
-            sinkCellAnchor(testCase.getName(), "TC_" + toHtmlId(testCase.getFullName()));
+            sink.tableCell();
+            linkTestCaseToSource(testCase);
+            sink.tableCell_();
         }
 
         tableCell(formatI18nString("surefire", "value.time", testCase.getTime()));
@@ -507,13 +507,13 @@ private void renderSectionFailureDetails() {
 
                 String fullClassName = testCase.getFullClassName();
                 String errorLineNumber = testCase.getFailureErrorLine();
-                if (xrefTestLocation != null) {
-                    String path = fullClassName.replace('.', '/');
-                    sink.link(xrefTestLocation + "/" + path + ".html#L" + errorLineNumber);
+                String xrefLocation = getXrefTestSourceLocation(fullClassName, errorLineNumber);
+                if (xrefLocation != null) {
+                    sink.link(xrefLocation);
                 }
                 sink.text(fullClassName + ":" + errorLineNumber);
 
-                if (xrefTestLocation != null) {
+                if (xrefLocation != null) {
                     sink.link_();
                 }
                 sink.unknown("div", TAG_TYPE_END, null);
@@ -531,6 +531,44 @@ private void renderSectionFailureDetails() {
         endSection();
     }
 
+    private void linkTestCaseToSource(ReportTestCase testCase) {
+        String xrefLocation = getXrefTestSourceLocation(testCase.getFullClassName(), null);
+        SinkEventAttributeSet atts = new SinkEventAttributeSet(ID, "TC_" + toHtmlId(testCase.getFullName()));
+        if (xrefLocation == null && !testCase.isSuccessful()) {
+            xrefLocation = "#" + toHtmlId(testCase.getFullName());
+        }
+        if (xrefLocation != null) {
+            atts.addAttribute(HREF, xrefLocation);
+        }
+
+        sink.unknown(A.toString(), TAG_TYPE_START, atts);
+        text(testCase.getName());
+        sink.unknown(A.toString(), TAG_TYPE_END, null);
+    }
+
+    private String getXrefTestSourceLocation(String fullClassName, String lineNumber) {
+        if (xrefTestLocation == null || fullClassName == null) {
+            return null;
+        }
+
+        String location = xrefTestLocation + "/" + toXrefTestSourcePath(fullClassName);
+        return lineNumber == null || lineNumber.isEmpty() ? location : location + "#L" + lineNumber;
+    }
+
+    static String toXrefTestSourcePath(String fullClassName) {
+        int reportNameSuffix = fullClassName.indexOf('(');
+        if (reportNameSuffix >= 0) {
+            fullClassName = fullClassName.substring(0, reportNameSuffix);
+        }
+
+        int nestedClass = fullClassName.indexOf('$');
+        if (nestedClass >= 0) {
+            fullClassName = fullClassName.substring(0, nestedClass);
+        }
+
+        return fullClassName.replace('.', '/') + ".html";
+    }
+
     private void constructHotLinks() {
         if (!testSuites.isEmpty()) {
             sink.paragraph();

maven-surefire-report-plugin/src/site/markdown/examples/cross-referencing.md.vm

@@ -20,7 +20,7 @@ date: July 2006
 <!-- limitations under the License.-->
 # Source Code Cross Reference
 
-There are times when we wish to know right away the line number of the source code that caused a test to the fail. The Surefire Report Plugin has the capability to cross reference the source code that made the test fail. In order to activate this feature, the `maven-jxr-plugin` should be declared in the `<reporting>` section of the POM along with the `maven-surefire-report-plugin`. For more details, please read the documentation of the [Maven JXR Plugin](http://maven.apache.org/plugins/maven-jxr-plugin/).
+The Surefire Report Plugin can link every reported test to its source class. For failed tests, the failure details link directly to the source line when it is available from the stack trace. To activate this feature, declare the `maven-jxr-plugin` in the `<reporting>` section of the POM along with the `maven-surefire-report-plugin`. For more details, read the documentation of the [Maven JXR Plugin](https://maven.apache.org/jxr/maven-jxr-plugin/).
 
 ```xml
 <project>
@@ -46,7 +46,7 @@ There are times when we wish to know right away the line number of the source co
 </project>
 ```
 
-After executing `mvn site` for site generation, you'll notice that from the **Failure Details** section of the report, a link is available to redirect you to the source code that caused the failure.
+After executing `mvn site`, each test name links to its source class. The **Failure Details** section additionally links to the source line that caused the failure when that line can be determined.
 
 In the figure below the code that caused the failure is _com.test.proj.AppTest:36_
 

maven-surefire-report-plugin/src/test/java/org/apache/maven/plugins/surefire/report/SurefireReportTest.java

@@ -77,6 +77,21 @@ void testBasicSurefireReport(SurefireReport mojo) throws Exception {
 
         int idx = htmlContent.indexOf("images/icon_success_sml.gif");
         assertTrue(idx >= 0, "Wrong content in file: " + report);
+
+        assertThat(
+                htmlContent,
+                containsString("<a id=\"TC_com.shape.CircleTest.testX\" "
+                        + "href=\"./xref-test/com/shape/CircleTest.html\">testX</a>"));
+        assertThat(
+                htmlContent,
+                containsString("<a id=\"TC_com.shape.CircleTest.testRadius\" "
+                        + "href=\"./xref-test/com/shape/CircleTest.html\">testRadius</a>"));
+        assertThat(
+                htmlContent,
+                containsString("<a href=\"#com.shape.CircleTest.testRadius\">"
+                        + "<img src=\"images/icon_warning_sml.gif\" /></a>"));
+        assertThat(htmlContent, containsString("toggleDisplay('com.shape.CircleTest.testRadius')"));
+        assertThat(htmlContent, containsString("./xref-test/com/shape/CircleTest.html#L34"));
     }
 
     @Test
@@ -106,8 +121,7 @@ void testBasicSurefireReportIfLinkXrefIsFalse(SurefireReport mojo) throws Except
 
         String htmlContent = String.join(System.lineSeparator(), Files.readAllLines(report.toPath()));
 
-        int idx = htmlContent.indexOf("./xref-test/com/shape/CircleTest.html#L44");
-        assertEquals(-1, idx);
+        assertFalse(htmlContent.contains("./xref-test/com/shape/CircleTest.html"));
     }
 
     @Test
@@ -119,8 +133,17 @@ void testBasicSurefireReportIfReportingIsNull(SurefireReport mojo) throws Except
         assertTrue(report.exists());
         String htmlContent = String.join(System.lineSeparator(), Files.readAllLines(report.toPath()));
 
-        int idx = htmlContent.indexOf("./xref-test/com/shape/CircleTest.html#L44");
-        assertTrue(idx < 0);
+        assertFalse(htmlContent.contains("./xref-test/com/shape/CircleTest.html"));
+    }
+
+    @Test
+    void testXrefTestSourcePath() {
+        assertEquals("com/shape/CircleTest.html", SurefireReportRenderer.toXrefTestSourcePath("com.shape.CircleTest"));
+        assertEquals(
+                "com/shape/OuterTest.html", SurefireReportRenderer.toXrefTestSourcePath("com.shape.OuterTest$Nested"));
+        assertEquals(
+                "com/shape/CircleTest.html",
+                SurefireReportRenderer.toXrefTestSourcePath("com.shape.CircleTest(Linux)"));
     }
 
     @SuppressWarnings("checkstyle:methodname")
@@ -133,11 +156,11 @@ void testBasicSurefireReport_AnchorTestCases(SurefireReport mojo) throws Excepti
         assertTrue(report.exists());
         String htmlContent = String.join(System.lineSeparator(), Files.readAllLines(report.toPath()));
 
-        int idx = htmlContent.indexOf("<td><a id=\"TC_com.shape.CircleTest.testX\"></a>testX</td>");
+        int idx = htmlContent.indexOf("<td><a id=\"TC_com.shape.CircleTest.testX\">testX</a></td>");
         assertTrue(idx > 0);
 
-        idx = htmlContent.indexOf("<td><a id=\"TC_com.shape.CircleTest.testRadius\"></a>"
-                + "<a href=\"#com.shape.CircleTest.testRadius\">testRadius</a>");
+        idx = htmlContent.indexOf("<td><a id=\"TC_com.shape.CircleTest.testRadius\" "
+                + "href=\"#com.shape.CircleTest.testRadius\">testRadius</a>");
         assertTrue(idx > 0);
     }
 

maven-surefire-report-plugin/src/test/java/org/apache/maven/plugins/surefire/report/stubs/ReportTestStub.java

@@ -18,8 +18,21 @@
  */
 package org.apache.maven.plugins.surefire.report.stubs;
 
+import java.io.InputStream;
+
+import org.apache.maven.model.io.xpp3.MavenXpp3Reader;
+
 public class ReportTestStub extends SurefireReportMavenProjectStub {
 
+    public ReportTestStub() {
+        try (InputStream is =
+                ReportTestStub.class.getResourceAsStream("/unit/basic-surefire-report-test/plugin-config.xml")) {
+            setModel(new MavenXpp3Reader().read(is));
+        } catch (Exception e) {
+            throw new IllegalStateException("Could not read test project model", e);
+        }
+    }
+
     @Override
     protected String getProjectDirName() {
         return "basic-surefire-report-test";