Functions

The following functions are available globally.

beforeSuite

  • Defines a closure to be run prior to any examples in the test suite. You may define an unlimited number of these closures, but there is no guarantee as to the order in which they’re run.

    If the test suite crashes before the first example is run, this closure will not be executed.

    Declaration

    Swift

    public func beforeSuite(_ closure: @escaping BeforeSuiteAsyncClosure)

    Parameters

    closure

    The closure to be run prior to any examples in the test suite.

afterSuite

  • Defines a closure to be run after all of the examples in the test suite. You may define an unlimited number of these closures, but there is no guarantee as to the order in which they’re run.

    If the test suite crashes before all examples are run, this closure will not be executed.

    Declaration

    Swift

    public func afterSuite(_ closure: @escaping AfterSuiteAsyncClosure)

    Parameters

    closure

    The closure to be run after all of the examples in the test suite.

sharedExamples

  • Defines a group of shared examples. These examples can be re-used in several locations by using the itBehavesLike function.

    Declaration

    Swift

    public func sharedExamples(_ name: String, closure: @escaping () -> Void)

    Parameters

    name

    The name of the shared example group. This must be unique across all shared example groups defined in a test suite.

    closure

    A closure containing the examples. This behaves just like an example group defined using describe or context–the closure may contain any number of beforeEach and afterEach closures, as well as any number of examples (defined using it).

  • Defines a group of shared examples. These examples can be re-used in several locations by using the itBehavesLike function.

    Declaration

    Swift

    public func sharedExamples(_ name: String, closure: @escaping SharedExampleClosure)

    Parameters

    name

    The name of the shared example group. This must be unique across all shared example groups defined in a test suite.

    closure

    A closure containing the examples. This behaves just like an example group defined using describe or context–the closure may contain any number of beforeEach and afterEach closures, as well as any number of examples (defined using it).

            The closure takes a SharedExampleContext as an argument. This context is a function
            that can be executed to retrieve parameters passed in via an `itBehavesLike` function.
    

Example groups

  • Defines an example group. Example groups are logical groupings of examples. Example groups can share setup and teardown code.

    Declaration

    Swift

    public func describe(_ description: String, closure: () -> Void)

    Parameters

    description

    An arbitrary string describing the example group.

    closure

    A closure that can contain other examples.

  • Defines an example group. Equivalent to describe.

    Declaration

    Swift

    public func context(_ description: String, closure: () -> Void)

beforeEach

  • Defines a closure to be run prior to each example in the current example group. This closure is not run for pending or otherwise disabled examples. An example group may contain an unlimited number of beforeEach. They’ll be run in the order they’re defined, but you shouldn’t rely on that behavior.

    Declaration

    Swift

    public func beforeEach(_ closure: @escaping BeforeExampleAsyncClosure)

    Parameters

    closure

    The closure to be run prior to each example.

  • Identical to Quick.DSL.beforeEach, except the closure is provided with metadata on the example that the closure is being run prior to.

    Declaration

    Swift

    public func beforeEach(_ closure: @escaping BeforeExampleWithMetadataAsyncClosure)

AfterEach

  • Defines a closure to be run after each example in the current example group. This closure is not run for pending or otherwise disabled examples. An example group may contain an unlimited number of afterEach. They’ll be run in the order they’re defined, but you shouldn’t rely on that behavior.

    Declaration

    Swift

    public func afterEach(_ closure: @escaping AfterExampleAsyncClosure)

    Parameters

    closure

    The closure to be run after each example.

  • Identical to Quick.DSL.afterEach, except the closure is provided with metadata on the example that the closure is being run after.

    Declaration

    Swift

    public func afterEach(_ closure: @escaping AfterExampleWithMetadataAsyncClosure)

aroundEach

  • Defines a closure to that wraps each example in the current example group. This closure is not run for pending or otherwise disabled examples.

    The closure you pass to aroundEach receives a callback as its argument, which it MUST call exactly one for the example to run properly:

    aroundEach { runExample in
        doSomeSetup()
        await runExample()
        doSomeCleanup()
    }
    

    This callback is particularly useful for test decartions that can’t split into a separate beforeEach and afterEach. For example, running each example in its own autorelease pool (provided by Task) requires aroundEach:

    aroundEach { runExample in
        await Task {
            await runExample()
        }.value
        checkObjectsNoLongerRetained()
    }
    

    You can also use aroundEach to guarantee proper nesting of setup and cleanup operations in situations where their relative order matters.

    An example group may contain an unlimited number of aroundEach callbacks. They will nest inside each other, with the first declared in the group nested at the outermost level.

    Declaration

    Swift

    public func aroundEach(_ closure: @escaping AroundExampleAsyncClosure)

    Parameters

    closure

    The closure that wraps around each example.

  • Identical to Quick.DSL.aroundEach, except the closure receives metadata about the example that the closure wraps.

    Declaration

    Swift

    public func aroundEach(_ closure: @escaping AroundExampleWithMetadataAsyncClosure)

