Merge remote-tracking branches 'origin/master' and 'fork1/rtl_support_with_test_plans' into main

* origin/master:
  Make image diffing strategies custom scale aware (pointfreeco#336)

* fork1/rtl_support_with_test_plans:
  Update README
  Make configuration directory a subdirectory of file name directory
  Change snapshot directory url when SNAPSHOT_CONFIGURATION_NAME environment variable is available
  Remove layout direction trait override

Author: andreyz

README.md

@@ -192,6 +192,7 @@ end
   - **Subclass-free.** Assert from any XCTest case or Quick spec.
   - **Device-agnostic snapshots.** Render views and view controllers for specific devices and trait collections from a single simulator.
   - **First-class Xcode support.** Image differences are captured as XCTest attachments. Text differences are rendered in inline error messages.
+  - **Support for Xcode Test Plans**. Just add `SNAPSHOT_CONFIGURATION_NAME` environment variable to every Configuration in your test plan (with distinctive names as values) to save separate snapshots for each one of them. It can be used for making UI snapshots with different langauges and locales.
   - **Supports any platform that supports Swift.** Write snapshot tests for iOS, Linux, macOS, and tvOS.
   - **SceneKit, SpriteKit, and WebKit support.** Most snapshot testing libraries don't support these view subclasses.
   - **`Codable` support**. Snapshot encodable data structures into their [JSON](Documentation/Available-Snapshot-Strategies.md#json) and [property list](Documentation/Available-Snapshot-Strategies.md#plist) representations.

Sources/SnapshotTesting/AssertSnapshot.swift

@@ -178,12 +178,16 @@ public func verifySnapshot<Value, Format>(
     do {
       let fileUrl = URL(fileURLWithPath: "\(file)", isDirectory: false)
       let fileName = fileUrl.deletingPathExtension().lastPathComponent
+      
+      /// Support for Xcode 11 test plans and running tests multiple times with different configurations
+      let configurationName = ProcessInfo.processInfo.environment["SNAPSHOT_CONFIGURATION_NAME"]
 
       let snapshotDirectoryUrl = snapshotDirectory.map { URL(fileURLWithPath: $0, isDirectory: true) }
         ?? fileUrl
           .deletingLastPathComponent()
           .appendingPathComponent("__Snapshots__")
           .appendingPathComponent(fileName)
+          .appendingPathComponentIfExists(configurationName)
 
       let identifier: String
       if let name = name {
@@ -311,3 +315,11 @@ func sanitizePathComponent(_ string: String) -> String {
     .replacingOccurrences(of: "\\W+", with: "-", options: .regularExpression)
     .replacingOccurrences(of: "^-|-$", with: "", options: .regularExpression)
 }
+
+private extension URL {
+  func appendingPathComponentIfExists(_ pathComponent: String?) -> URL {
+    guard let pathComponent = pathComponent else { return self }
+    
+    return appendingPathComponent(pathComponent)
+  }
+}

Sources/SnapshotTesting/Common/View.swift

@@ -11,6 +11,12 @@ import UIKit
 import WebKit
 #endif
 
+// Explanation for not providing `layoutDirection` trait in base traits for devices:
+// .init(layoutDirection: .leftToRight) is commented out because of http://www.openradar.me/radar?id=5044259694575616
+// When tests are ran with RTL language (e.g. Arabic), this override does not fully change layout to LTR (due to issue linked above)
+// which causes layout to not be correct on snapshots.
+// When tests are ran with LTR langauge (e.g. English), this override is not needed.
+
 #if os(iOS) || os(tvOS)
 public struct ViewImageConfig {
   public enum Orientation {
@@ -352,8 +358,8 @@ extension UITraitCollection {
       let base: [UITraitCollection] = [
 //        .init(displayGamut: .SRGB),
 //        .init(displayScale: 2),
+//        .init(layoutDirection: .leftToRight), // See explanation at the beginning of the file
         .init(forceTouchCapability: .available),
-        .init(layoutDirection: .leftToRight),
         .init(preferredContentSizeCategory: .medium),
         .init(userInterfaceIdiom: .phone)
       ]
@@ -380,8 +386,8 @@ extension UITraitCollection {
       let base: [UITraitCollection] = [
 //        .init(displayGamut: .P3),
 //        .init(displayScale: 2),
+//        .init(layoutDirection: .leftToRight), // See explanation at the beginning of the file
         .init(forceTouchCapability: .available),
-        .init(layoutDirection: .leftToRight),
         .init(preferredContentSizeCategory: .medium),
         .init(userInterfaceIdiom: .phone)
       ]
@@ -408,8 +414,8 @@ extension UITraitCollection {
       let base: [UITraitCollection] = [
 //        .init(displayGamut: .P3),
 //        .init(displayScale: 3),
+//        .init(layoutDirection: .leftToRight), // See explanation at the beginning of the file
         .init(forceTouchCapability: .available),
-        .init(layoutDirection: .leftToRight),
         .init(preferredContentSizeCategory: .medium),
         .init(userInterfaceIdiom: .phone)
       ]
@@ -436,8 +442,8 @@ extension UITraitCollection {
       let base: [UITraitCollection] = [
 //        .init(displayGamut: .P3),
 //        .init(displayScale: 3),
+//        .init(layoutDirection: .leftToRight), // See explanation at the beginning of the file
         .init(forceTouchCapability: .available),
-        .init(layoutDirection: .leftToRight),
         .init(preferredContentSizeCategory: .medium),
         .init(userInterfaceIdiom: .phone)
       ]
@@ -464,8 +470,8 @@ extension UITraitCollection {
       let base: [UITraitCollection] = [
 //        .init(displayGamut: .P3),
 //        .init(displayScale: 2),
+//        .init(layoutDirection: .leftToRight), // See explanation at the beginning of the file
         .init(forceTouchCapability: .unavailable),
-        .init(layoutDirection: .leftToRight),
         .init(preferredContentSizeCategory: .medium),
         .init(userInterfaceIdiom: .phone)
       ]
@@ -492,8 +498,8 @@ extension UITraitCollection {
       let base: [UITraitCollection] = [
 //        .init(displayGamut: .P3),
 //        .init(displayScale: 3),
+//        .init(layoutDirection: .leftToRight), // See explanation at the beginning of the file
         .init(forceTouchCapability: .available),
-        .init(layoutDirection: .leftToRight),
         .init(preferredContentSizeCategory: .medium),
         .init(userInterfaceIdiom: .phone)
       ]

Sources/SnapshotTesting/Snapshotting/CALayer.swift

@@ -37,7 +37,7 @@ extension Snapshotting where Value == CALayer, Format == UIImage {
   /// - Parameter precision: The percentage of pixels that must match.
   public static func image(precision: Float = 1, traits: UITraitCollection = .init())
     -> Snapshotting {
-      return SimplySnapshotting.image(precision: precision).pullback { layer in
+      return SimplySnapshotting.image(precision: precision, scale: traits.displayScale).pullback { layer in
         renderer(bounds: layer.bounds, for: traits).image { ctx in
           layer.setNeedsLayout()
           layer.layoutIfNeeded()

Sources/SnapshotTesting/Snapshotting/CGPath.swift

@@ -40,7 +40,7 @@ extension Snapshotting where Value == CGPath, Format == UIImage {
   ///
   /// - Parameter precision: The percentage of pixels that must match.
   public static func image(precision: Float = 1, scale: CGFloat = 1, drawingMode: CGPathDrawingMode = .eoFill) -> Snapshotting {
-    return SimplySnapshotting.image(precision: precision).pullback { path in
+    return SimplySnapshotting.image(precision: precision, scale: scale).pullback { path in
       let bounds = path.boundingBoxOfPath
       let format: UIGraphicsImageRendererFormat
       if #available(iOS 11.0, tvOS 11.0, *) {

Sources/SnapshotTesting/Snapshotting/SwiftUIView.swift

@@ -51,7 +51,7 @@ extension Snapshotting where Value: SwiftUI.View, Format == UIImage {
         config = .init(safeArea: .zero, size: size, traits: traits)
       }
 
-      return SimplySnapshotting.image(precision: precision).asyncPullback { view in
+      return SimplySnapshotting.image(precision: precision, scale: traits.displayScale).asyncPullback { view in
         var config = config
 
         let controller: UIViewController

Sources/SnapshotTesting/Snapshotting/UIBezierPath.swift

@@ -11,7 +11,7 @@ extension Snapshotting where Value == UIBezierPath, Format == UIImage {
   ///
   /// - Parameter precision: The percentage of pixels that must match.
   public static func image(precision: Float = 1, scale: CGFloat = 1) -> Snapshotting {
-    return SimplySnapshotting.image(precision: precision).pullback { path in
+    return SimplySnapshotting.image(precision: precision, scale: scale).pullback { path in
       let bounds = path.bounds
       let format: UIGraphicsImageRendererFormat
       if #available(iOS 11.0, tvOS 11.0, *) {

Sources/SnapshotTesting/Snapshotting/UIImage.swift

@@ -4,16 +4,24 @@ import XCTest
 
 extension Diffing where Value == UIImage {
   /// A pixel-diffing strategy for UIImage's which requires a 100% match.
-  public static let image = Diffing.image(precision: 1)
+  public static let image = Diffing.image(precision: 1, scale: nil)
 
   /// A pixel-diffing strategy for UIImage that allows customizing how precise the matching must be.
   ///
   /// - Parameter precision: A value between 0 and 1, where 1 means the images must match 100% of their pixels.
+  /// - Parameter scale: Scale to use when loading the reference image from disk. If `nil` or the `UITraitCollection`s default value of `0.0`, the screens scale is used.
   /// - Returns: A new diffing strategy.
-  public static func image(precision: Float) -> Diffing {
+  public static func image(precision: Float, scale: CGFloat?) -> Diffing {
+    let imageScale: CGFloat
+    if let scale = scale, scale != 0.0 {
+      imageScale = scale
+    } else {
+        imageScale = UIScreen.main.scale
+    }
+
     return Diffing(
       toData: { $0.pngData() ?? emptyImage().pngData()! },
-      fromData: { UIImage(data: $0, scale: UIScreen.main.scale)! }
+      fromData: { UIImage(data: $0, scale: imageScale)! }
     ) { old, new in
       guard !compare(old, new, precision: precision) else { return nil }
       let difference = SnapshotTesting.diff(old, new)
@@ -48,16 +56,17 @@ extension Diffing where Value == UIImage {
 extension Snapshotting where Value == UIImage, Format == UIImage {
   /// A snapshot strategy for comparing images based on pixel equality.
   public static var image: Snapshotting {
-    return .image(precision: 1)
+    return .image(precision: 1, scale: nil)
   }
 
   /// A snapshot strategy for comparing images based on pixel equality.
   ///
   /// - Parameter precision: The percentage of pixels that must match.
-  public static func image(precision: Float) -> Snapshotting {
+  /// - Parameter scale: The scale of the reference image stored on disk.
+  public static func image(precision: Float, scale: CGFloat?) -> Snapshotting {
     return .init(
       pathExtension: "png",
-      diffing: .image(precision: precision)
+      diffing: .image(precision: precision, scale: scale)
     )
   }
 }

Sources/SnapshotTesting/Snapshotting/UIView.swift

@@ -22,7 +22,7 @@ extension Snapshotting where Value == UIView, Format == UIImage {
     )
     -> Snapshotting {
 
-      return SimplySnapshotting.image(precision: precision).asyncPullback { view in
+      return SimplySnapshotting.image(precision: precision, scale: traits.displayScale).asyncPullback { view in
         snapshotView(
           config: .init(safeArea: .zero, size: size ?? view.frame.size, traits: .init()),
           drawHierarchyInKeyWindow: drawHierarchyInKeyWindow,

Sources/SnapshotTesting/Snapshotting/UIViewController.swift

@@ -22,7 +22,7 @@ extension Snapshotting where Value == UIViewController, Format == UIImage {
     )
     -> Snapshotting {
 
-      return SimplySnapshotting.image(precision: precision).asyncPullback { viewController in
+      return SimplySnapshotting.image(precision: precision, scale: traits.displayScale).asyncPullback { viewController in
         snapshotView(
           config: size.map { .init(safeArea: config.safeArea, size: $0, traits: config.traits) } ?? config,
           drawHierarchyInKeyWindow: false,
@@ -48,7 +48,7 @@ extension Snapshotting where Value == UIViewController, Format == UIImage {
     )
     -> Snapshotting {
 
-      return SimplySnapshotting.image(precision: precision).asyncPullback { viewController in
+      return SimplySnapshotting.image(precision: precision, scale: traits.displayScale).asyncPullback { viewController in
         snapshotView(
           config: .init(safeArea: .zero, size: size, traits: traits),
           drawHierarchyInKeyWindow: drawHierarchyInKeyWindow,