Discourage using unrealistic catalog inputs in tests (#1106)

* Discourage future use of the "TestBundle" by renaming it. This example catalog contains significant handcrafted data that doesn't reflect realistic inputs. * Update tests that don't need a catalog input to use an empty context. * Update `SymbolGraphRelationshipsBuilderTests` to not load any catalog * Update name of test specifically about the unrealistic test catalog * Create minimal catalog for final remaining `ChoiceTests` test case * Create minimal catalog for final remaining `VolumeTests` test case * Avoid referencing an input catalog for image size test * Create minimal catalog for `NonInclusiveLanguageCheckerTests` * Create minimal catalog for `DiagnosticTests` * Create minimal catalogs for some `DocumentationContextTests` * Update more tests that don't need a catalog input to use an empty context. * Create minimal catalogs for more `DocumentationContextTests` * Create minimal catalogs for some `VideoMediaTests` * Create minimal catalogs for two `SemaToRenderNodeTests` * Create minimal catalogs for a few more `DocumentationContextTests` * Load test catalogs from in-memory file system in many more tests * Rename legacy test bundle again * Resolve some warnings in tests about using `var` for unmutated action
swiftlang · Dec 5, 2024 · 5aa2c45 · 5aa2c45
1 parent cd3f5ba
commit 5aa2c45
Show file tree

Hide file tree

Showing 184 changed files with 971 additions and 925 deletions.
diff --git a/Tests/SwiftDocCTests/Benchmark/ExternalTopicsHashTests.swift b/Tests/SwiftDocCTests/Benchmark/ExternalTopicsHashTests.swift
@@ -39,7 +39,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
 
     func testNoMetricAddedIfNoExternalTopicsAreResolved() throws {
         // Load bundle without using external resolvers
-        let (_, context) = try testBundleAndContext(named: "TestBundle")
+        let (_, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         XCTAssertTrue(context.externallyResolvedLinks.isEmpty)
 
         // Try adding external topics metrics
@@ -55,7 +55,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
 
         // Add external links and verify the checksum is always the same
         let hashes: [String] = try (0...10).map { _ -> MetricValue? in
-            let (_, _, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
+            let (_, _, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
             try """
             # ``SideKit/SideClass``
 
@@ -93,7 +93,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
 
         // Add external links and verify the checksum is always the same
         let hashes: [String] = try (0...10).map { _ -> MetricValue? in
-            let (_, _, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [externalResolver.bundleID: externalResolver], externalSymbolResolver: externalSymbolResolver) { url in
+            let (_, _, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [externalResolver.bundleID: externalResolver], externalSymbolResolver: externalSymbolResolver) { url in
             try """
             # ``SideKit/SideClass``
 
@@ -131,7 +131,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
         let externalResolver = self.externalResolver
 
         // Load a bundle with external links
-        let (_, _, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
+        let (_, _, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
         try """
         # ``SideKit/SideClass``
 

diff --git a/Tests/SwiftDocCTests/Benchmark/TopicGraphHashTests.swift b/Tests/SwiftDocCTests/Benchmark/TopicGraphHashTests.swift
@@ -14,7 +14,7 @@ import XCTest
 class TopicGraphHashTests: XCTestCase {
     func testTopicGraphSameHash() throws {
         let hashes: [String] = try (0...10).map { _ -> MetricValue? in
-            let (_, context) = try testBundleAndContext(named: "TestBundle")
+            let (_, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
             let testBenchmark = Benchmark()
             benchmark(add: Benchmark.TopicGraphHash(context: context), benchmarkLog: testBenchmark)
             return testBenchmark.metrics[0].result
@@ -32,7 +32,7 @@ class TopicGraphHashTests: XCTestCase {
     func testTopicGraphChangedHash() throws {
         // Verify that the hash changes if we change the topic graph
         let initialHash: String
-        let (_, context) = try testBundleAndContext(named: "TestBundle")
+        let (_, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
 
         do {
             let testBenchmark = Benchmark()
@@ -88,7 +88,7 @@ class TopicGraphHashTests: XCTestCase {
             "/externally/resolved/path/to/article2": .success(.init(referencePath: "/externally/resolved/path/to/article2")),
         ]
 
-        let (_, bundle, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [
+        let (_, bundle, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [
             "com.external.testbundle" : resolver
         ]) { url in
             // Add external links to the MyKit Topics.

diff --git a/Tests/SwiftDocCTests/Checker/Checkers/NonInclusiveLanguageCheckerTests.swift b/Tests/SwiftDocCTests/Checker/Checkers/NonInclusiveLanguageCheckerTests.swift
@@ -11,6 +11,7 @@
 import XCTest
 import Markdown
 @testable import SwiftDocC
+import SwiftDocCTestUtilities
 
 class NonInclusiveLanguageCheckerTests: XCTestCase {
 
@@ -167,9 +168,9 @@ func aBlackListedFunc() {
     }
 
     private let nonInclusiveContent = """
-    # ``SideKit``
+    # Some root page
     
-    SideKit module root symbol. And here is a ~~whitelist~~:
+    Some custom root page. And here is a ~~whitelist~~:
     
      - item one
      - item two
@@ -178,11 +179,12 @@ func aBlackListedFunc() {
 
     func testDisabledByDefault() throws {
         // Create a test bundle with some non-inclusive content.
-        let (_, _, context) = try testBundleAndContext(copying: "TestBundle", diagnosticEngine: .init(filterLevel: .error)) { url in
-            try self.nonInclusiveContent.write(to: url.appendingPathComponent("documentation").appendingPathComponent("sidekit.md"), atomically: true, encoding: .utf8)
-        }
+        let catalog = Folder(name: "unit-test.docc", content: [
+            TextFile(name: "Root.md", utf8Content: nonInclusiveContent)
+        ])
+        let (_, context) = try loadBundle(catalog: catalog)
 
-        XCTAssertEqual(context.problems.count, 0)
+        XCTAssertEqual(context.problems.count, 0) // Non-inclusive content is an info-level diagnostic, so it's filtered out.
     }
 
     func testEnablingTheChecker() throws {
@@ -196,9 +198,12 @@ func aBlackListedFunc() {
         ]
 
         for (severity, enabled) in expectations {
-            let (_, _, context) = try testBundleAndContext(copying: "TestBundle", diagnosticEngine: .init(filterLevel: severity)) { url in
-                try self.nonInclusiveContent.write(to: url.appendingPathComponent("documentation").appendingPathComponent("sidekit.md"), atomically: true, encoding: .utf8)
-            }
+            let catalog = Folder(name: "unit-test.docc", content: [
+                TextFile(name: "Root.md", utf8Content: nonInclusiveContent)
+            ])
+            var configuration = DocumentationContext.Configuration()
+            configuration.externalMetadata.diagnosticLevel = severity
+            let (_, context) = try loadBundle(catalog: catalog, diagnosticEngine: .init(filterLevel: severity), configuration: configuration)
 
             // Verify that checker diagnostics were emitted or not, depending on the diagnostic level set.
             XCTAssertEqual(context.problems.contains(where: { $0.diagnostic.identifier == "org.swift.docc.NonInclusiveLanguage" }), enabled)

diff --git a/Tests/SwiftDocCTests/Converter/DocumentationContextConverterTests.swift b/Tests/SwiftDocCTests/Converter/DocumentationContextConverterTests.swift
@@ -14,7 +14,7 @@ import XCTest
 
 class DocumentationContextConverterTests: XCTestCase {
     func testRenderNodesAreIdentical() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
 
         // We'll use this to convert nodes ad-hoc
         let perNodeConverter = DocumentationNodeConverter(bundle: bundle, context: context)
@@ -41,7 +41,7 @@ class DocumentationContextConverterTests: XCTestCase {
     }
 
     func testSymbolLocationsAreOnlyIncludedWhenRequested() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let renderContext = RenderContext(documentationContext: context, bundle: bundle)
 
         let fillIntroducedSymbolNode = try XCTUnwrap(
@@ -71,7 +71,7 @@ class DocumentationContextConverterTests: XCTestCase {
     }
 
     func testSymbolAccessLevelsAreOnlyIncludedWhenRequested() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let renderContext = RenderContext(documentationContext: context, bundle: bundle)
 
         let fillIntroducedSymbolNode = try XCTUnwrap(

diff --git a/Tests/SwiftDocCTests/Converter/RenderContextTests.swift b/Tests/SwiftDocCTests/Converter/RenderContextTests.swift
@@ -14,7 +14,7 @@ import XCTest
 
 class RenderContextTests: XCTestCase {
     func testCreatesRenderReferences() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
 
         let renderContext = RenderContext(documentationContext: context, bundle: bundle)
 

diff --git a/Tests/SwiftDocCTests/Converter/TopicRenderReferenceEncoderTests.swift b/Tests/SwiftDocCTests/Converter/TopicRenderReferenceEncoderTests.swift
@@ -158,7 +158,7 @@ class TopicRenderReferenceEncoderTests: XCTestCase {
     /// Verifies that when JSON encoder should sort keys, the custom render reference cache
     /// respects that setting and prints the referencs in alphabetical order.
     func testSortedReferences() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let converter = DocumentationNodeConverter(bundle: bundle, context: context)
 
         // Create a JSON encoder
@@ -218,7 +218,7 @@ class TopicRenderReferenceEncoderTests: XCTestCase {
 
     // Verifies that there is no extra comma at the end of the references list.
     func testRemovesLastReferencesListDelimiter() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let converter = DocumentationNodeConverter(bundle: bundle, context: context)
 
         // Create a JSON encoder

diff --git a/Tests/SwiftDocCTests/Diagnostics/DiagnosticConsoleWriterDefaultFormattingTest.swift b/Tests/SwiftDocCTests/Diagnostics/DiagnosticConsoleWriterDefaultFormattingTest.swift
@@ -229,7 +229,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         let summary = "Test diagnostic summary"
         let explanation = "Test diagnostic explanation."
         let baseURL =  Bundle.module.url(
-            forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+            forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!
         let source = baseURL.appendingPathComponent("TestTutorial.tutorial")
         let range = SourceLocation(line: 44, column: 59, source: source)..<SourceLocation(line: 44, column: 138, source: source)
 
@@ -307,7 +307,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         let summary = "Test diagnostic summary"
         let explanation = "Test diagnostic explanation."
         let baseURL =  Bundle.module.url(
-            forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+            forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!
         let source = baseURL.appendingPathComponent("TestTutorial.tutorial")
         let diagnosticRange = SourceLocation(line: 44, column: 59, source: source)..<SourceLocation(line: 44, column: 138, source: source)
         let diagnostic = Diagnostic(source: source, severity: .warning, range: diagnosticRange, identifier: identifier, summary: summary, explanation: explanation)

diff --git a/Tests/SwiftDocCTests/Diagnostics/DiagnosticTests.swift b/Tests/SwiftDocCTests/Diagnostics/DiagnosticTests.swift
@@ -79,12 +79,15 @@ class DiagnosticTests: XCTestCase {
 
     /// Test offsetting diagnostic ranges
     func testOffsetDiagnostics() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try loadBundle(catalog: Folder(name: "unit-test.docc", content: [
+            JSONFile(name: "SomeModuleName.symbols.json", content: makeSymbolGraph(moduleName: "SomeModuleName"))
+        ]))
 
         let content = "Test a ``Reference`` in a sentence."
         let markup = Document(parsing: content, source: URL(string: "/tmp/foo.symbols.json"), options: .parseSymbolLinks)
 
-        var resolver = ReferenceResolver(context: context, bundle: bundle, rootReference: ResolvedTopicReference(bundleID: "org.swift.docc.example", path: "/documentation/MyKit", sourceLanguage: .swift))
+        let moduleReference = try XCTUnwrap(context.soleRootModuleReference)
+        var resolver = ReferenceResolver(context: context, bundle: bundle, rootReference: moduleReference)
 
         // Resolve references
         _ = resolver.visitMarkup(markup)

diff --git a/Tests/SwiftDocCTests/DocumentationService/ConvertService/ConvertServiceTests.swift b/Tests/SwiftDocCTests/DocumentationService/ConvertService/ConvertServiceTests.swift
@@ -1383,7 +1383,7 @@ class ConvertServiceTests: XCTestCase {
 
     func testConvertAllPagesForOnDiskContent() throws {
         let testBundleURL = Bundle.module.url(
-            forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+            forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!
 
         let request = ConvertRequest(
             bundleInfo: testBundleInfo,
@@ -1444,7 +1444,7 @@ class ConvertServiceTests: XCTestCase {
 
     func testConvertSomeSymbolsAndSomeArticlesForOnDiskContent() throws {
         let testBundleURL = Bundle.module.url(
-            forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+            forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!
 
         let request = ConvertRequest(
             bundleInfo: testBundleInfo,
@@ -1468,7 +1468,7 @@ class ConvertServiceTests: XCTestCase {
 
     func testConvertNoSymbolsAndNoArticlesForOnDiskContent() throws {
         let testBundleURL = Bundle.module.url(
-            forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+            forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!
 
         let request = ConvertRequest(
             bundleInfo: testBundleInfo,
@@ -1495,7 +1495,7 @@ class ConvertServiceTests: XCTestCase {
         """)
         #else
         let (testBundleURL, _, _) = try testBundleAndContext(
-            copying: "TestBundle",
+            copying: "LegacyBundle_DoNotUseInNewTests",
             excludingPaths: [
                 "sidekit.symbols.json",
                 "mykit-iOS.symbols.json",
@@ -1624,7 +1624,7 @@ class ConvertServiceTests: XCTestCase {
         """)
         #else
         let (testBundleURL, _, _) = try testBundleAndContext(
-            copying: "TestBundle",
+            copying: "LegacyBundle_DoNotUseInNewTests",
             excludingPaths: [
                 "mykit-iOS.symbols.json",
                 "[email protected]",

diff --git a/Tests/SwiftDocCTests/Indexing/IndexingTests.swift b/Tests/SwiftDocCTests/Indexing/IndexingTests.swift
@@ -15,7 +15,7 @@ class IndexingTests: XCTestCase {
 
     // MARK: - Tutorial
     func testTutorial() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let tutorialReference = ResolvedTopicReference(bundleID: "org.swift.docc.example", path: "/tutorials/Test-Bundle/TestTutorial", sourceLanguage: .swift)
         let node = try context.entity(with: tutorialReference)
         let tutorial = node.semantic as! Tutorial
@@ -89,7 +89,7 @@ class IndexingTests: XCTestCase {
     // MARK: - Article
 
     func testArticle() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let articleReference = ResolvedTopicReference(bundleID: "org.swift.docc.example", path: "/tutorials/Test-Bundle/TestTutorialArticle", sourceLanguage: .swift)
         let node = try context.entity(with: articleReference)
         let article = node.semantic as! TutorialArticle
@@ -187,7 +187,7 @@ class IndexingTests: XCTestCase {
     }
 
     func testRootPageIndexingRecord() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let articleReference = ResolvedTopicReference(bundleID: "org.swift.docc.example", path: "/documentation/MyKit", sourceLanguage: .swift)
         let node = try context.entity(with: articleReference)
         let article = node.semantic as! Symbol
@@ -207,7 +207,7 @@ class IndexingTests: XCTestCase {
     }
 
     func testSymbolIndexingRecord() throws {
-        let (_, bundle, context) = try testBundleAndContext(copying: "TestBundle") { url in
+        let (_, bundle, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests") { url in
             // Modify the documentaion to have default availability for MyKit so that there is platform availability
             // information for MyProtocol (both in the render node and in the indexing record.
             let plistURL = url.appendingPathComponent("Info.plist")