Macro Testing

Magical testing tools for Swift macros.

Learn more

This library was designed to support libraries and episodes produced for Point-Free, a video series exploring the Swift programming language hosted by Brandon Williams and Stephen Celis.

You can watch all of the episodes here.

Motivation

This library comes with a tool for testing macros that is more powerful and ergonomic than the default tool that comes with SwiftSyntax. To use the tool, simply specify the macros that you want to expand as well as a string of Swift source code that makes use of the macro.

For example, to test the #stringify macro that comes with SPM's macro template all one needs to do is write the following:

import MacroTesting
import XCTest

class StringifyTests: XCTestCase {
  func testStringify() {
    assertMacro(["stringify": StringifyMacro.self]) {
      """
      #stringify(a + b)
      """
    }
  }
}

When you run this test the library will automatically expand the macros in the source code string and write the expansion into the test file:

func testStringify() {
  assertMacro(["stringify": StringifyMacro.self]) {
    """
    #stringify(a + b)
    """
  } expansion: {
    """
    (a + b, "a + b")
    """
  }
}

That is all it takes.

If in the future the macro's output changes, such as adding labels to the tuple's arguments, then running the test again will produce a nicely formatted message:

❌ failed - Actual output (+) differed from expected output (−). Difference: …

- (a + b, "a + b")
+ (result: a + b, code: "a + b")

You can even have the library automatically re-record the macro expansion directly into your test file by providing the record argument to assertMacro:

assertMacro(["stringify": StringifyMacro.self], record: true) {
  """
  #stringify(a + b)
  """
} expansion: {
  """
  (a + b, "a + b")
  """
}

Now when you run the test again the freshest expanded macro will be written to the expansion trailing closure.

If you're writing many tests for a macro, you can avoid the repetitive work of specifying the macros in each assertion by using XCTest's invokeTest method to wrap each test with Macro Testing configuration:

class StringifyMacroTests: XCTestCase {
  override func invokeTest() {
    withMacroTesting(
      macros: ["stringify": StringifyMacro.self]
    ) {
      super.invokeTest()
    }
  }

  func testStringify() {
    assertMacro {  // 👈 No need to specify the macros being tested
      """
      #stringify(a + b)
      """
    } expansion: {
      """
      (a + b, "a + b")
      """
    }
  }

  // ...
}

You can pass the isRecording parameter to withMacroTesting to re-record every assertion in the test case (or suite, if you're using your own custom base test case class):

override func invokeTest() {
  withMacroTesting(
    isRecording: true
  ) {
    super.invokeTest()
  }
}

Macro Testing can also test diagnostics, such as warnings, errors, notes, and fix-its. When a macro expansion emits a diagnostic, it will render inline in the test. For example, a macro that adds completion handler functions to async functions may emit an error and fix-it when it is applied to a non-async function. The resulting macro test will fully capture this information, including where the diagnostics are emitted, how the fix-its are applied, and how the final macro expands:

func testNonAsyncFunctionDiagnostic() {
  assertMacro {
    """
    @AddCompletionHandler
    func f(a: Int, for b: String) -> String {
      return b
    }
    """
  } diagnostics: {
    """
    @AddCompletionHandler
    func f(a: Int, for b: String) -> String {
    ┬───
    ╰─ 🛑 can only add a completion-handler variant to an 'async' function
       ✏️ add 'async'
      return b
    }
    """
  } fixes: {
    """
    @AddCompletionHandler
    func f(a: Int, for b: String) async -> String {
      return b
    }
    """
  } expansion: {
    """
    func f(a: Int, for b: String) async -> String {
      return b
    }

    func f(a: Int, for b: String, completionHandler: @escaping (String) -> Void) {
      Task {
        completionHandler(await f(a: a, for: b, value))
      }
    }
    """
  }
}

Documentation

The latest documentation for this library is available here.

License

This library is released under the MIT license. See LICENSE for details.