Initial commit

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,6 @@
+## Summary 
+
+Briefly summarize your PR
+
+## Author checklist
+- [ ] updated [changelog](CHANGELOG.md) under _Next_ section

.github/workflows/build.yml

@@ -0,0 +1,24 @@
+name: Build
+
+on: 
+  workflow_call:
+  push: 
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  DEVELOPER_DIR: /Applications/Xcode_15.4.app
+
+jobs:
+  build:
+    name: Build
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build
+        run: |
+          set -eo pipefail
+          xcodebuild -scheme ackee-ios-snapshots -destination 'generic/platform=iOS' build | xcbeautify

.gitignore

@@ -0,0 +1,63 @@
+# Xcode
+#
+# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
+
+## User settings
+xcuserdata/
+
+## Obj-C/Swift specific
+*.hmap
+
+## App packaging
+*.ipa
+*.dSYM.zip
+*.dSYM
+
+## Playgrounds
+timeline.xctimeline
+playground.xcworkspace
+
+# Swift Package Manager
+#
+# Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
+# Packages/
+# Package.pins
+# Package.resolved
+# *.xcodeproj
+#
+# Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
+# hence it is not needed unless you have added a package configuration file to your project
+# .swiftpm
+
+.build/
+
+# CocoaPods
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# Pods/
+#
+# Add this line if you want to avoid checking in source code from the Xcode workspace
+# *.xcworkspace
+
+# Carthage
+#
+# Add this line if you want to avoid checking in source code from Carthage dependencies.
+# Carthage/Checkouts
+
+Carthage/Build/
+
+# fastlane
+#
+# It is recommended to not store the screenshots in the git repo.
+# Instead, use fastlane to re-generate the screenshots whenever they are needed.
+# For more information about the recommended setup visit:
+# https://docs.fastlane.tools/best-practices/source-control/#source-control
+
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots/**/*.png
+fastlane/test_output
+.swiftpm

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+- please enter new entries in format 
+
+```
+- <description> (#<PR_number>, kudos to @<author>)
+```
+
+## Next

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ackee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Package.swift

@@ -0,0 +1,33 @@
+// swift-tools-version: 5.10
+
+import PackageDescription
+
+let package = Package(
+    name: "ackee-ios-snapshots",
+    platforms: [
+        .iOS(.v15),
+    ],
+    products: [
+        .library(
+            name: "AckeeSnapshots",
+            targets: ["AckeeSnapshots"]
+        ),
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/pointfreeco/swift-snapshot-testing.git",
+            from: "1.17.4"
+        )
+    ],
+    targets: [
+        .target(
+            name: "AckeeSnapshots",
+            dependencies: [
+                .product(
+                    name: "SnapshotTesting",
+                    package: "swift-snapshot-testing"
+                ),
+            ]
+        ),
+    ]
+)

README.md

@@ -0,0 +1,67 @@
+# Ackee Snapshots
+
+Set of extensions that we use to simplify out snapshot tests using [SnapshotTesting][snapshot-testing]
+
+## Installation
+
+As [SnapshotTesting][snapshot-testing] is only available through SPM, this is the only installation option for AckeeSnapshots too.
+
+Just add it to your _Package.swift_ or your Xcode project.
+
+
+## Usage
+
+In your shared testing framework (we recommend using it and including it to all your test targets) define shared instance of [SnapshotTest](Sources/AckeeSnapshots/SnapshotTest.swift) object:
+```swift
+public let assertSnapshot = SnapshotTest(
+  devices: [
+    .iPhone8,
+    .iPhone13ProMax,
+    .iPadPro11,
+    .iPadPro12_9
+  ],
+  record: false,
+  displayScale: 1,
+  contentSizes: [.extraExtraExtraLarge, .large, .small],
+  colorSchemes: [.light, .dark]
+)
+```
+And in your test use assert method of your choice:
+```swift
+import AppTesting
+import XCTest
+
+func test_appearance() {
+  assertSnapshot.devices(SubjectView())
+}
+```
+
+## Recommendations
+
+As we use snapshot tests for quite a long time, we have developed several practices that we consider good:
+
+### Use [Git LFS](https://git-lfs.com) for storing snapshots
+At the beginning you will have a few snapshots so it will not matter, but think about the future. 
+If you really snapshot a lot, you might end up with hundreds of megabytes of images, that means that all developers
+will have all snapshots stored locally at any time (unless you use a shallow clone, which is not very practical for development).
+
+When using LFS all files are just pointers to the actual files and you can have only snapshots that are relevant for your current commit.
+
+### Think of what devices are relevant for you
+
+Trying to cover all devices/font sizes that your app supports is probably a bad idea. The tests will take forever and will use a lot of space, 
+that increases pull/clone time and makes development a bit more complicated.
+
+We usually use one iPhone with home button, one iPhone with home indicator and the same with iPads. 
+For dynamic type we stick with `large` that is default and one smaller and one larger size.
+Color schemes are only to so we snapshot both of them it app supports dark mode.
+
+This creates a reasonable set of snapshots that truly help us in development.
+
+### Use lower display scale
+
+Having real life snapshots is nice, but once you start snapshotting a 13-inch iPad, a single snapshot can easily have over 10 MB.
+This way your repository or LFS storage will grow rapidly, we generally recommend using `displayScale: 1` for snapshots as they are pretty decent
+to discover major problems in the app and use really low amount of disk space.
+
+[snapshot-testing]: https://github.com/pointfreeco/swift-snapshot-testing/tree/main

