Skip to content

📸 Automatic snapshots from Xcode previews. Supports UIKit/AppKit/SwiftUI on iOS/macOS/watchOS/visionOS/tvOS. Browse previews in-app with the Preview Gallery, or save them to PNGs with an XCTest

License

Notifications You must be signed in to change notification settings

EmergeTools/SnapshotPreviews

Folders and files

NameName
Last commit message
Last commit date

Latest commit

b3f2722 Â· Aug 13, 2024
Aug 5, 2024
Jul 27, 2023
Aug 12, 2024
Jul 5, 2024
Aug 13, 2024
Jul 27, 2023
Aug 31, 2023
May 6, 2024
Dec 12, 2023
Jul 27, 2023
Aug 12, 2024
Aug 12, 2024

Repository files navigation

📸 SnapshotPreviews

An all-in-one snapshot testing solution built on Xcode previews. Automatic browsable gallery of previews, and no-code snapshot generation with XCTest. Supports SwiftUI and UIKit previews using PreviewProvider or #Preview and works with any platform that supports SwiftUI.

Installation

Add the package dependency to your Xcode project using the URL of this repository (https://github.com/EmergeTools/SnapshotPreviews-iOS). Link your app to PreviewGallery and (optionally) your XCTest target to Snapshotting and SnapshottingTests.

Features

Preview Gallery

PreviewGallery is an interactive UI built on top of snapshot extraction. It turns your Xcode previews into a gallery of components and features you can access from your application. Xcode is not required to view the previews. You can use it to preview individual components (buttons/rows/icons/etc) or even entire interactive features.

The public API of PreviewGallery is a single SwiftUI View named PreviewGallery. Displaying this view gives you access to the full gallery. For example, you could add a button with navigation like this:

import SwiftUI
import PreviewGallery

NavigationLink("Open Gallery") { PreviewGallery() }

The gallery also supports macOS. However, snapshotting does not support macOS.

Local Snapshot Generation

The EmergeTools snapshot testing service automatically handles hosting and diffing your snapshot tests. This Swift Package can be used for locally debugging the snapshots by generating images for each preview as part of a XCTest. You’ll need a unit test target that imports the SnapshottingTests product from this package. Create a test that inherits from SnapshotTest like this:

import SnapshottingTests

class DemoAppPreviewTest: SnapshotTest {

  // Return the type names of previews like "MyApp.MyView._Previews" to selectively render only some previews
  override func snapshotPreviews() -> [String]? {
    return nil
  }
  
  // Use this to exclude some previews from generating
  override func excludedSnapshotPreviews() -> [String]? {
    return nil
  }
}

Note that there are no test functions; they are automatically added at runtime by SnapshotTest. You can return a list of previews from the snapshotPreviews() function based on what preview you are trying to locally validate. The previews will be added as attachements in Xcode’s test results. The test must be run on an iOS simulator (not device).

Note

When you use Preivew macros (#Preview("Display Name")) the name of the snapshot uses the file path and the name, for example: "MyModule/MyFile.swift:Display Name"

Screenshot of Xcode test output

Accessibility Audits

Xcode 15 accessibility audits can also be run locally on any preview. They are run in a UI test (rather than unit test). To enable these tests, inherit from AccessibilityPreviewTest. By default they will use all audit types. To customize the behavior you can override the following functions in your test:

import SnapshottingTests
import Snapshotting

class DemoAppAccessibilityPreviewTest: AccessibilityPreviewTest {

  override func auditType() -> XCUIAccessibilityAuditType {
    return .all
  }

  override func handle(_ issue: XCUIAccessibilityAuditIssue) -> Bool {
    return false
  }
}

See the demo app for a full example.

Accessibility Snapshots

You can also add visualisations of accessibiilty elements to snapshots using the emergeAccessibility function. For example:

struct MyPreview: PreviewProvider {
  static var previews: some View {
    MyView()
      .emergeAccessibility(true)
  }
}

About

📸 Automatic snapshots from Xcode previews. Supports UIKit/AppKit/SwiftUI on iOS/macOS/watchOS/visionOS/tvOS. Browse previews in-app with the Preview Gallery, or save them to PNGs with an XCTest

Resources

License

Stars

Watchers

Forks