Expand parameterized testing documentation to mention try/await support and showcase helper pattern (#1133)

This expands a few places where we document parameterized testing APIs
to mention `try`/`await` support and showcase a common pattern for
sharing arguments between multiple tests.

### Modifications:

- For each `@Test` macro which accepts arguments, mention that `try` and
`await` are supported and that arguments are lazily evaluated.
- In the "Implementing parameterized tests" article, add a new section
titled "Pass the same arguments to multiple test functions" showcasing
the pattern of extracting common arguments to a separate property.
- Add a [`> Tip:`
callout](https://www.swift.org/documentation/docc/other-formatting-options#Add-Notes-and-Other-Asides)
within that new article section mentioning `try`/`await` support.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Fixes rdar://130929060

Author: stmontgomery

Sources/Testing/Test+Macro.swift

@@ -217,8 +217,10 @@ public macro Test<C>(
 ///   - collection: A collection of values to pass to the associated test
 ///     function.
 ///
-/// During testing, the associated test function is called once for each element
-/// in `collection`.
+/// You can prefix the expression you pass to `collection` with `try` or `await`.
+/// The testing library evaluates the expression lazily only if it determines
+/// that the associated test will run. During testing, the testing library calls
+/// the associated test function once for each element in `collection`.
 ///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.
@@ -270,7 +272,10 @@ extension Test {
 ///   - collection1: A collection of values to pass to `testFunction`.
 ///   - collection2: A second collection of values to pass to `testFunction`.
 ///
-/// During testing, the associated test function is called once for each pair of
+/// You can prefix the expressions you pass to `collection1` or `collection2`
+/// with `try` or `await`. The testing library evaluates the expressions lazily
+/// only if it determines that the associated test will run. During testing, the
+/// testing library calls the associated test function once for each pair of
 /// elements in `collection1` and `collection2`.
 ///
 /// @Comment {
@@ -298,7 +303,10 @@ public macro Test<C1, C2>(
 ///   - collection1: A collection of values to pass to `testFunction`.
 ///   - collection2: A second collection of values to pass to `testFunction`.
 ///
-/// During testing, the associated test function is called once for each pair of
+/// You can prefix the expressions you pass to `collection1` or `collection2`
+/// with `try` or `await`. The testing library evaluates the expressions lazily
+/// only if it determines that the associated test will run. During testing, the
+/// testing library calls the associated test function once for each pair of
 /// elements in `collection1` and `collection2`.
 ///
 /// @Comment {
@@ -324,8 +332,11 @@ public macro Test<C1, C2>(
 ///   - zippedCollections: Two zipped collections of values to pass to
 ///     `testFunction`.
 ///
-/// During testing, the associated test function is called once for each element
-/// in `zippedCollections`.
+/// You can prefix the expression you pass to `zippedCollections` with `try` or
+/// `await`. The testing library evaluates the expression lazily only if it
+/// determines that the associated test will run. During testing, the testing
+/// library calls the associated test function once for each element in
+/// `zippedCollections`.
 ///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.
@@ -352,8 +363,11 @@ public macro Test<C1, C2>(
 ///   - zippedCollections: Two zipped collections of values to pass to
 ///     `testFunction`.
 ///
-/// During testing, the associated test function is called once for each element
-/// in `zippedCollections`.
+/// You can prefix the expression you pass to `zippedCollections` with `try` or
+/// `await`. The testing library evaluates the expression lazily only if it
+/// determines that the associated test will run. During testing, the testing
+/// library calls the associated test function once for each element in
+/// `zippedCollections`.
 ///
 /// @Comment {
 ///   - Bug: The testing library should support variadic generics.

Sources/Testing/Testing.docc/ParameterizedTesting.md

@@ -101,6 +101,37 @@ func makeLargeOrder(count: Int) async throws {
 - Note: Very large ranges such as `0 ..< .max` may take an excessive amount of
   time to test, or may never complete due to resource constraints.
 
+### Pass the same arguments to multiple test functions
+
+If you want to pass the same collection of arguments to two or more
+parameterized test functions, you can extract the arguments to a separate
+function or property and pass it to each `@Test` attribute. For example:
+
+```swift
+extension Food {
+  static var bestSelling: [Food] {
+    get async throws { /* ... */ }
+  }
+}
+
+@Test(arguments: try await Food.bestSelling)
+func `Order entree`(food: Food) {
+  let foodTruck = FoodTruck()
+  #expect(foodTruck.order(food))
+}
+
+@Test(arguments: try await Food.bestSelling)
+func `Package leftovers`(food: Food) throws {
+  let foodTruck = FoodTruck()
+  let container = try #require(foodTruck.container(fitting: food))
+  try container.add(food)
+}
+```
+
+> Tip: You can prefix expressions passed to `arguments:` with `try` or `await`.
+> The testing library evaluates them lazily only if it determines that the
+> associated test will run.
+
 ### Test with more than one collection
 
 It's possible to test more than one collection. Consider the following test