Update XML string comparisons to account for formatting differences across platforms

Author: d-ronnqvist

Sources/DocCHTML/MarkdownRenderer.swift

@@ -171,7 +171,7 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
             return .text("")
         }
 
-        if link.childCount > 0 {
+        guard link.isAutolink else {
             var customTitle = [XMLNode]()
             for child in link.inlineChildren {
                 if let code = child as? InlineCode {
@@ -181,16 +181,14 @@ package struct MarkdownRenderer<Provider: LinkProvider> {
                 }
             }
 
-            if customTitle != [.text(destination.absoluteString)] {
-                return .element(
-                    named: "a",
-                    children: customTitle,
-                    attributes: [
-                        // Use relative links for DocC elements, and the full link otherwise.
-                        "href": linkProvider.element(for: destination).flatMap { path(to: $0.path) } ?? destination.absoluteString
-                    ]
-                )
-            }
+            return .element(
+                named: "a",
+                children: customTitle,
+                attributes: [
+                    // Use relative links for DocC elements, and the full link otherwise.
+                    "href": linkProvider.element(for: destination).flatMap { path(to: $0.path) } ?? destination.absoluteString
+                ]
+            )
         }
 
         // Make a relative link

Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift

@@ -53,7 +53,7 @@ struct MarkdownRenderer_PageElementsTests {
         let breadcrumbs = makeRenderer(goal: goal, elementsToReturn: elements).breadcrumbs(references: elements.map { $0.path }, currentPageNames: .single(.conceptual("ThisPage")))
         switch goal {
         case .richness:
-            #expect(breadcrumbs.rendered(prettyFormatted: true) == """
+            breadcrumbs.assertMatches(prettyFormatted: true, expectedXMLString: """
             <nav id="breadcrumbs">
             <ul>
                 <li>
@@ -70,7 +70,7 @@ struct MarkdownRenderer_PageElementsTests {
             </nav>
             """)
         case .conciseness:
-            #expect(breadcrumbs.rendered(prettyFormatted: true) == """
+            breadcrumbs.assertMatches(prettyFormatted: true, expectedXMLString: """
             <ul>
             <li>
                 <a href="../../index.html">ModuleName</a>
@@ -93,15 +93,15 @@ struct MarkdownRenderer_PageElementsTests {
         ])
         switch goal {
         case .richness:
-            #expect(availability.rendered(prettyFormatted: true) == """
+            availability.assertMatches(prettyFormatted: true, expectedXMLString: """
             <ul id="availability">
             <li aria-label="First 1.2–3.4, Introduced in First 1.2 and deprecated in First 3.4" class="deprecated" role="text" title="Introduced in First 1.2 and deprecated in First 3.4">First 1.2–3.4</li>
             <li aria-label="Second 1.2.3+, Available on 1.2.3 and later" role="text" title="Available on 1.2.3 and later">Second 1.2.3+</li>
             <li aria-label="Third 4.5+, Available on 4.5 and later" class="beta" role="text" title="Available on 4.5 and later">Third 4.5+</li>
             </ul>
             """)
         case .conciseness:
-            #expect(availability.rendered(prettyFormatted: true) == """
+            availability.assertMatches(prettyFormatted: true, expectedXMLString: """
             <ul id="availability">
             <li>First 1.2–3.4</li>
             <li>Second 1.2.3+</li>
@@ -126,7 +126,7 @@ struct MarkdownRenderer_PageElementsTests {
 
         switch goal {
         case .richness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="parameters">
             <h2>
                 <a href="#parameters">Parameters</a>
@@ -153,7 +153,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>Parameters</h2>
             <dl>
             <dt>
@@ -192,7 +192,7 @@ struct MarkdownRenderer_PageElementsTests {
                 .init(name: "ObjectiveCOnly", content: parseMarkup(string: "Only available in Objective-C")),
             ],
         ])
-        #expect(parameters.rendered(prettyFormatted: true) == """
+        parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
         <section id="parameters">
         <h2>
             <a href="#parameters">Parameters</a>
@@ -240,7 +240,7 @@ struct MarkdownRenderer_PageElementsTests {
                 .init(name: "Third", content: parseMarkup(string: "Some description")),
             ],
         ])
-        #expect(parameters.rendered(prettyFormatted: true) == """
+        parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
         <section id="parameters">
         <h2>
             <a href="#parameters">Parameters</a>
@@ -306,7 +306,7 @@ struct MarkdownRenderer_PageElementsTests {
         ])
         switch goal {
         case .richness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre id="declaration">
             <code>
                 <span class="token-keyword">func</span>
@@ -323,7 +323,7 @@ struct MarkdownRenderer_PageElementsTests {
             </pre>
             """)
         case .conciseness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre>
             <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
             </pre>
@@ -344,7 +344,7 @@ struct MarkdownRenderer_PageElementsTests {
 
         switch goal {
         case .richness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
@@ -353,7 +353,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>Return Value</h2>
             \(commonHTML)
             """)
@@ -375,7 +375,7 @@ struct MarkdownRenderer_PageElementsTests {
 
         switch goal {
         case .richness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="return-value">
             <h2>
                 <a href="#return-value">Return Value</a>
@@ -384,7 +384,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(parameters.rendered(prettyFormatted: true) == """
+            parameters.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>Return Value</h2>
             \(commonHTML)
             """)
@@ -449,7 +449,7 @@ struct MarkdownRenderer_PageElementsTests {
         ])
         switch goal {
         case .richness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre id="declaration">
             <code class="swift-only">
                 <span class="token-keyword">func</span>
@@ -478,7 +478,7 @@ struct MarkdownRenderer_PageElementsTests {
             """)
 
         case .conciseness:
-            #expect(declaration.rendered(prettyFormatted: true) == """
+            declaration.assertMatches(prettyFormatted: true, expectedXMLString: """
             <pre>
             <code>func doSomething(with first: FirstParameterValue, and second: SecondParameterValue) throws-&gt; ReturnValue</code>
             </pre>
@@ -552,7 +552,7 @@ struct MarkdownRenderer_PageElementsTests {
 
         switch goal {
         case .richness:
-            #expect(groupedSection.rendered(prettyFormatted: true) == """
+            groupedSection.assertMatches(prettyFormatted: true, expectedXMLString: """
             <section id="\(expectedSectionID)">
             <h2>
                 <a href="#\(expectedSectionID)">\(expectedGroupTitle)</a>
@@ -615,7 +615,7 @@ struct MarkdownRenderer_PageElementsTests {
             </section>
             """)
         case .conciseness:
-            #expect(groupedSection.rendered(prettyFormatted: true) == """
+            groupedSection.assertMatches(prettyFormatted: true, expectedXMLString: """
             <h2>\(expectedGroupTitle)</h2>
             <h3>Group title</h3>
             <p>Some description of this group</p>

Tests/DocCHTMLTests/MarkdownRendererTests.swift

@@ -573,9 +573,7 @@ struct MarkdownRendererTests {
             )
         )
         let htmlNodes = Document(parsing: markdownContent, options: .parseSymbolLinks).children.map { renderer.visit($0) }
-        let htmlString = htmlNodes.rendered(prettyFormatted: prettyFormatted)
-        
-        #expect(htmlString == expectedHTML, sourceLocation: sourceLocation)
+        htmlNodes.assertMatches(prettyFormatted: prettyFormatted, expectedXMLString: expectedHTML, sourceLocation: sourceLocation)
     }
 
     private func makeExampleMethodWithDifferentLanguageRepresentations() -> LinkedElement {
@@ -610,7 +608,11 @@ struct MarkdownRendererTests {
 // MARK: Helpers
 
 extension XMLNode {
-    func rendered(prettyFormatted: Bool) -> String {
+    func assertMatches(prettyFormatted: Bool, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+        _assertMatches(actualXMLString: rendered(prettyFormatted: prettyFormatted), expectedXMLString: expectedXMLString, sourceLocation: sourceLocation)
+    }
+    
+    fileprivate func rendered(prettyFormatted: Bool) -> String {
         if prettyFormatted {
             xmlString(options: [.nodePrettyPrint, .nodeCompactEmptyElement])
         } else {
@@ -620,19 +622,49 @@ extension XMLNode {
 }
 
 extension Sequence<XMLNode> {
-    func rendered(prettyFormatted: Bool) -> String {
+    func assertMatches(prettyFormatted: Bool, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+        _assertMatches(actualXMLString: rendered(prettyFormatted: prettyFormatted), expectedXMLString: expectedXMLString, sourceLocation: sourceLocation)
+    }
+    
+    private func rendered(prettyFormatted: Bool) -> String {
         map { $0.rendered(prettyFormatted: prettyFormatted) }
             .joined(separator: prettyFormatted ? "\n" : "")
     }
 }
 
 extension Sequence<XMLElement> {
-    func rendered(prettyFormatted: Bool) -> String {
+    func assertMatches(prettyFormatted: Bool, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+        _assertMatches(actualXMLString: rendered(prettyFormatted: prettyFormatted), expectedXMLString: expectedXMLString, sourceLocation: sourceLocation)
+    }
+    
+    private func rendered(prettyFormatted: Bool) -> String {
         map { $0.rendered(prettyFormatted: prettyFormatted) }
             .joined(separator: prettyFormatted ? "\n" : "")
     }
 }
 
+private func _assertMatches(actualXMLString: String, expectedXMLString: String, sourceLocation: Testing.SourceLocation = #_sourceLocation) {
+    // XMLNode on macOS and Linux pretty print with different indentation.
+    // To compare the XML structure without getting false positive failures because of indentation and other formatting differences,
+    // we explicitly process each string into an easy-to-compare format.
+    func formatForTestComparison(_ xmlString: String) -> String {
+        // This is overly simplified and won't result in "pretty" XML for general use but sufficient for test content comparisons
+        xmlString
+            // Put each tag on its own line
+            .replacingOccurrences(of: ">", with: ">\n")
+            // Remove leading indentation
+            .components(separatedBy: .newlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .joined(separator: "\n")
+            // Explicitly escape a few HTML characters that appear in the test content
+            .replacingOccurrences(of: "–", with: "&#x2013;") // en-dash
+            .replacingOccurrences(of: "—", with: "&#x2014;") // em-dash
+    }
+    
+    #expect(formatForTestComparison(actualXMLString) == formatForTestComparison(expectedXMLString), sourceLocation: sourceLocation)
+}
+
 struct SingleValueLinkProvider: LinkProvider {
     var elementToReturn: LinkedElement?
     func element(for path: URL) -> LinkedElement? {

Tests/SwiftDocCUtilitiesTests/FileWritingHTMLContentConsumerTests.swift

@@ -183,8 +183,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
                     ╰─ index.html
         """)
 
-        
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -228,7 +227,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
 
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -274,7 +273,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
 
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/somemethod(with:and:)/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/someclass/somemethod(with:and:)/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -339,7 +338,7 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
         </html>
         """)
 
-        XCTAssertEqual(try XCTUnwrap(String(data: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/somearticle/index.html")), encoding: .utf8)), """
+        try assert(readHTML: fileSystem.contents(of: URL(fileURLWithPath: "/output-dir/documentation/modulename/somearticle/index.html")), matches: """
         <html>
           <head>
             <meta charset="utf-8" />
@@ -387,6 +386,8 @@ final class FileWritingHTMLContentConsumerTests: XCTestCase {
 
 }
 
+// MARK: Helpers
+
 private class TestOutputConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
     func consume(renderNode: RenderNode) throws { }
     func consume(assetsInBundle bundle: DocumentationBundle) throws { }
@@ -400,3 +401,30 @@ private class TestOutputConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
     func consume(linkResolutionInformation: SerializableLinkResolutionInformation) throws { }
     func consume(externalRenderNode: ExternalRenderNode) throws { }
 }
+
+private func assert(readHTML: Data, matches expectedHTML: String, file: StaticString = #filePath, line: UInt = #line) {
+    // XMLNode on macOS and Linux pretty print with different indentation.
+    // To compare the XML structure without getting false positive failures because of indentation and other formatting differences,
+    // we explicitly process each string into an easy-to-compare format.
+    func formatForTestComparison(_ xmlString: String) -> String {
+        // This is overly simplified and won't result in "pretty" XML for general use but sufficient for test content comparisons
+        xmlString
+            // Put each tag on its own line
+            .replacingOccurrences(of: ">", with: ">\n")
+            // Remove leading indentation
+            .components(separatedBy: .newlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+            .joined(separator: "\n")
+            // Explicitly escape a few HTML characters that appear in the test content
+            .replacingOccurrences(of: "–", with: "&#x2013;") // en-dash
+            .replacingOccurrences(of: "—", with: "&#x2014;") // em-dash
+    }
+    
+    XCTAssertEqual(
+        formatForTestComparison(String(decoding: readHTML, as: UTF8.self)),
+        formatForTestComparison(expectedHTML),
+        file: file,
+        line: line
+    )
+}