From 2d1cbc9234872658bf3cfb0cf37fc4ee7b3d0943 Mon Sep 17 00:00:00 2001 From: Graham Lee Date: Mon, 16 Jun 2025 15:21:44 +0100 Subject: [PATCH 1/3] Prefer using raw identifiers over display name parameters for tests and suites. Fixes #894. --- Sources/Testing/Test+Macro.swift | 52 +++++++++++++++++++ Sources/Testing/Testing.docc/DefiningTests.md | 8 +-- .../Testing/Testing.docc/OrganizingTests.md | 15 ++++-- 3 files changed, 68 insertions(+), 7 deletions(-) diff --git a/Sources/Testing/Test+Macro.swift b/Sources/Testing/Test+Macro.swift index f2fc415d6..537e10583 100644 --- a/Sources/Testing/Test+Macro.swift +++ b/Sources/Testing/Test+Macro.swift @@ -86,6 +86,16 @@ 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: +/// > Use a raw identifier to give a type a readable name 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 +146,13 @@ public macro Test( /// associated function's name. /// - traits: Zero or more traits to apply to this test. /// +/// Use a raw identifier as the test's name as an alternative to setting the +/// `displayName` parameter, for example: +/// +/// ```swift +/// @Test func `Food truck exists`() { ... } +/// ``` +/// /// ## See Also /// /// - @@ -220,6 +237,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`. /// +/// Use a raw identifier as the test's name 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 +300,13 @@ extension Test { /// testing library calls the associated test function once for each pair of /// elements in `collection1` and `collection2`. /// +/// Use a raw identifier as the test's name 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 +338,13 @@ public macro Test( /// testing library calls the associated test function once for each pair of /// elements in `collection1` and `collection2`. /// +/// Use a raw identifier as the test's name 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 +374,13 @@ public macro Test( /// library calls the associated test function once for each element in /// `zippedCollections`. /// +/// Use a raw identifier as the test's name 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 +412,13 @@ public macro Test( /// library calls the associated test function once for each element in /// `zippedCollections`. /// +/// Use a raw identifier as the test's name 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..4bbdc0da7 100644 --- a/Sources/Testing/Testing.docc/OrganizingTests.md +++ b/Sources/Testing/Testing.docc/OrganizingTests.md @@ -38,10 +38,19 @@ 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. +Use a raw identifier to give the test suite a readable name: + +```swift +struct `Food Truck Tests` { + @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") struct FoodTruckTests { From 1db394f16a07cd2a58e26a797abcd0476d72bc99 Mon Sep 17 00:00:00 2001 From: Graham Lee Date: Tue, 17 Jun 2025 12:26:58 +0100 Subject: [PATCH 2/3] Remove the phrase "raw identifiers" from the documentation. --- Sources/Testing/Test+Macro.swift | 17 +++++++++-------- Sources/Testing/Testing.docc/OrganizingTests.md | 7 ++++--- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/Sources/Testing/Test+Macro.swift b/Sources/Testing/Test+Macro.swift index 537e10583..73ecdd702 100644 --- a/Sources/Testing/Test+Macro.swift +++ b/Sources/Testing/Test+Macro.swift @@ -87,8 +87,9 @@ public macro Suite( /// suites even if they do not have the `@Suite` attribute applied to them. /// /// > Tip: -/// > Use a raw identifier to give a type a readable name instead of using -/// > `@Suite` to change its display name: +/// > 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` { @@ -146,7 +147,7 @@ public macro Test( /// associated function's name. /// - traits: Zero or more traits to apply to this test. /// -/// Use a raw identifier as the test's name as an alternative to setting the +/// Surround a test's name with backticks as an alternative to setting the /// `displayName` parameter, for example: /// /// ```swift @@ -237,7 +238,7 @@ 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`. /// -/// Use a raw identifier as the test's name as an alternative to setting the +/// Surround a test's name with backticks as an alternative to setting the /// `displayName` parameter, for example: /// /// ```swift @@ -300,7 +301,7 @@ extension Test { /// testing library calls the associated test function once for each pair of /// elements in `collection1` and `collection2`. /// -/// Use a raw identifier as the test's name as an alternative to setting the +/// Surround a test's name with backticks as an alternative to setting the /// `displayName` parameter, for example: /// /// ```swift @@ -338,7 +339,7 @@ public macro Test( /// testing library calls the associated test function once for each pair of /// elements in `collection1` and `collection2`. /// -/// Use a raw identifier as the test's name as an alternative to setting the +/// Surround a test's name with backticks as an alternative to setting the /// `displayName` parameter, for example: /// /// ```swift @@ -374,7 +375,7 @@ public macro Test( /// library calls the associated test function once for each element in /// `zippedCollections`. /// -/// Use a raw identifier as the test's name as an alternative to setting the +/// Surround a test's name with backticks as an alternative to setting the /// `displayName` parameter, for example: /// /// ```swift @@ -412,7 +413,7 @@ public macro Test( /// library calls the associated test function once for each element in /// `zippedCollections`. /// -/// Use a raw identifier as the test's name as an alternative to setting the +/// Surround a test's name with backticks as an alternative to setting the /// `displayName` parameter, for example: /// /// ```swift diff --git a/Sources/Testing/Testing.docc/OrganizingTests.md b/Sources/Testing/Testing.docc/OrganizingTests.md index 4bbdc0da7..e692459c9 100644 --- a/Sources/Testing/Testing.docc/OrganizingTests.md +++ b/Sources/Testing/Testing.docc/OrganizingTests.md @@ -41,10 +41,11 @@ For more information about test parallelization, see . ### Name a test suite The testing library uses the name of the Swift type as the test suite's name. -Use a raw identifier to give the test suite a readable name: +Surround the type's name with backticks to use spaces and punctuation characters +in the name: ```swift -struct `Food Truck Tests` { +struct `Food truck tests: existence` { @Test func `Food truck exists`() { ... } } ``` @@ -53,7 +54,7 @@ Alternatively, customize a test suite's name by supplying a string literal as an argument to the `@Suite` attribute: ```swift -@Suite("Food truck tests") struct FoodTruckTests { +@Suite("Food truck tests: existence") struct FoodTruckTests { @Test func foodTruckExists() { ... } } ``` From dbd31d9789558d4e22cb72ee2675662f5e0ea200 Mon Sep 17 00:00:00 2001 From: Graham Lee Date: Tue, 17 Jun 2025 12:34:57 +0100 Subject: [PATCH 3/3] Unsplice commas --- Sources/Testing/Test+Macro.swift | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Sources/Testing/Test+Macro.swift b/Sources/Testing/Test+Macro.swift index 73ecdd702..16cf4652b 100644 --- a/Sources/Testing/Test+Macro.swift +++ b/Sources/Testing/Test+Macro.swift @@ -148,7 +148,7 @@ public macro Test( /// - 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: +/// `displayName` parameter; for example: /// /// ```swift /// @Test func `Food truck exists`() { ... } @@ -239,7 +239,7 @@ public macro Test( /// 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: +/// `displayName` parameter; for example: /// /// ```swift /// @Test func `Food truck exists`() { ... } @@ -302,7 +302,7 @@ extension Test { /// elements in `collection1` and `collection2`. /// /// Surround a test's name with backticks as an alternative to setting the -/// `displayName` parameter, for example: +/// `displayName` parameter; for example: /// /// ```swift /// @Test func `Food truck exists`() { ... } @@ -340,7 +340,7 @@ public macro Test( /// elements in `collection1` and `collection2`. /// /// Surround a test's name with backticks as an alternative to setting the -/// `displayName` parameter, for example: +/// `displayName` parameter; for example: /// /// ```swift /// @Test func `Food truck exists`() { ... } @@ -376,7 +376,7 @@ public macro Test( /// `zippedCollections`. /// /// Surround a test's name with backticks as an alternative to setting the -/// `displayName` parameter, for example: +/// `displayName` parameter; for example: /// /// ```swift /// @Test func `Food truck exists`() { ... } @@ -414,7 +414,7 @@ public macro Test( /// `zippedCollections`. /// /// Surround a test's name with backticks as an alternative to setting the -/// `displayName` parameter, for example: +/// `displayName` parameter; for example: /// /// ```swift /// @Test func `Food truck exists`() { ... }