Make value capture of optionals more robust. (#277)

When an expression is optional and is passed through `#require()`, and
that requirement fails, we capture the expression's subexpressions and
record them as an expectation-failed event that is eventually propagated
to `stderr`. Yay.

The underlying value-capturing machinery accepts optional values as
input so that they can be lazily evaluated: if a value is `nil` at this
layer, that means that it wasn't evaluated and we present `"<not
evaluated>"` instead of a description of it or `"nil"`.

In the case of `#require()` unwrapping optionals, these values need to
be boxed in a second optional (i.e. `T??` instead of `T?`, or
`Optional<Optional<T>>` instead of `Optional<T>`) so that if the value
is `nil`, it isn't confused with "no value". See the following table:

| Expression | Value of `x as String??` | Presented As |
|-|-|-|
| `try #require(x)` | `.some(.some("Hello World"))` | `"Hello World"` | 
| `try #require(x)` | `.some(.none)` | `nil` |
| `try #require("Goodbye Venus" ?? x)` | `.none` | `"<not evaluated>"` |

(This maybe suggests we should use a different enum than `Optional`
here, but that's a debate for another PR I think…)

This PR fixes a couple of spots where we weren't casting our values,
known to be optionals, to double-optionals, resulting in incorrect
output that incorrectly included `"<not evaluated>"`.

### 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.

Author: grynspan

Sources/Testing/Expectations/ExpectationChecking+Macro.swift

@@ -557,7 +557,7 @@ public func __checkPropertyAccess<T, U>(
   return __checkValue(
     optionalValue,
     expression: expression,
-    expressionWithCapturedRuntimeValues: expression.capturingRuntimeValues(lhs, optionalValue),
+    expressionWithCapturedRuntimeValues: expression.capturingRuntimeValues(lhs, optionalValue as U??),
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation
@@ -731,7 +731,7 @@ public func __checkBinaryOperation<T>(
   return __checkValue(
     optionalValue,
     expression: expression,
-    expressionWithCapturedRuntimeValues: expression.capturingRuntimeValues(lhs, rhs),
+    expressionWithCapturedRuntimeValues: expression.capturingRuntimeValues(lhs as T??, rhs as T??),
     comments: comments(),
     isRequired: isRequired,
     sourceLocation: sourceLocation

Tests/TestingTests/IssueTests.swift

@@ -1161,6 +1161,28 @@ final class IssueTests: XCTestCase {
     await fulfillment(of: [rhsCalled], timeout: 0.0)
   }
 
+  func testRequireOptionalMemberAccessEvaluatesToNil() async {
+    var configuration = Configuration()
+    configuration.eventHandler = { event, _ in
+      guard case let .issueRecorded(issue) = event.kind else {
+        return
+      }
+      XCTAssertFalse(issue.isKnown)
+      guard case let .expectationFailed(expectation) = issue.kind else {
+        XCTFail("Unexpected issue kind \(issue.kind)")
+        return
+      }
+      let expression = expectation.evaluatedExpression
+      XCTAssertTrue(expression.expandedDescription().contains("nil"))
+      XCTAssertFalse(expression.expandedDescription().contains("<not evaluated>"))
+    }
+
+    await Test {
+      let array = [String]()
+      _ = try #require(array.first)
+    }.run(configuration: configuration)
+  }
+
   func testOptionalOperand() async {
     let expectationFailed = expectation(description: "Expectation failed")