📘A library for isolated developing UI components and automatically taking snapshots of them.

Overview

Playbook

A library for isolated developing UI components and automatically taking snapshots of them.

playbook

Playbook

Playbook

Swift5 CI Status Lincense
Release Swift Package Manager CocoaPods Carthage

Playbook is a library that provides a sandbox for building UI components without having to worry about application-specific dependencies, strongly inspired by Storybook for JavaScript in web-frontend development.

Components built by using Playbook can generate a standalone app as living styleguide.
This allows you to not only review UI quickly but also deliver more robost designs by separating business logics out of components.

Besides, snapshots of each component can be automatically generated by unit tests, and visual regression testing can be performed using arbitrary third-party tools.

For complex modern app development, it’s important to catch UI changes more sensitively and keep improving them faster.
With the Playbook, you don't have to struggle through preparing the data and spend human resources for manual testings.



Usage


Playbook

Playbook is a framework that provides the basic functionality for managing components. It supports both SwiftUI and UIKit.
Components are uniquely stored as scenarios. A Scenario has the way to layout component. Please check the API Doc for the variety of layouts.

Playbook.default.addScenarios(of: "Home") {
    Scenario("CategoryHome", layout: .fill) {
        CategoryHome().environmentObject(UserData.stub)
    }

    Scenario("LandmarkList", layout: .fill) {
        NavigationView {
            LandmarkList().environmentObject(UserData.stub)
        }
    }

    Scenario("UIView red", layout: .fixed(length: 100)) {
        let view = UIView()
        view.backgroundColor = .red
        return view
    }
}

ScenarioProvider allows you to isolate additional scenarios and keep your playbook building clean.

struct HomeScenarios: ScenarioProvider {
    static func addScenarios(into playbook: Playbook) {
        playbook.addScenarios(of: "Home") {
            Scenario("CategoryHome", layout: .fill) {
                CategoryHome().environmentObject(UserData.stub)
            }
        }
    }
}

struct AllScenarios: ScenarioProvider {
    static func addScenarios(into playbook: Playbook) {
        playbook.add(HomeScenarios.self)
    }
}

You can use the ScenarioContext passed to the closure that creates the component to get the screen size in snapshot, or wait before generating a snapshot.

Scenario("MapView", layout: .fill) { context in
    MapView(coordinate: landmarkData[10].locationCoordinate) {
        // This closure will called after the map has completed to render.
        context.snapshotWaiter.fulfill()
     }
     .onAppear(perform: context.snapshotWaiter.wait)
}

PlaybookUI

PlaybookUI is a framework that provides user interfaces made by SwiftUI for browsing a list of scenarios.

PlaybookGallery

The component visuals are listed and displayed.
Those that are displayed on the top screen are not actually doing layout, but rather display the snapshots that are efficiently generated at runtime.

Browser Detail
Gellery LightGellery Dark Gellery Content LightGellery Content Dark

PlaybookCatalog

The UI that search and select a scenario in a drawer. It's more similar to Storybook.
If you have too many scenarios, this may be more efficient than PlaybookCatalog.

Browser Detail
Catalog Drawer LightCatalog Drawer Dark Catalog LightCatalog Dark

How to Save Snapshot Images

To save snapshot images to the photo library from the share button on each UI, NSPhootLibraryAddUsageDescription must be supported. See the official document for more information.


PlaybookSnapshot

Scenarios can be tested by the instance of types conform to TestTool protocol.
Snapshot is one of them, which can generate the snapshots of all scenarios with simulate the screen size and safe area of the given devices.
Since Playbook doesn't depend on XCTest, it doesn't necessarily need to be run on Unit-test.

final class SnapshotTests: XCTestCase {
    func testTakeSnapshot() throws {
        let directory = ProcessInfo.processInfo.environment["SNAPSHOT_DIR"]!

        try Playbook.default.run(
            Snapshot(
                directory: URL(fileURLWithPath: directory),
                clean: true,
                format: .png,
                keyWindow: UIApplication.shared.windows.first { $0.isKeyWindow },
                devices: [.iPhone11Pro(.portrait)]
            )
        )
    }
}

