{"id":13466101,"url":"https://github.com/parski/SnapshotTest","last_synced_at":"2025-03-25T21:31:14.443Z","repository":{"id":27077861,"uuid":"108688804","full_name":"parski/SnapshotTest","owner":"parski","description":"Snapshot testing tool for iOS and tvOS","archived":true,"fork":false,"pushed_at":"2022-07-22T01:02:44.000Z","size":525,"stargazers_count":41,"open_issues_count":14,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-02T05:46:41.841Z","etag":null,"topics":["ios","testing-tools","tvos"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing Guidelines.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-28T22:28:53.000Z","updated_at":"2024-10-04T09:12:05.000Z","dependencies_parsed_at":"2022-07-27T09:22:05.361Z","dependency_job_id":null,"html_url":"https://github.com/parski/SnapshotTest","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parski%2FSnapshotTest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parski%2FSnapshotTest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parski%2FSnapshotTest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parski%2FSnapshotTest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parski","download_url":"https://codeload.github.com/parski/SnapshotTest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245547258,"owners_count":20633336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ios","testing-tools","tvos"],"created_at":"2024-07-31T15:00:39.121Z","updated_at":"2025-03-25T21:31:14.062Z","avatar_url":"https://github.com/parski.png","language":"Swift","funding_links":[],"categories":["Libs","Testing [🔝](#readme)","HarmonyOS","Swift"],"sub_categories":["Testing","Windows Manager"],"readme":"\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://raw.githubusercontent.com/parski/SnapshotTest/master/logo.png\" width=\"540\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://travis-ci.org/parski/SnapshotTest\"\u003e\u003cimg src=\"https://img.shields.io/travis/rust-lang/rust/master.svg?style=flat-square\" alt=\"master\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**SnapshotTest** is a simple view testing tool written completely in Swift to aid with development for Apple platforms. It's like unit testing for views.\n\n### How\nWhen **record mode** is active a snapshot assertion will record an image of the view and save it to a **specified directory**. This will cause the test to fail. When record mode is deactivated the snapshot assertion will record an image of the view and compare it to the saved reference image. Should they differ the test will fail.\n\n### Setup\nAll SnapshotTest needs to know is where to save the reference images. This directory is specified using a test scheme environmental variable using the key: \n\n```\nREFERENCE_IMAGE_DIR\n```\n\nRecommended reference image directory path is: \n\n```\n$(SOURCE_ROOT)/$(PROJECT_NAME)Tests/ReferenceImages\n```\nIt should look something like this:\n\n![Test scheme arguments.](https://raw.githubusercontent.com/parski/SnapshotTest/master/reference_image_directory.png)\n\n### Usage\nIf you are familiar with **XCTest** using **SnapshotTest** will be a breeze. Instead of subclassing **XCTestCase** you just need to subclass **SnapshotTestCase** and assert the view using `AssertSnapshot()` to test it.\n\n```swift\nclass ViewTests: SnapshotTestCase {\n    \n    func testView_withAlteration() {\n        // Given\n        let view = View(frame: CGRect(x: 0, y: 0, width: 375, height: 100))\n        \n        // When\n        view.alter()\n        \n        // Then\n        AssertSnapshot(view)\n    }\n    \n}\n```\nCurrently **UIView**, **UIViewController** and **CALayer** are supported.\n\n### Record mode\nRecord mode records a snapshot of your view within the current scope and stores it in the reference directory to compare with any subsequent assertions.\n  \nNote that record mode will fail the test and output the reference image path to the console.\n  \n```\n🔴 RECORD MODE: Reference image saved to /Users/snap/App/AppTests/ReferenceImages/View/testView_withAlteration.png\n```\n\n#### Test case\n\nTo set the test case to record mode simply change the `recordMode` property to true.\n\n```swift\nclass ViewTests: SnapshotTestCase {\n    \n    override func setUp() {\n        super.setUp()\n        recordMode = true\n    }\n    \n}\n```\n\nThe assertion will then record and save a reference image.\n\n#### Global\n\nTo set record mode globally and record all snapshots for every assertion, set the class variable `recordMode` instead.\n\n```swift\nSnapshotTestCase.recordMode = true\n```\n\nNote that you will probably need to set up a [principal class](#principal-class) to guarantee that record mode is activated before your test suite is run.\n\n#### Statement\n\nTo explicitly record a single snapshot you can instead use the `RecordSnapshot()` function:\n\n```swift\nclass ViewTests: SnapshotTestCase {\n    \n    func testView_withAlteration() {\n        // Given\n        let view = View(frame: CGRect(x: 0, y: 0, width: 375, height: 100))\n        \n        // When\n        view.alter()\n        \n        // Then\n        RecordSnapshot(view)\n    }\n    \n}\n```\n\n### Principal class\n\nA principal class is automatically instantiated by `XCTest` when your test bundle is loaded. Think of it as a good place to put a global `setUp()` and `tearDown()`. A simple principal class might look like this:\n\n```swift\nimport SnapshotTest\n\nclass TestObserver : NSObject {\n\n    override init() {\n        SnapshotTestCase.recordMode = true\n    }\n}\n\n```\n\nIn your test bundle's `Info.plist`, add a key value pair:\n\n```\n\u003ckey\u003eNSPrincipalClass\u003c/key\u003e\n\u003cstring\u003eYourAppTests.TestObserver\u003c/string\u003e\n```\n\nWhere `YourAppTests` is the name of your test bundle.\n\nThis will activate record mode globally and is guaranteed to be run before your test suite.\n\n### Options\nSnapshotTest provides different ways to compare snapshots using several options.\n  \n| Option    | Description                                          |\n|-----------|------------------------------------------------------|\n| device    | Compares snapshots specific to a certain device.     |\n| osVersion | Compares snapshots specific to a certain OS version. |\n\nTo use one or several options you just pass them to the options argument of the assertion:\n\n```swift\nAssertSnapshot(view, options: [.device, .osVersion])\n```\n\n### Platforms\nThe following platforms and minimum versions are supported:\n\n* iOS 8.0\n* tvOS 9.0\n\n### Distribution\nUse SnapshotTest by building it and integrating it into your project manually or by using a depencency manager. Currently only CocoaPods is supported with more to come.\n\n#### CocoaPods\nJust add the following line to your Podfile in the scope of your **test target**:\n\n```ruby\ntarget \"MyAppTests\" do\n  use_frameworks!\n  pod 'SnapshotTest' ~\u003e 'X.Y.Z'\nend\n```\nReplace `X.Y.Z` with the starting version you wish to use. Breaking backward compatability will be a last resort kind of deal but specifying version is still recommended.\n\n### Contribute\nSnapshotTest is licensed under the **BSD 2-clause License** and contributions are very welcome in the form of pull requests and issues.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparski%2FSnapshotTest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparski%2FSnapshotTest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparski%2FSnapshotTest/lists"}