Sources/AckeeSnapshots/SnapshotColorScheme.swift

@@ -0,0 +1,48 @@
+import UIKit
+
+/// An enumeration representing the color scheme for snapshot testing.
+///
+/// This enum defines three possible color schemes:
+/// - `.light`: A light color scheme, typically used for light-themed user interfaces.
+/// - `.dark`: A dark color scheme, used for dark-themed user interfaces.
+/// - `.unspecified`: An unspecified color scheme, where the color scheme is not explicitly defined.
+///
+/// Use this enum to specify the color scheme when configuring snapshots for testing different
+/// appearance modes.
+public enum SnapshotColorScheme {
+    case light
+    case dark
+    case unspecified
+}
+
+public extension SnapshotColorScheme {
+    /// Maps the `SnapshotColorScheme` to its corresponding `UIUserInterfaceStyle`.
+    ///
+    /// The `UIUserInterfaceStyle` is used to define the appearance of the user interface
+    /// based on the color scheme. This property is useful for applying the appropriate
+    /// interface style in a snapshot testing context.
+    ///
+    /// - Returns: The `UIUserInterfaceStyle` that corresponds to the color scheme.
+    var uiUserInterfaceStyle: UIUserInterfaceStyle {
+        switch self {
+        case .light: return .light
+        case .dark: return .dark
+        case .unspecified: return .unspecified
+        }
+    }
+
+    /// Returns the name of the color scheme as a `String`.
+    ///
+    /// This property provides a textual representation of the color scheme, which can be
+    /// useful for logging, debugging, or for use in file names or identifiers related to
+    /// snapshots.
+    ///
+    /// - Returns: A `String` representing the name of the color scheme.
+    var name: String {
+        switch self {
+        case .light: return "light"
+        case .dark: return "dark"
+        case .unspecified: return "unspecified"
+        }
+    }
+}

Sources/AckeeSnapshots/SnapshotContentSize.swift

@@ -0,0 +1,88 @@
+import UIKit
+
+/// Represents the various content size categories for snapshots.
+public enum SnapshotContentSize {
+    /// Represents an unspecified content size category.
+    case unspecified
+
+    /// Represents the extra small content size category.
+    case extraSmall
+
+    /// Represents the small content size category.
+    case small
+
+    /// Represents the medium content size category.
+    case medium
+
+    /// Represents the large content size category.
+    case large
+
+    /// Represents the extra large content size category.
+    case extraLarge
+
+    /// Represents the extra extra large content size category.
+    case extraExtraLarge
+
+    /// Represents the extra extra extra large content size category.
+    case extraExtraExtraLarge
+
+    /// Represents the medium accessibility content size category.
+    case accessibilityMedium
+
+    /// Represents the large accessibility content size category.
+    case accessibilityLarge
+
+    /// Represents the extra large accessibility content size category.
+    case accessibilityExtraLarge
+
+    /// Represents the extra extra large accessibility content size category.
+    case accessibilityExtraExtraLarge
+
+    /// Represents the extra extra extra large accessibility content size category.
+    case accessibilityExtraExtraExtraLarge
+}
+
+public extension SnapshotContentSize {
+    /// Converts `SnapshotContentSize` to its corresponding `UIContentSizeCategory`.
+    ///
+    /// - Returns: The `UIContentSizeCategory` that corresponds to the `SnapshotContentSize` case.
+    var uiContentSizeCategory: UIContentSizeCategory {
+        switch self {
+        case .unspecified: return .unspecified
+        case .extraSmall: return .extraSmall
+        case .small: return .small
+        case .medium: return .medium
+        case .large: return .large
+        case .extraLarge: return .extraLarge
+        case .extraExtraLarge: return .extraExtraLarge
+        case .extraExtraExtraLarge: return .extraExtraExtraLarge
+        case .accessibilityMedium: return .accessibilityMedium
+        case .accessibilityLarge: return .accessibilityLarge
+        case .accessibilityExtraLarge: return .accessibilityExtraLarge
+        case .accessibilityExtraExtraLarge: return .accessibilityExtraExtraLarge
+        case .accessibilityExtraExtraExtraLarge: return .accessibilityExtraExtraExtraLarge
+        }
+    }
+
+    /// Provides a human-readable name for each `SnapshotContentSize` case.
+    ///
+    /// - Returns: A string representing a user-friendly name for the `SnapshotContentSize` case.
+    var name: String {
+        switch self {
+        case .unspecified: return "unspecified"
+        case .extraSmall: return "sizeXS"
+        case .small: return "sizeS"
+        case .medium: return "sizeM"
+        case .large: return "sizeL"
+        case .extraLarge: return "sizeXL"
+        case .extraExtraLarge: return "sizeXXL"
+        case .extraExtraExtraLarge: return "sizeXXXL"
+        case .accessibilityMedium: return "a11ySizeM"
+        case .accessibilityLarge: return "a11ySizeL"
+        case .accessibilityExtraLarge: return "a11ySizeXL"
+        case .accessibilityExtraExtraLarge: return "a11ySizeXXL"
+        case .accessibilityExtraExtraExtraLarge: return "a11ySizeXXXL"
+        }
+    }
+
+}