Examples

  • Defines a closure to be run prior to each example but after any beforeEach blocks. This closure is not run for pending or otherwise disabled examples. An example group may contain an unlimited number of justBeforeEach. They’ll be run in the order they’re defined, but you shouldn’t rely on that behavior.

    Declaration

    Swift

    public func justBeforeEach(_ closure: @escaping BeforeExampleClosure)

    Parameters

    closure

    The closure to be run prior to each example and after any beforeEach blocks

  • Defines an example. Examples use assertions to demonstrate how code should behave. These are like “tests” in XCTest.

    Declaration

    Swift

    public func it(_ description: String, file: FileString = #file, line: UInt = #line, closure: @escaping () async throws -> Void)

    Parameters

    description

    An arbitrary string describing what the example is meant to specify.

    closure

    A closure that can contain assertions.

    file

    The absolute path to the file containing the example. A sensible default is provided.

    line

    The line containing the example. A sensible default is provided.

Shared Examples

  • Inserts the examples defined using a sharedExamples function into the current example group. The shared examples are executed at this location, as if they were written out manually.

    Declaration

    Swift

    public func itBehavesLike(_ name: String, file: FileString = #file, line: UInt = #line)

    Parameters

    name

    The name of the shared examples group to be executed. This must be identical to the name of a shared examples group defined using sharedExamples. If there are no shared examples that match the name given, an exception is thrown and the test suite will crash.

    file

    The absolute path to the file containing the current example group. A sensible default is provided.

    line

    The line containing the current example group. A sensible default is provided.

  • Inserts the examples defined using a sharedExamples function into the current example group. The shared examples are executed at this location, as if they were written out manually. This function also passes those shared examples a context that can be evaluated to give the shared examples extra information on the subject of the example.

    Declaration

    Swift

    public func itBehavesLike(_ name: String, file: FileString = #file, line: UInt = #line, sharedExampleContext: @escaping SharedExampleContext)

    Parameters

    name

    The name of the shared examples group to be executed. This must be identical to the name of a shared examples group defined using sharedExamples. If there are no shared examples that match the name given, an exception is thrown and the test suite will crash.

    sharedExampleContext

    A closure that, when evaluated, returns key-value pairs that provide the shared examples with extra information on the subject of the example.

    file

    The absolute path to the file containing the current example group. A sensible default is provided.

    line

    The line containing the current example group. A sensible default is provided.

  • Inserts the examples defined using a Behavior into the current example group. The shared examples are executed at this location, as if they were written out manually. This function also passes a strongly-typed context that can be evaluated to give the shared examples extra information on the subject of the example.

    Declaration

    Swift

    public func itBehavesLike<C>(_ behavior: Behavior<C>.Type, file: FileString = #file, line: UInt = #line, context: @escaping () -> C)

    Parameters

    behavior

    The type of Behavior class defining the example group to be executed.

    context

    A closure that, when evaluated, returns an instance of Behavior‘s context type to provide its example group with extra information on the subject of the example.

    file

    The absolute path to the file containing the current example group. A sensible default is provided.

    line

    The line containing the current example group. A sensible default is provided.

Pending

  • Defines an example or example group that should not be executed. Use pending to temporarily disable examples or groups that should not be run yet.

    Declaration

    Swift

    public func pending(_ description: String, closure: () -> Void)

    Parameters

    description

    An arbitrary string describing the example or example group.

    closure

    A closure that will not be evaluated.

  • Defines an example or example group that should not be executed. Use pending to temporarily disable examples or groups that should not be run yet.

    Declaration

    Swift

    public func pending(_ description: String, closure: () async throws -> Void)

    Parameters

    description

    An arbitrary string describing the example or example group.

    closure

    A closure that will not be evaluated.

Defocused

  • Use this to quickly mark a describe closure as pending. This disables all examples within the closure.

    Declaration

    Swift

    public func xdescribe(_ description: String, closure: () -> Void)
  • Use this to quickly mark a context closure as pending. This disables all examples within the closure.

    Declaration

    Swift

    public func xcontext(_ description: String, closure: () -> Void)
  • Use this to quickly mark an it closure as pending. This disables the example and ensures the code within the closure is never run.

    Declaration

    Swift

    public func xit(_ description: String, file: FileString = #file, line: UInt = #line, closure: @escaping () async throws -> Void)
  • Use this to quickly mark an it closure as pending. This disables the example and ensures the code within the closure is never run.

    Note: This is a synchronous version.

    Declaration

    Swift

    public func xit(_ description: String, file: FileString = #file, line: UInt = #line, closure: @escaping () throws -> Void)
  • Use this to quickly mark an itBehavesLike closure as pending. This disables the example group defined by this behavior and ensures the code within is never run.

    Declaration

    Swift

    public func xitBehavesLike<C>(_ behavior: Behavior<C>.Type, file: FileString = #file, line: UInt = #line, context: @escaping () -> C)

Focused

  • Use this to quickly focus a describe closure, focusing the examples in the closure. If any examples in the test suite are focused, only those examples are executed. This trumps any explicitly focused or unfocused examples within the closure–they are all treated as focused.

    Declaration

    Swift

    public func fdescribe(_ description: String, closure: () -> Void)
  • Use this to quickly focus a context closure. Equivalent to fdescribe.

    Declaration

    Swift

    public func fcontext(_ description: String, closure: () -> Void)
  • Use this to quickly focus an it closure, focusing the example. If any examples in the test suite are focused, only those examples are executed.

    Declaration

    Swift

    public func fit(_ description: String, file: FileString = #file, line: UInt = #line, closure: @escaping () async throws -> Void)
  • Use this to quickly focus an it closure, focusing the example. If any examples in the test suite are focused, only those examples are executed.

    Note: This is a synchronous version.

    Declaration

    Swift

    public func fit(_ description: String, file: FileString = #file, line: UInt = #line, closure: @escaping () throws -> Void)
  • Use this to quickly focus an itBehavesLike closure.

    Declaration

    Swift

    public func fitBehavesLike(_ name: String, file: FileString = #file, line: UInt = #line)
  • Use this to quickly focus an itBehavesLike closure.

    Declaration

    Swift

    public func fitBehavesLike(_ name: String, file: FileString = #file, line: UInt = #line, sharedExampleContext: @escaping SharedExampleContext)
  • Use this to quickly focus on itBehavesLike closure.

    Declaration

    Swift

    public func fitBehavesLike<C>(_ behavior: Behavior<C>.Type, file: FileString = #file, line: UInt = #line, context: @escaping () -> C)