Swift Power Assert

Power asserts (also known as diagrammed assertions) augment your assertion failures with information about the values produced during evaluation of a condition, and present it in an easily digestible form. Power asserts are a popular feature of Spock (and later the entire Groovy language independent of Spock), ScalaTest and Expecty.

Power asserts provide descriptive assertion messages for your tests, like the following examples:

#assert(numbers[2] == 4)
        │       ││ │  │
        │       │3 │  4
        │       2  false
        [1, 2, 3, 4, 5]

--- [Int] numbers[2]
+++ [Int] 4
–3
+4

[Int] numbers[2]
=> 3
[Int] 4
=> 4

#assert(numbers.contains(6))
        │       │        │
        │       false    6
        [1, 2, 3, 4, 5]

#assert(string1 == string2)
        │       │  │
        │       │  "Hello, Swift!"
        │       false
        "Hello, world!"

--- [String] string1
+++ [String] string2
Hello, {+S+}w[-orld-]{+ift+}!

[String] string1
=> "Hello, world!"
[String] string2
=> "Hello, Swift!"

Online Playground

Experience the library in action with our online playground! :sparkles: Click here to access the interactive demo.

Why Power Assert?

When writing tests, we need to use different assertion functions. With Power Assert you only use the #assert() function. There are many Assertion APIs, no need to remember them. Just create an expression that returns a boolean value and Power Assert will automatically display rich error information.

Getting Started

Swift Power Assert is implemented using macros, an experimental feature of Swift. Therefore, Xcode 15 beta must be installed to use this library.

1. Download and extract Xcode 15 beta. https://developer.apple.com/download/all/
2. (Optional) To use this library from the command line, go to the Xcode menu and select Settings... > Locations > Locations > Command Line Tools and select "Xcode -beta-15.0".

For Xcode Project

To see PowerAssert in action, go to the Examples directory and run xcodebuild test ....

$ cd Examples/XcodeProject/
$ xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 14 Pro,OS=17.0' -parallel-testing-enabled NO

The parameter -parallel-testing-enabled NO is required. Due to recent changes in Xcode, parallel testing is now turned on by default and test messages are no longer output to the console. Therefore, to see assertion messages in the console, disable parallel testing. When parallel testing is enabled, all console logs can be viewed from the result bundle.

For Swift Package Manager

To see PowerAssert in action, go to the Examples directory and run swift test.

$ cd Examples/SwiftPackage/
$ swift test

See the following results?

...
Test Suite 'All tests' started at 2023-04-05 07:17:58.800
Test Suite 'swift-power-assert-examplePackageTests.xctest' started at 2023-04-05 07:17:58.801
Test Suite 'PowerAssertTests' started at 2023-04-05 07:17:58.801
Test Case '-[ExampleTests.PowerAssertTests testExample]' started.
/swift-power-assert/Example/"ExampleTests/ExampleTests.swift":8: error: -[ExampleTests.PowerAssertTests testExample] : failed -
#assert(a * b == 91)
        │ │ │ │  │
        │ │ 9 │  91
        │ 90  false
        10

[Int] a
=> 10
[Int] b
=> 9
[Int] a * b
=> 90
[Int] 91
=> 91
/swift-power-assert/Example/"ExampleTests/ExampleTests.swift":11: error: -[ExampleTests.PowerAssertTests testExample] : failed -
#assert(xs.contains(4))
        │  │        │
        │  false    4
        [1, 2, 3]
...

Modify the code in Example/Tests/ExampleTests.swift to try different patterns you like.

Usage

To use Swift Power Assert in your library or application, first add swift-power-assert to your project.

For the Xcode project, add the swift-power-assert library as a package dependency.

The dependency rule should (for now) specify the main branch.

Select PowerAssert as the Package Product and specify the Test Bundle as the target to add.

For the Swift package, configure Package.swift as follows:

// swift-tools-version:5.8
import PackageDescription

let package = Package(
  name: "MyLibrary",
  dependencies: [
    ...,
    .package(
        url: "https://github.com/kishikawakatsumi/swift-power-assert.git",
        branch: "main"
    ),
  ],
  targets: [
    ...,
    .testTarget(
      name: "MyLibraryTests",
      dependencies: [
        ...,
        .product(name: "PowerAssert", package: "swift-power-assert"),
      ]
    ),
  ]
)

Next, you can use Power Assert in your tests with the #assert() macro.

// MyLibraryTests.swift
import XCTest
import PowerAssert
@testable import MyLibrary

final class MyLibraryTests: XCTestCase {
  func testExample() {
    let a = 7
    let b = 4
    let c = 12

    #assert(max(a, b) == c)
  }
}

Concurrency (async/await) support

Swift Power Assert library allows you to write assertions with async/await expressions directly. Here's a sample code demonstrating its seamless support for async/await:

func testConcurrency() async {
  let ok = "OK"
  #assert(await upload(content: "example") == ok)
}

Frequently Asked Questions

Q: I want to display the result even if the test is successful (i.e. the expression in the #assert() function evaluates to true).

A: By default, the #assert() function does not display the result if the expression evaluates to true, because the test was successful. To always print the result, set the verbose argument to true.

For example:

#assert(x == y, verbose: true)

Q: I want to know how the compiler actually expanded the macro.

A: You can use the -dump-macro-expansions option to dump the macro expansion.

For example:

$ cd Examples/SwiftPackage/
$ swift test -Xswiftc -Xfrontend -Xswiftc -dump-macro-expansions

If you run the above with the -dump-macro-expansions option, you will get the following output.

...
@__swiftmacro_12ExampleTests011PowerAssertB0C04testA0yyF6assertfMf_.swift as ()
------------------------------
PowerAssert.Assertion("#assert(a * b == 91)", message: "", file: #""ExampleTests/ExampleTests.swift""#, line: 8, verbose: false, binaryExpressions: [0: "a", 2: "a * b", 3: "91", 1: "b"]) {
    $0.capture($0.capture($0.capture(a .self, column: 8, id: 0) * $0.capture(b .self, column: 12, id: 1), column: 10, id: 2) == $0.capture(91, column: 17, id: 3), column: 14, id: 4)
}
.render()
------------------------------
...

Supporters & Sponsors

Open source projects thrive on the generosity and support of people like you. If you find this project valuable, please consider extending your support. Contributing to the project not only sustains its growth, but also helps drive innovation and improve its features.

To support this project, you can become a sponsor through GitHub Sponsors. Your contribution will be greatly appreciated and will help keep the project alive and thriving. Thanks for your consideration! :heart:

Author

Kishikawa Katsumi

License

The project is released under the MIT License