kishikawakatsumi/swift-power-assert

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

Requirements:

• Swift 5.9 or later
• Xcode 15.0 or later

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.

Or set the following UserDefaults. This option allows console output even if parallel testing is enabled.

defaults write com.apple.dt.xcodebuild ParallelTestRunnerStdoutMirroringEnabled -bool YES

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.

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.9
import PackageDescription

let package = Package(
  name: "MyLibrary",
  dependencies: [
    ...,
    .package(
      url: "https://github.com/kishikawakatsumi/swift-power-assert.git",
      from: "0.12.0"
    ),
  ],
  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)
}

For use on CI

For unattended use (e.g. on CI), you can disable the package validation dialog by

• individually passing -skipMacroValidation to xcodebuild or
• globally setting defaults write com.apple.dt.Xcode IDESkipMacroFingerprintValidation -bool YES for that user.

Frequently Asked Questions

Q: Assert failure messages are not displayed.

If you are running your tests from the command line using the xcodebuild test ... command, disable parallel testing. Due to recent changes in Xcode, detailed test logs are not output to the console when parallel testing is enabled. Use the following options to disable parallel testing

-parallel-testing-enabled NO

Alternatively, set the following UserDefaults. This option enables detailed messages to be output to the console even parallel testing enabled.

defaults write com.apple.dt.xcodebuild ParallelTestRunnerStdoutMirroringEnabled -bool YES

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