Swift Testing: Test Scoping Traits
Swift 6.1 enables custom Swift Testing traits to perform logic before or after tests run in order to share set-up or tear-down logic. If you write a custom trait type which conforms to the new
TestScopingprotocol, you can implement a method to customize the scope in which each test or suite the trait is applied to will execute. For example, you could implement a trait which binds a task local value to a mocked resource:struct MockAPICredentialsTrait: TestTrait, TestScoping { func provideScope(for test: Test, testCase: Test.Case?, performing function: @Sendable () async throws -> Void) async throws { let mockCredentials = APICredentials(apiKey: "fake") try await APICredentials.$current.withValue(mockCredentials) { try await function() } } } extension Trait where Self == MockAPICredentialsTrait { static var mockAPICredentials: Self { Self() } } @Test(.mockAPICredentials) func example() { // Validate API usage, referencing `APICredentials.current`... }
Because task locals cannot be separated into set-up and tear-down portions, they were previously only usable in Swift Testing if you repeated them within each test function. TestScoping gets rid of the indentation that entails and can also be applied at the suite level, so you don’t have to repeat it for each test. It’s great to have this functionality, though I think the implementation via traits feels a bit convoluted compared with XCTest’s invokeTest().
Some test authors have expressed interest in allowing custom traits to access the instance of a suite type for
@Testinstance methods, so the trait could inspect or mutate the instance. Currently, only instance-level members of a suite type (includinginit,deinit, and the test function itself) can accessself, so this would grant traits applied to an instance test method access to the instance as well. This is certainly interesting, but poses several technical challenges that puts it out of scope of this proposal.
It seems like a major limitation that any code factored out in this way can’t access properties or helper functions in the type that contains the test.
Some reviewers of this proposal pointed out that the hypothetical usage example shown earlier involving setting a task local value while a test is executing will likely become a common use of these APIs. To streamline that pattern, it would be very natural to add a built-in trait type which facilitates this. I have prototyped this idea and plan to add it once this new trait functionality lands.
Previously:
Update (2025-04-02): Christian Tietze:
I really like how Swift Testing Traits turns into how Emacs Lisp implements function advising.
You basically decorate a function call with a macro.
Unlike (Emacs) Lisp, you can't fiddle with the context of the called function and pass data along.