generate images


PlaybookAccessibilitySnapshot

An extension to Playbook that uses AccessibilitySnapshot to produce snapshots with accessibility information such as activation points and labels.

accessibility-snapshot


Integration with Third-party Tools

The generated snapshot images can be used for more advanced visual regression testing by using a variety of third party tools.

percy

percy

reg-viz/reg-suit

reg-suit


Requirements

  • Swift 5.1+
  • Xcode 11.0+
  • iOS
    • Playbook: 11.0+
    • PlaybookSnapshot: 11.0+
    • PlaybookUI: 13.0+

Installation

Playbook features are separated into the following frameworks.

  • Playbook: Core system of component management.
  • PlaybookSnapshot: Generates snapshots of all components.
  • PlaybookUI: Products a browsing UI for components managed by Playbook.

CocoaPods

Add the following to your Podfile:

target 'YourPlaybook' do
  pod 'Playbook'
  pod 'PlaybookUI'

  target 'YourPlaybookTests' do
    inherit! :search_paths

    pod 'PlaybookSnapshot'
  end
end

Carthage

Add the following to your Cartfile:

github "playbook-ui/playbook-ios"

Swift Package Manager

Select Xcode menu File > Swift Packages > Add Package Dependency... and enter repository URL with GUI.

Repository: https://github.com/playbook-ui/playbook-ios

Note: Currently, SwiftPM doesn't support specifying the OS version for each library, so only iOS13 is supported.


License

Playbook is released under the Apache 2.0 License.


Playbook

