Behavior validation docs

Sources/Testing/Testing.docc/Expectations.md

@@ -10,15 +10,54 @@ See https://swift.org/LICENSE.txt for license information
 See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 -->
 
-Check for expected values and outcomes in tests.
+Check for expected values, outcomes, and events in tests.
 
 ## Overview
 
-The testing library provides `#expect()` and `#require()` macros you use to 
-validate expected outcomes. To validate that an error is thrown, or _not_ thrown, 
-the testing library provides several overloads of the macros that you can use.
-Use a ``Confirmation`` to confirm the occurrence of an asynchronous event that
-you can't check directly using an expectation.
+Use ``expect(_:_:sourceLocation:)`` and
+``require(_:_:sourceLocation:)-5l63q`` macros to validate expected
+outcomes.  To validate that an error is thrown, or _not_ thrown, the
+testing library provides several overloads of the macros that you can
+use.  Use a ``Confirmation`` to confirm the occurrence of an
+asynchronous event that you can't check directly using an expectation.
+
+### Validate your code's result
+
+To validate that your code produces an expected value, use
+``expect(_:_:sourceLocation:)``.  ``expect(_:_:sourceLocation:)`` captures the
+expression you pass, and provides detailed information when the code doesn't
+satisfy the expectation:
+
+```swift
+class OrderCalculator {
+    func total(of subtotals: [Int]) -> Int {
+        return subtotals.reduce(1) { partialResult, subtotal in
+            partialResult + subtotal
+        }
+    }
+}
+
+@Test func calculatingOrderTotal() {
+    let calculator = OrderCalculator()
+    #expect(calculator.total(of: [3, 3]) == 6)
+    // Prints "Expectation failed: (calculator.total(of: [3, 3]) → 7) == 6"
+}
+```
+
+Your test keeps running after ``expect(_:_:sourceLocation:)`` fails.  To stop
+the test when the code doesn't satisfy a requirement, use
+``require(_:_:sourceLocation:)-5l63q`` instead:
+
+```swift
+@Test func returningCustomerRemembersUsualOrder() throws {
+    let customer = Customer(id: 123)
+    try #require(customer)
+    #expect(customer?.usualOrder?.countOfItems == 2) // The test runner doesn't reach this line if the customer is nil.
+}
+```
+
+``require(_:_:sourceLocation:)-5l63q`` throws an instance of ``ExpectationFailedError`` when your code
+fails to satisfy the requirement.
 
 ## Topics
 
@@ -30,6 +69,7 @@ you can't check directly using an expectation.
 
 ### Checking that errors are thrown
 
+- <doc:testing-for-errors-in-swift-code>
 - ``expect(throws:_:sourceLocation:performing:)-79piu``
 - ``expect(throws:_:sourceLocation:performing:)-1xr34``
 - ``expect(_:sourceLocation:performing:throws:)``
@@ -41,6 +81,7 @@ you can't check directly using an expectation.
 
 ### Confirming that asynchronous events occur
 
+- ``<doc:testing-asynchronous-code>
 - ``confirmation(_:expectedCount:fileID:filePath:line:column:_:)``
 - ``Confirmation``
 

Sources/Testing/Testing.docc/testing-asynchronous-code.md

@@ -0,0 +1,70 @@
+# Testing asynchronous code
+
+<!--
+This source file is part of the Swift.org open source project
+
+Copyright (c) 2024 Apple Inc. and the Swift project authors
+Licensed under Apache License v2.0 with Runtime Library Exception
+
+See https://swift.org/LICENSE.txt for license information
+See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+Validate whether your code causes expected events to happen.
+
+## Overview
+
+`swift-testing` integrates with Swift concurrency, meaning that in many
+situations you can test asynchronous code using standard Swift
+features.  Mark your test function as `async` and, in the function
+body, `await` any asynchronous interactions:
+
+```swift
+@Test func priceLookupYieldsExpectedValue() async {
+    #expect(await unitPrice(for: .mozarella) == 3)
+}
+```
+
+In more complex situations, where the code you test doesn't use Swift
+concurrency, you use ``Confirmation`` to discover whether an expected
+event happens.
+
+### Confirm that an event happens
+
+If your code under test doesn't use Swift concurrency, call
+``confirmation(_:expectedCount:fileID:filePath:line:column:_:)`` in
+your asynchronous test function to create a `Confirmation` for the
+expected event.  In the trailing block parameter, call the code under
+test.  Swift Testing passes a `Confirmation` as the parameter to the
+block, which you call as a function in the completion or event handler
+for the code under test when the event you're testing for occurs:
+
+```swift
+@Test func orderCalculatorSuccessfullyCalculatesSubtotalForNoPizzas() async {
+    let calculator = OrderCalculator()
+    await confirmation() { confirmation in
+        calculator.successHandler = { _ in confirmation() }
+        calculator.subtotal(for: PizzaToppings(bases: []))
+    }
+}
+```
+
+If you expect the event to happen more than once, set the
+`expectedCount` parameter to the number of expected occurrences.  The
+test passes if the number of occurrences during the test matches the
+expected count, and fails otherwise.
+
+### Confirm that an event doesn't happen
+
+To validate that a particular event doesn't occur during a test,
+create a `Confirmation` with an expected count of `0`:
+
+```swift
+@Test func orderCalculatorEncountersNoErrors() async {
+    let calculator = OrderCalculator()
+    await confirmation(expectedCount: 0) { confirmation in
+        calculator.errorHandler = { _ in confirmation() }
+        calculator.subtotal(for: PizzaToppings(bases: []))
+    }
+}
+```

