PlaygroundTester

PlaygroundTester is a package that enables you to add tests to your iPad Swift Playgrounds project.

Installation

Just add PlaygroundTester package to the project as you normally would.

Usage

Patching `Package.swift`

Since Swift Playgrounds don't support multiple targets at this time, we need to keep test source files alongside regular application code. In order to avoid including testing code in a release build of the app, PlaygroundTester has it's entire code between conditional compliation flags :

#if TESTING_ENABLED
// code
#endif

Since the base class for tests is also treated like that you also need to wrap your tests in this manner. Unfortunatelly, the DEBUG flag available by default in Xcode is not present in Swift Playgrounds, and there is no way to add them via UI.

For now you'll need to follow these steps to add a compilation flag to your project :

Send the app project to a Mac (for example via AirDrop)
Open the package contents (right click -> Show Package Contents)
Open Package.swift file
This file should contain a single .executableTarget definition.
Add this argument to the target : swiftSettings: [.define("TESTING_ENABLED", .when(configuration: .debug))]
Save the file and share the app back to your iPad.

In the end the target definition should look similar to this :

targets: [
        .executableTarget(
            name: "AppModule",
            dependencies: [
              // if any
            ],
            path: ".",
            swiftSettings: [.define("TESTING_ENABLED", .when(configuration: .debug))]
        )
    ]

You can of course choose any name for the flag.

NOTE : I hope to automate this process in Patching Package.swift

Adding tests

For PlaygroundTester to find and properly execute tests your test class needs to :

Inherit from TestCase
Be marked as having @objcMembers
1. Alternatively you can mark each method you want to be discoverable as @objc

At this momment inheriting from another test class is not supported (so you cannot create a class BaseTests: TestCase that you will then inherit other test classes from).

setUp / tearDown

You can override four methods to help with setting up and cleaning up after your tests.

  // Called once for the entire test class, before any tests are run.
  open class func setUp() {  }

  // Called before each test method.
  // If this method throws, the test method won't be executed, but `tearDown` will be.
  open func setUp() throws { }

  // Called after each test method.
  open func tearDown() throws { }

  // Called once for the entire test class, after all tests are run.
  open class func tearDown() { }
}

Adding test methods

For PlaygroundTester to discover your test methods and run them automatically they have to :

Be non-private (so public or internal)
Begin with test

Any private methods or ones not begininning with test will not be automatically executed, so you can use this opportunity to define helper methods.

Sample method definition :

func testSample() { }

// Methods that won't be run automaticaly
private func testPrivateSample() { }

func helperMethod() { }

Throwing test methods

Throwing test methods are supported by PlaygroundTester - just define your method following the rules above and add throws to its definition. PlaygroundTester will catch the thrown error and report it.

Sample throwing test method definition :

func testSampleThrowing() throws { }

Asserting

Currently there is a basic set of assertion methods available that mimick the asserting style of XCTest:

// Assert of a passed boolean value is `true`/`false`
public func Assert(_ value: Bool, message: String = "")
public func AssertFalse(_ value: Bool, message: String = "")

// Assert if two passed values are equal / not equal.
public func AssertEqual<T: Equatable>(_ value: T, other: T, message: String = "") 
public func AssertNotEqual<T: Equatable>(_ value: T, other: T, message: String = "")

// assert if passed optional value is `nil` / not `nil`.
public func AssertNil<T>(_ value: T?, message: String = "")
public func AssertNotNil<T>(_ value: T?, message: String = "")

There are a few methods missing from achieving parity with XCTAssert family of methods which will be added later.

Unwrapping

PlaygroundTester provides a similar method to XCTUnwrap:

// Return an unwrapped value, or throw an error if `nil` was passed.
public func AssertUnwrap<T>(_ value: T?, message: String = "") throws -> T

You should mark your test method with throws to avoid the need to handle this thrown error yourself.

Sample method with AssertUnwrap :

func testSampleAssertUnwrap() throws {

  let sampleArray = ["first", "second"]
  
  let firstValue = try XCTUnwrap(sampleArray.first, "Array should have a first element").

  // `firstValue` is non-optional here
}

Expectations

PlaygroundTester supports waiting on expectations to test asynchronous code. Expectations can be configured with 3 properties :

expectedFulfilmentCount (default == 1) - how many times should the expectation be fullfilled to be considered as met. Expectations will fail if they are overfulfilled.
inverted (default == false) - if the expectation is inverted it will fail, if it is fullfilled.
1. If you have an inverted expectation with expectedFulfilmentCount > 1 it will be considered as met if it gets fullfilled less than expectedFulfilmentCount times.

You use the AssertExpectations method to wait on created expectations :

// Will wait for `timeout` seconds for `expectations` to be fulfilled before continuing test execution.
public func AssertExpectations(_ expectations: [Expectation], timeout: TimeInterval)

Sample test with expectation :

func testSampleExpectation() {
  let expectation = Expectation(name: "Wait for main thread")
  
  DispatchQueue.main.async { 
    expectation.fulfill()
  }
  
  AssertExpectations([expectation], timeout: 2)
}

At this moment unwaited expectations don't trigger an assertion failure.

Runing tests

In order to execute your tests you need to do one final thing : exchange your app view for PlaygroundTesterView. In your App object just do this :

struct Myapp: App {
    var body: some Scene {
        WindowGroup {
          // YourContentView()
          PlaygroundTester.PlaygroundTesterView()
        }
    }
}

After that when running the app either in fullscreen or in preview mode will instead discover and run your tests.

Inspecting results

After the tests are run, you can navigate them to inspect their results and see which assertions failed.

pg_tester_sample.mp4

Supported features

Automatic test discovery & execution
UI for inspecting test results
Basic assertions
Expectations
Throwing tests methods
setUp/tearDown methods

Roadmap

Things I'd like to explore and add to PlaygroundTester (random order):

Automatic Package.swift patching
Filtering - by test result and by name
- Possibly with persistence, to allow quick feedback for TDD
Single test method / test suite execution
Flat list view
Assertion parity with XCTest
Explore support for async/await
Explore support for Combine
... and possibly more

Please check Issues for more info.

pawelurb/PlaygroundTester