Comments
  • Scenario names containing the path separator (`/`) causes test failure

    Scenario names containing the path separator (`/`) causes test failure

    Checklist

    • [x] This is not a Apple's bug.
    • [x] Reviewed the README and documents.
    • [x] Searched existing issues for ensure not duplicated.

    Description (Include Screenshots)

    Hi, I found that scenario names containing the path separator (/) can be problematic.

    When it's used in the name of a group of scenarios, it's recognized literally as a path separator and makes additional directory structure. I couldn't figure out whether this is an intended behavior or not.

    Screen Shot 2020-11-05 at 14 31 56

    When it's in a scenario name, it causes the test to fail with an error "No such file or directory." I guess it's a bit confusing, and would be best to be avoided.

    image

    A few possible ways to improve it I have in my mind:

    • Encode the entire name in a URL safe way such as addingPercentEncoding
    • Replace only / with another (say, _)
    • Throw an error with an improved message like "You cannot use / in a scenario name"

    Encoding the whole is indeed the most safe way, but will make the report generated by reg-suit ugly. What do you think?

    Last but not least, thank you for sharing and maintaining this great project!

    Steps to Reproduce

    Contain / in names; see screenshots above.

    Reproducible Demo Project

    Reproducible with the example project.

    Environments

    • Library version: Checked with the example in master (c8c14d7b066c)
    • Swift version: Apple Swift version 5.3 (swiftlang-1200.0.29.2 clang-1200.0.30.1)
    • iOS version: 14
    • Xcode version: Version 12.1 (12A7403)
    • Devices/Simulators: iPhone 12
    • Package manager version: N/A
    opened by akkyie 6
  • Support for AccessibilitySnapshot

    Support for AccessibilitySnapshot

    Checklist

    • [x] All tests are passed.
    • [x] Added tests or Playbook scenario.
    • [x] Documented the code using Xcode markup.
    • [x] Searched existing pull requests for ensure not duplicated.

    Description

    In order to create an extension to Playbook for accessibility testing, the UIView of the scenario snapshot is needed. The function makeResource is split into two parts: creating the UIView using SnapshotWindow and generating the image data of the UIView.

    Motivation and Context

    This is to create PlaybookAccessibility (WIP) and it uses AccessibilitySnapshot. To do this:

    1. AccessibilitySnapshot takes the UIView of a scenario using SnapshotSupport.view(...)
    2. An AccessibilitySnapshotView is generated
    3. AccessibilitySnapshotView is passed to snapshotSupport.data(for: view, ...) to generate image data for saving
    opened by jiayi-zhou 2
  • Mention the purpose of the document

    Mention the purpose of the document

    Checklist

    • [x] This is not a Apple's bug.
    • [x] Reviewed the README and documents.
    • [x] Searched existing issues for ensure not duplicated.

    Description (Include Screenshots)

    Mention the purpose of the document located at https://playbook-ui.github.io/playbook-ios/. The document lists APIS. However, it nowhere mentions that it is an API document. Please provide an appropriate title/heading.

    Steps to Reproduce

    1. Go to https://playbook-ui.github.io/playbook-ios/.
    2. In the menu on the left, read headings.
    3. Review if you can read API document anywhere.

    Reproducible Demo Project

    Environments

    • Library version:

    • Swift version:

    • iOS version:

    • Xcode version:

    • Devices/Simulators:

    • Package manager version:

    opened by vitish 2
  • Incorrect article

    Incorrect article

    Checklist

    • [x] This is not a Apple's bug.
    • [x] Reviewed the README and documents.
    • [x] Searched existing issues for ensure not duplicated.

    Description (Include Screenshots)

    At the https://playbook-ui.github.io/playbook-ios/Playbook.html, in ScenarioStore, in the Parameters section, in the first bullet point, instead of an write a.

    Steps to Reproduce

    1. Go to https://playbook-ui.github.io/playbook-ios/.
    2. Click the ScenarioStore
    3. In the Parameters section, in the first bullet point, instead of an write a.

    Reproducible Demo Project

    Environments

    • Library version:

    • Swift version:

    • iOS version:

    • Xcode version:

    • Devices/Simulators:

    • Package manager version:

    opened by vitish 2
  • Fix typo and broken link in README

    Fix typo and broken link in README

    Checklist

    • ~[ ] All tests are passed.~
    • ~[ ] Added tests or Playbook scenario.~
    • ~[ ] Documented the code using Xcode markup.~
    • ~[ ] Searched existing pull requests for ensure not duplicated.~

    Description

    This PR is just fixing typo and broken link in README. Please review!

    opened by jollyjoester 1
  • Remove VALID_ARCHS

    Remove VALID_ARCHS

    Checklist

    • [x] All tests are passed.
    • [ ] Added tests or Playbook scenario.
    • [ ] Documented the code using Xcode markup.
    • [x] Searched existing pull requests for ensure not duplicated.

    Description

    Remove VALID_ARCHS since it's not used in Xcode 12 by default. This will support Apple Silicon builds.

    opened by taoshotaro 1
  • fix import so sample app builds

    fix import so sample app builds

    Checklist

    • [ x ] All tests are passed.
    • [ n/a ] Added tests or Playbook scenario.
    • [ n/a ] Documented the code using Xcode markup.
    • [ x ] Searched existing pull requests for ensure not duplicated.

    Description

    SampleApp doesn't build. This import fixes it.

    Related Issue

    Motivation and Context

    Screenshots

    opened by spnkr 1
  • Version 0.1.1

    Version 0.1.1

    Checklist

    • [x] All tests are passed.
    • [ ] Added tests or Playbook scenario.
    • [x] Documented the code using Xcode markup.
    • [x] Searched existing pull requests for ensure not duplicated.

    Description

    • Update version to 0.1.1
    • Use swift-doc only instead of gitbook
    • Update tools and formats
    • Some fix for iOS 13.4 regression
    • Fix typography

    Related Issue

    close #16 close #17 close #18 close #19 close #22

    opened by ra1028 1
  • Fix Documentation

    Fix Documentation

    Checklist

    • [x] All tests are passed.
    • [x] Added tests or Playbook scenario.
    • [x] Documented the code using Xcode markup.
    • [x] Searched existing pull requests for ensure not duplicated.

    Description

    I noticed some grammatical mistakes in the documentation while reading so I fixed them.

    opened by yuzushioh 1
  • Remove .edgesIgnoringSafeArea line from sample app code

    Remove .edgesIgnoringSafeArea line from sample app code

    Checklist

    • [x] All tests are passed.
    • [ ] Added tests or Playbook scenario.
    • [ ] Documented the code using Xcode markup.
    • [x] Searched existing pull requests for ensure not duplicated.

    Description

    Remove .edgesIgnoringSafeArea line from sample app code

    Related Issue

    Closes #20

    Motivation and Context

    Screenshot

    Fixed screen shot: Screen Shot 2020-04-06 at 21 26 20

    opened by kagemiku 1
  • Typing mistake

    Typing mistake

    Checklist

    • [x] This is not a Apple's bug.
    • [x] Reviewed the README and documents.
    • [x] Searched existing issues for ensure not duplicated.

    Description (Include Screenshots)

    In the playbook README and API Document, in the second paragraph where the sentence starts with 'Components built using...'; instead of writing 'can generates' write 'generate'.

    Steps to Reproduce

    1. Go to https://github.com/playbook-ui/playbook-ios or https://playbook-ui.github.io/playbook-ios/.

    2. Go to the README section at https://github.com/playbook-ui/playbook-ios and Read the Introduction section at https://playbook-ui.github.io/playbook-ios/.

    3. Read the README and/or Introduction section.

    4. Read the first line of the second paragraph.

    Reproducible Demo Project

    Environments

    • Library version:

    • Swift version:

    • iOS version:

    • Xcode version:

    • Devices/Simulators:

    • Package manager version:

    opened by vitish 1
  • Set up documentation

    Set up documentation

    Checklist

    • [x ] Reviewed the README and documents.
    • [x ] Searched existing issues for ensure not duplicated.

    Description

    It is very hard to figure out how to set Playbook up for a UIKit app

    Motivation and Context

    I'd like to set Playbook for my my UIKit app, but there is no documentation on how to set things up. The sample app is SwiftUi only, so it makes it hard to figure it out

    Proposed Solution

    Add a page in the documentation explaining how to setup the playbook target to for a UIKit app

    opened by otusweb 0
  • Add `TestTool` for compare snapshot diffs without dependency

    Add `TestTool` for compare snapshot diffs without dependency

    Checklist

    • [x] Reviewed the README and documents.
    • [x] Searched existing issues for ensure not duplicated.

    Description

    Add a new TestTool compare snapshot diffs without dependency like pointfreeco/swift-snapshot-testing and uber/ios-snapshot-test-case.

    Motivation and Context

    Visual regression tests using third-party tools such as reg-suit are powerful, but a framework that can be used more simply on unit tests is needed.

    Proposed Solution

    Playbook.default.run(
        SnapshotCompare(devices: [.iPhone11Pro(.portrait)])
    )
    
    opened by ra1028 1
