Contents

expect(throws:_:sourceLocation:performing:)

Check that an expression always throws an error of a given type.

Declaration

@discardableResult @freestanding(expression) macro expect<E, R>(throws errorType: E.Type, _ comment: @autoclosure () -> Comment? = nil, sourceLocation: SourceLocation = #_sourceLocation, performing expression: () async throws -> R) -> E? where E : Error

Parameters

  • errorType:

    The type of error that is expected to be thrown. If expression could throw any error, or the specific type of thrown error is unimportant, pass (any Error).self.

  • comment:

    A comment describing the expectation.

  • sourceLocation:

    The source location to which recorded expectations and issues should be attributed.

  • expression:

    The expression to be evaluated.

Mentioned in

Return Value

If the expectation passes, the instance of errorType that was thrown by expression. If the expectation fails, the result is nil.

Overview

Use this overload of #expect() when the expression expression should throw an error of a given type:

#expect(throws: EngineFailureError.self) {
  FoodTruck.shared.engine.batteryLevel = 0
  try FoodTruck.shared.engine.start()
}

If expression does not throw an error, or if it throws an error that is not an instance of errorType, an Issue is recorded for the test that is running in the current task. Any value returned by expression is discarded.

If the thrown error need only equal another instance of Error, use expect(throws:_:sourceLocation:performing:) instead.

Expressions that should never throw

If the expression expression should never throw any error, you can pass Never.self:

#expect(throws: Never.self) {
  FoodTruck.shared.engine.batteryLevel = 100
  try FoodTruck.shared.engine.start()
}

If expression throws an error, an Issue is recorded for the test that is running in the current task. Any value returned by expression is discarded.

Test functions can be annotated with throws and can throw errors which are then recorded as issues when the test runs. If the intent is for a test to fail when an error is thrown by expression, rather than to explicitly check that an error is not thrown by it, do not use this macro. Instead, simply call the code in question and allow it to throw an error naturally.

See Also

Checking that errors are thrown