diff --git a/Sources/Testing/Test+Macro.swift b/Sources/Testing/Test+Macro.swift index f2fc415d6..16cf4652b 100644 --- a/Sources/Testing/Test+Macro.swift +++ b/Sources/Testing/Test+Macro.swift @@ -86,6 +86,17 @@ public macro Suite( /// The use of the `@Suite` attribute is optional; types are recognized as test /// suites even if they do not have the `@Suite` attribute applied to them. /// +/// > Tip: +/// > Give a type a readable name that includes spaces and punctuation by +/// > surrounding the type's name with backticks, instead of using `@Suite` to +/// > change its display name: +/// > +/// > ```swift +/// > struct `Delivery region tests` { +/// > // Add your tests. +/// > } +/// > ``` +/// /// When adding test functions to a type extension, do not use the `@Suite` /// attribute. Only a type's primary declaration may have the `@Suite` attribute /// applied to it. @@ -136,6 +147,13 @@ public macro Test( /// associated function's name. /// - traits: Zero or more traits to apply to this test. /// +/// Surround a test's name with backticks as an alternative to setting the +/// `displayName` parameter; for example: +/// +/// ```swift +/// @Test func `Food truck exists`() { ... } +/// ``` +/// /// ## See Also /// /// - @@ -220,6 +238,13 @@ public macro Test( /// that the associated test will run. During testing, the testing library calls /// the associated test function once for each element in `collection`. /// +/// Surround a test's name with backticks as an alternative to setting the +/// `displayName` parameter; for example: +/// +/// ```swift +/// @Test func `Food truck exists`() { ... } +/// ``` +/// /// @Comment { /// - Bug: The testing library should support variadic generics. /// ([103416861](rdar://103416861)) @@ -276,6 +301,13 @@ extension Test { /// testing library calls the associated test function once for each pair of /// elements in `collection1` and `collection2`. /// +/// Surround a test's name with backticks as an alternative to setting the +/// `displayName` parameter; for example: +/// +/// ```swift +/// @Test func `Food truck exists`() { ... } +/// ``` +/// /// @Comment { /// - Bug: The testing library should support variadic generics. /// ([103416861](rdar://103416861)) @@ -307,6 +339,13 @@ public macro Test( /// testing library calls the associated test function once for each pair of /// elements in `collection1` and `collection2`. /// +/// Surround a test's name with backticks as an alternative to setting the +/// `displayName` parameter; for example: +/// +/// ```swift +/// @Test func `Food truck exists`() { ... } +/// ``` +/// /// @Comment { /// - Bug: The testing library should support variadic generics. /// ([103416861](rdar://103416861)) @@ -336,6 +375,13 @@ public macro Test( /// library calls the associated test function once for each element in /// `zippedCollections`. /// +/// Surround a test's name with backticks as an alternative to setting the +/// `displayName` parameter; for example: +/// +/// ```swift +/// @Test func `Food truck exists`() { ... } +/// ``` +/// /// @Comment { /// - Bug: The testing library should support variadic generics. /// ([103416861](rdar://103416861)) @@ -367,6 +413,13 @@ public macro Test( /// library calls the associated test function once for each element in /// `zippedCollections`. /// +/// Surround a test's name with backticks as an alternative to setting the +/// `displayName` parameter; for example: +/// +/// ```swift +/// @Test func `Food truck exists`() { ... } +/// ``` +/// /// @Comment { /// - Bug: The testing library should support variadic generics. /// ([103416861](rdar://103416861)) diff --git a/Sources/Testing/Testing.docc/DefiningTests.md b/Sources/Testing/Testing.docc/DefiningTests.md index 6b8cc4f00..7bdebb6de 100644 --- a/Sources/Testing/Testing.docc/DefiningTests.md +++ b/Sources/Testing/Testing.docc/DefiningTests.md @@ -37,14 +37,14 @@ To declare a test function, write a Swift function declaration that doesn't take any arguments, then prefix its name with the `@Test` attribute: ```swift -@Test func foodTruckExists() { +@Test func `Food truck exists`() { // Test logic goes here. } ``` This test function can be present at file scope or within a type. A type -containing test functions is automatically a _test suite_ and can be optionally -annotated with the `@Suite` attribute. For more information about suites, see +containing test functions is automatically a _test suite_ and you can optionally +annotate it with the `@Suite` attribute. For more information about suites, see . Note that, while this function is a valid test function, it doesn't actually @@ -71,7 +71,7 @@ to run in the main actor's execution context (that is, from the main thread of the process), it can be annotated `@MainActor`: ```swift -@Test @MainActor func foodTruckExists() async throws { ... } +@Test @MainActor func `Food truck exists`() async throws { ... } ``` ### Limit the availability of a test diff --git a/Sources/Testing/Testing.docc/OrganizingTests.md b/Sources/Testing/Testing.docc/OrganizingTests.md index 3464db4ae..e692459c9 100644 --- a/Sources/Testing/Testing.docc/OrganizingTests.md +++ b/Sources/Testing/Testing.docc/OrganizingTests.md @@ -38,13 +38,23 @@ within the scope of the outer test suite type. By default, tests contained within a suite run in parallel with each other. For more information about test parallelization, see . -### Customize a suite's name +### Name a test suite -To customize a test suite's name, supply a string literal as an argument to the -`@Suite` attribute: +The testing library uses the name of the Swift type as the test suite's name. +Surround the type's name with backticks to use spaces and punctuation characters +in the name: ```swift -@Suite("Food truck tests") struct FoodTruckTests { +struct `Food truck tests: existence` { + @Test func `Food truck exists`() { ... } +} +``` + +Alternatively, customize a test suite's name by supplying a string literal as an +argument to the `@Suite` attribute: + +```swift +@Suite("Food truck tests: existence") struct FoodTruckTests { @Test func foodTruckExists() { ... } } ```