Releases(0.3.2)
a iOS network debug library, monitor HTTP requests

NetworkEye README 中文 NetworkEye,a iOS network debug library,monitor HTTP requests. It can be detected HTTP request include web pages, NSURLConnection,

coderyi 1.4k Dec 31, 2022
TouchInspector - a lightweight package that helps you visualize and debug touches on iOS and iPadOS

TouchInspector is a lightweight package that helps you visualize and debug touches on iOS and iPadOS.

Janum Trivedi 116 Jan 3, 2023
In-app console and debug tools for iOS developers

LocalConsole Welcome to LocalConsole! This Swift Package makes on-device debugging easy with a convenient PiP-style console that can display items in

Duraid Abdul 650 Jan 1, 2023
A collection of tools for debugging, diffing, and testing your application's data structures.

Custom Dump A collection of tools for debugging, diffing, and testing your application's data structures. Motivation customDump diff XCTAssertNoDiffer

Point-Free 631 Jan 3, 2023
Remote network and data debugging for your native iOS app using Chrome Developer Tools

PonyDebugger PonyDebugger is a remote debugging toolset. It is a client library and gateway server combination that uses Chrome Developer Tools on you

Square 5.9k Dec 24, 2022
An in-app debugging and exploration tool for iOS

FLEX FLEX (Flipboard Explorer) is a set of in-app debugging and exploration tools for iOS development. When presented, FLEX shows a toolbar that lives