Sources/Testing/Testing.docc/testing-for-errors-in-swift-code.md

@@ -0,0 +1,131 @@
+# Testing for errors in Swift code
+
+<!--
+This source file is part of the Swift.org open source project
+
+Copyright (c) 2024 Apple Inc. and the Swift project authors
+Licensed under Apache License v2.0 with Runtime Library Exception
+
+See https://swift.org/LICENSE.txt for license information
+See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+Ensure that your code handles errors in the way you expect.
+
+## Overview
+
+The Swift language provides an idiomatic approach to [error
+handling](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling),
+based on throwing errors where your code detects a failure for a
+caller to catch and react to.
+
+Write tests for your code that validate the conditions in which the
+code throws errors, and the conditions in which it returns without
+throwing an error.  Use overrides of the `#expect()` and
+``require(_:_:sourceLocation:)-5l63q`` macros that check for errors.
+
+### Validate that your code throws an expected error
+
+The Swift structure in this example represents a list that accepts any
+number of toppings for pizzas in the list.  The API contains a method for
+applying a topping to a range of pizzas, and a method for retrieving the
+toppings requested for the item at a given index.  Both of these methods
+throw errors if their parameters are outside the list's range.
+
+```swift
+enum PizzaBase {
+    case deepCrust
+    case shallowCrust
+    case calzone
+}
+
+enum Topping {
+    case tomato
+    case cheese
+    case caper
+    case anchovy
+    case prosciutto
+    case pineapple
+}
+
+struct PizzaToppings {
+    enum PizzaToppingsError : Error {
+        case outOfRange
+    }
+
+    let pizzas: [PizzaBase]
+    var toppings: [Int: [Topping]]
+
+    init(bases: [PizzaBase]) {
+        pizzas = bases
+        toppings = [Int: [Topping]]()
+    }
+
+    mutating func add(topping: Topping, toPizzasIn range: Range<Int>) throws {
+        guard Int(range.startIndex) >= 0 && Int(range.endIndex) < pizzas.count else {
+            throw PizzaToppingsError.outOfRange
+        }
+        for index in range {
+            if var toppingList = toppings[index] {
+                toppingList.append(topping)
+                toppings[index] = toppingList
+            } else {
+                toppings[index] = [topping]
+            }
+        }
+    }
+
+    func toppings(forPizzaAt index: Int) throws -> [Topping] {
+        guard index >= 0 && index < pizzas.count else {
+            throw PizzaToppingsError.outOfRange
+        }
+        return toppings[index] ?? []
+    }
+
+    // Other methods.
+}
+```
+
+Create a test function that `throws` and `try` the code under test.
+If the code throws an error, then your test fails.
+
+To check that the code under test throws a specific error, or to continue a
+longer test function after the code throws an error, pass that error as the
+first argument of ``expect(throws:_:sourcelocation:performing:)-1xr34``, and
+pass a closure that calls the code under test:
+
+```swift
+@Test func cannotAddToppingToPizzaBeforeStartOfList() {
+    var order = PizzaToppings(bases: [.calzone, .deepCrust])
+    #expect(throws: PizzaToppings.PizzaToppingsError.outOfRange) {
+        try order.add(topping: .mozarella, toPizzasIn: -1..<0)
+    }
+}
+```
+
+If the closure completes without throwing an error, the testing library
+records an issue.  Other overloads of ``expect(_:_:sourceLocation:)`` let you test that
+the code throws an error of a given type, or matching an arbitrary
+Boolean test.  Similar overloads of ``require(_:_:sourceLocation:)-5l63q`` stop running your
+test if the code doesn't throw the expected error.
+
+### Validate that your code doesn't throw an error
+
+Validate that the code under test doesn't throw an error by comparing
+the error to `Never`:
+
+```swift
+@Test func canAddToppingToPizzaInPositionZero() throws {
+    var order = PizzaToppings(bases: [.thinCrust, .thinCrust])
+    #expect(throws: Never.self) {
+        try order.add(topping: .caper, toPizzasIn: 0..<1)
+    }
+    let toppings = try order.toppings(forPizzaAt: 0)
+    #expect(toppings == [.caper])
+}
+```
+
+If the closure throws an error, the testing library records an issue.
+If you need the test to stop if the code throws an error, include the
+code inline in the test function instead of wrapping it in an
+``expect(throws:_:sourcelocation:performing:)-1xr34`` block.