Power Assertions for Swift

Power assertions (a.k.a. diagrammed assertions) augment your assertion failures with information about values produced during the evaluation of a condition, and presents them in an easily digestible form. Power assertions are a popular feature of Spock (and later the whole Groovy language independently of Spock), ScalaTest, and Expecty.

Power assertions provide descriptive assertion messages for your tests, like this.

XCTAssert(max(a, b) == c)
          |   |  |  |  |
          7   4  7  |  12
                    false

XCTAssert(xs.contains(4))
          |  |        |
          |  false    4
          [1, 2, 3]

XCTAssert("hello".hasPrefix("h") && "goodbye".hasSuffix("y"))
          |       |         |    |  |         |         |
          "hello" true      "h"  |  "goodbye" false     "y"
                                 false

Online Playground

Live demo for SwiftPowerAssert

https://swift-power-assert.kishikawakatsumi.com/

Installation

$ git clone https://github.com/kishikawakatsumi/SwiftPowerAssert
$ cd SwiftPowerAssert
$ swift build -c release

Copy the file (.build/release/swift-power-assert) to your binary location.

Getting Started

For XCTest

Replace xcodebuild test... command with swift-power-assert xctest -Xxcodebuild test ...

$ /path/to/swift-power-assert xctest -Xxcodebuild test -scheme Atlas-Package

For swift test

Replace swift test... command with swift-power-assert test -Xswift test ...

$ /path/to/swift-power-assert test -Xswift test

Note: SwiftPowerAssert injects instrument code into the family of XCTAssert() methods during tests. SwiftPowerAssert back up the source files before executing tests and restore automatically when the tests finished. However, the original files may not be restored due to an unexpected crash or something wrong. Please use it for the project under Git.

Run Sample Project

You can run the sample project with the following command:

$ swift build -c release
$ (cd Fixtures/Atlas && ../../.build/release/swift-power-assert test -Xswift test)

Usage

USAGE: swift-power-assert [options] subcommand [options]

OPTIONS:
  --verbose   Show more debugging information
  --help      Display available options

SUBCOMMANDS:
  test        Run swift test with power assertion
  xctest      Run XCTest with power assertion.

You can pass any xcodebuild or swift options after -Xxcodebuild or -Xswift.

$ /path/to/swift-power-assert xctest -Xxcodebuild test -project Atlas.xcodeproj \
  -scheme Atlas-Package -sdk iphonesimulator \
  -destination "name=iPhone X,OS=11.2"

$ /path/to/swift-power-assert test -Xswift test -c release -Xswiftc -enable-testing

Nothing happens? If the test succeeds, nothing is output. If you always want to see rich ASCII art, enable the --verbose option. always output a diagram regardless of the success or failure of assertions.

$ /path/to/swift-power-assert --verbose xctest -Xxcodebuild test -project Atlas.xcodeproj -scheme Atlas-Package

$ /path/to/swift-power-assert --verbose test -Xswift test

Examples

let a = 10
let b = 9
XCTAssert(a * b == 91)

// Output:
// XCTAssert(a * b == 91)
//           | | | |  |
//           | | 9 |  91
//           | 90  false
//           10

let xs = [1, 2, 3]
XCTAssert(xs.contains(4))

// Output:
// XCTAssert(xs.contains(4))
//           |  |        |
//           |  false    4
//           [1, 2, 3]

XCTAssert("hello".hasPrefix("h") && "goodbye".hasSuffix("y"))

// Output:
// XCTAssert("hello".hasPrefix("h") && "goodbye".hasSuffix("y"))
//           |       |         |    |  |         |         |
//           "hello" true      "h"  |  "goodbye" false     "y"
//                                  false

let d = 4
let e = 7
let f = 12

XCTAssert(max(d, e) == f)
XCTAssert(d + e > f)

// Output:
// XCTAssert(max(d, e) == f)
//           |   |  |  |  |
//           7   4  7  |  12
//                     false
// XCTAssert(d + e > f)
//           | | | | |
//           4 | 7 | 12
//             11  false

struct Person {
  let name: String
  let age: Int

  var isTeenager: Bool {
    return age <= 12 && age >= 20
  }
}

let john = Person(name: "John", age: 42)
let mike = Person(name: "Mike", age: 13)

XCTAssert(john.isTeenager)
XCTAssert(mike.isTeenager && john.age < mike.age)

// Output:
// XCTAssert(john.isTeenager)
//           |    |
//           |    false
//           Person(name: "John", age: 42)
// XCTAssert(mike.isTeenager && john.age < mike.age)
//           |    |          |  |    |   | |    |
//           |    false      |  |    42  | |    13
//           |               |  |        | Person(name: "Mike", age: 13)
//           |               |  |        false
//           |               |  Person(name: "John", age: 42)
//           |               false
//           Person(name: "Mike", age: 13)

Author

Kishikawa Katsumi, [email protected]

License

SwiftPowerAssert is available under the Apache 2.0 license. See the LICENSE file for more info.