Merge branch 'main' into faet/ImageSerializationPlugin

.github/workflows/ci.yml

@@ -13,10 +13,11 @@ jobs:
     strategy:
       matrix:
         xcode:
-          - "14.3.1"
+          - 15.4
+          - '16.0'
 
-    name: macOS 13 (Xcode ${{ matrix.xcode }})
-    runs-on: macos-13
+    name: macOS
+    runs-on: macos-14
     steps:
       - uses: actions/checkout@v3
       - name: Select Xcode ${{ matrix.xcode }}

Sources/SnapshotTesting/AssertSnapshot.swift

@@ -2,9 +2,7 @@ import XCTest
 import ImageSerializationPlugin
 
 #if canImport(Testing)
-  // NB: We are importing only the implementation of Testing because that framework is not available
-  //     in Xcode UI test targets.
-  @_implementationOnly import Testing
+  import Testing
 #endif
 
 /// Whether or not to change the default output image format to something else.
@@ -453,7 +451,9 @@ public func verifySnapshot<Value, Format>(
 
       if !attachments.isEmpty {
         #if !os(Linux) && !os(Windows)
-          if ProcessInfo.processInfo.environment.keys.contains("__XCODE_BUILT_PRODUCTS_DIR_PATHS") {
+          if ProcessInfo.processInfo.environment.keys.contains("__XCODE_BUILT_PRODUCTS_DIR_PATHS"),
+            !isSwiftTesting
+          {
             XCTContext.runActivity(named: "Attached Failure Diff") { activity in
               attachments.forEach {
                 activity.add($0)

Sources/SnapshotTesting/Documentation.docc/Articles/IntegratingWithTestFrameworks.md

@@ -67,21 +67,14 @@ class FeatureTests: XCTestCase {
 
 This will override the `diffTool` and `record` properties for each test function.
 
-Swift's new testing framework does not currently have a public API for this kind of customization.
-There is an experimental feature, called `CustomExecutionTrait`, that does gives us this ability,
-and the library provides such a trait called ``Testing/Trait/snapshots(diffTool:record:)``. It can
-be attached to any `@Test` or `@Suite` to configure snapshot testing:
+Swift's new testing framework also allows for this kind of configuration, both for a single test
+and an entire test suite. This is done via what are known as "test traits":
 
 ```swift
-@_spi(Experimental) import SnapshotTesting
+import SnapshotTesting
 
 @Suite(.snapshots(record: .all, diffTool: .ksdiff))
 struct FeatureTests {
   …
 }
 ```
-
-> Important: You must import SnapshotTesting with the `@_spi(Experimental)` attribute to get access
-to this functionality because Swift Testing's own `CustomExecutionTrait` is hidden behind the same
-SPI flag. This means this API is subject to change in the future, but hopefully Apple will 
-publicize this tool soon.

Sources/SnapshotTesting/Documentation.docc/Articles/MigrationGuides/MigratingTo1.17.md

@@ -151,16 +151,12 @@ in an XCTest context or a Swift Testing context, and will determine if it should
 `Issue.record` to trigger a test failure.
 
 For the most part you can write tests for Swift Testing exactly as you would for XCTest. However,
-there is one major difference. Swift Testing does not (yet) have a substitute for `invokeTest`,
-which we used alongside `withSnapshotTesting` to customize snapshotting for a full test class.
-
-There is an experimental version of this tool in Swift Testing, called `CustomExecutionTrait`, and
-this library provides such a trait called ``Testing/Trait/snapshots(diffTool:record:)``. It allows 
-you to customize snapshots for a `@Test` or `@Suite`, but to get access to it you must perform an
-`@_spi(Experimental)` import of snapshot testing:
+there is one major difference. In order to override a snapshot's 
+[configuration](<doc:SnapshotTestingConfiguration>) for a particular test or an entire suite you
+must use what are known as "test traits":
 
 ```swift
-@_spi(Experimental) import SnapshotTesting
+import SnapshotTesting
 
 @Suite(.snapshots(record: .all, diffTool: .ksdiff))
 struct FeatureTests {
@@ -169,7 +165,4 @@ struct FeatureTests {
 ```
 
 That will override the `diffTool` and `record` options for the entire `FeatureTests` suite.
-
-> Important: As evident by the usage of `@_spi(Experimental)` this API is subject to change. As
-soon as the Swift Testing library finalizes its API for `CustomExecutionTrait` we will update
-the library accordingly and remove the `@_spi` annotation.
+These traits can also be used on individual `@Test`s too.

Sources/SnapshotTesting/Internal/RecordIssue.swift

@@ -1,9 +1,7 @@
 import XCTest
 
 #if canImport(Testing)
-  // NB: We are importing only the implementation of Testing because that framework is not available
-  //     in Xcode UI test targets.
-  @_implementationOnly import Testing
+  import Testing
 #endif
 
 var isSwiftTesting: Bool {

Sources/SnapshotTesting/SnapshotsTestTrait.swift

@@ -1,10 +1,8 @@
 #if canImport(Testing)
-  // NB: We are importing only the implementation of Testing because that framework is not available
-  //     in Xcode UI test targets.
-  @_implementationOnly import Testing
+
   import ImageSerializationPlugin
+  import Testing
 
-  @_spi(Experimental)
   extension Trait where Self == _SnapshotsTestTrait {
     /// Configure snapshot testing in a suite or test.
     ///
@@ -36,7 +34,6 @@
   }
 
   /// A type representing the configuration of snapshot testing.
-  @_spi(Experimental)
   public struct _SnapshotsTestTrait: SuiteTrait, TestTrait {
     public let isRecursive = true
     let configuration: SnapshotTestingConfiguration

Tests/InlineSnapshotTestingTests/AssertInlineSnapshotSwiftTests.swift

@@ -2,7 +2,7 @@
   import Testing
   import Foundation
   import InlineSnapshotTesting
-  @_spi(Experimental) import SnapshotTesting
+  import SnapshotTesting
 
   @Suite(
     .snapshots(
@@ -21,6 +21,28 @@
       }
     }
 
+    @Test func inlineSnapshotFailure() {
+      withKnownIssue {
+        assertInlineSnapshot(of: ["Hello", "World"], as: .dump) {
+          """
+          ▿ 2 elements
+            - "Hello"
+
+          """
+        }
+      } matching: { issue in
+        issue.description == """
+          Issue recorded: Snapshot did not match. Difference: …
+
+            @@ −1,3 +1,4 @@
+             ▿ 2 elements
+               - "Hello"
+            +  - "World"
+             
+          """
+      }
+    }
+
     @Test func inlineSnapshot_NamedTrailingClosure() {
       assertInlineSnapshot(
         of: ["Hello", "World"], as: .dump,

Tests/SnapshotTestingTests/AssertSnapshotSwiftTests.swift

@@ -1,7 +1,7 @@
 #if canImport(Testing)
   import Testing
   import Foundation
-  @_spi(Experimental) import SnapshotTesting
+  import SnapshotTesting
 
   @Suite(
     .snapshots(

Tests/SnapshotTestingTests/SnapshotsTraitTests.swift

@@ -1,6 +1,6 @@
 #if compiler(>=6) && canImport(Testing)
   import Testing
-  @_spi(Experimental) @_spi(Internals) import SnapshotTesting
+  @_spi(Internals) import SnapshotTesting
 
   struct SnapshotsTraitTests {
     @Test(.snapshots(diffTool: "ksdiff"))

Tests/SnapshotTestingTests/SwiftTestingTests.swift

@@ -0,0 +1,26 @@
+#if compiler(>=6) && canImport(Testing)
+  import Testing
+  import SnapshotTesting
+
+  @Suite(.snapshots(diffTool: "ksdiff"))
+  struct SwiftTestingTests {
+    @Test func testSnapshot() {
+      assertSnapshot(of: ["Hello", "World"], as: .dump)
+    }
+
+    @Test func testSnapshotFailure() {
+      withKnownIssue {
+        assertSnapshot(of: ["Goodbye", "World"], as: .dump)
+      } matching: { issue in
+        issue.description.hasSuffix(
+          """
+          @@ −1,4 +1,4 @@
+           ▿ 2 elements
+          −  - "Hello"
+          +  - "Goodbye"
+             - "World"
+          """)
+      }
+    }
+  }
+#endif

Tests/SnapshotTestingTests/__Snapshots__/SwiftTestingTests/testSnapshot.1.txt

@@ -0,0 +1,3 @@
+▿ 2 elements
+  - "Hello"
+  - "World"

Tests/SnapshotTestingTests/__Snapshots__/SwiftTestingTests/testSnapshotFailure.1.txt

@@ -0,0 +1,3 @@
+▿ 2 elements
+  - "Hello"
+  - "World"