FLEXTool 13.3k Dec 31, 2022
Automaticly display Log,Crash,Network,ANR,Leak,CPU,RAM,FPS,NetFlow,Folder and etc with one line of code based on Swift. Just like God opened his eyes

GodEye Automaticly display Log,Crash,Network,ANR,Leak,CPU,RAM,FPS,NetFlow,Folder and etc with one line of code based on Swift. Just like God opened hi

陈奕龙(子循) 3.7k Dec 23, 2022
Dotzu In-App iOS Debugging Tool With Enhanced Logging, Networking Info, Crash reporting And More.

Dotzu In-App iOS Debugging Tool With Enhanced Logging, Networking Info, Crash reporting And More. The debugger tool for iOS developer. Display logs, n

Remi ROBERT 1.8k Jan 3, 2023
In-app design review tool to inspect measurements, attributes, and animations.

Hyperion Hyperion - In App Design Review Tool What is it? Hyperion is a hidden plugin drawer that can easily be integrated into any app. The drawer si

WillowTree, LLC 2k Dec 27, 2022
Tool to debug layouts directly on iOS devices: inspect layers in 3D and debug each visible view attributes

Introduction Features Inspect layouts directly on iOS devices Inspection could be triggered only if app is running under DEBUG build configuration, so

Ihor Savynskyi 510 Dec 24, 2022
A little and powerful iOS framework for intercepting HTTP/HTTPS Traffic.

A little and powerful iOS framework for intercepting HTTP/HTTPS Traffic from your app. No more messing around with proxy, certificate config. Features

Proxyman 874 Jan 6, 2023
Xray is viewDebugging tool for iOS, tvOS, watchOS and macOS

XRay XRay is view debugging tool for iOS. Currently, XRay can show all of the view hierarchies in UIKit. For SwiftUI, I'm working on it. XRay helps yo

Shawn Baek 10 Jun 10, 2022
📘A library for isolated developing UI components and automatically taking snapshots of them.

A library for isolated developing UI components and automatically taking snapshots of them. Playbook Playbook is a library that provides a sandbox for

Playbook 970 Jan 3, 2023
Jogendra 113 Nov 28, 2022
Mathias Köhnke 1.1k Dec 16, 2022
WebKit aims to provide platform agnostic isolated browser environments without the need for sketchy C bindings or a bloated V8 runtime.

WebKit WebKit aims to provide platform agnostic isolated browser environments without the need for sketchy C bindings or a bloated V8 runtime. Running

Linden 1 Nov 26, 2021
Matrix-rust-components-swift - Swift package providing components from the matrix-rust-sdk

Swift package for Matrix Rust components This repository is a Swift Package for

matrix.org 10 Nov 4, 2022
Basic components for setting up UIKit components programmatically.

UIKit Components Package This repository contains basic components for setting up UIKit components programmatically. It is made by SPACE SQUAD! We mak

SPACE SQUAD 2 Sep 22, 2022
SwiftGen is a tool to automatically generate Swift code for resources of your projects (like images, localised strings, etc), to make them type-safe to use.

SwiftGen is a tool to automatically generate Swift code for resources of your projects (like images, localised strings, etc), to make them type-safe to use.

null 8.3k Jan 5, 2023
Add validations to your text fields, Group them together and navigate through them via keyboard's return button and accessory view.

TFManager Let's say you have multiple UITextFields to get data from users. You need to handle each field keyboard's return key and add an accessory vi

Hosein Abbaspour 16 Sep 29, 2022