@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-testing/references/testing-advanced.md

@@ -1,123 +1,119 @@
-# Advanced Testing Patterns
+# Newer Swift Testing APIs
 
-Warning-severity issues, programmatic test cancellation, and image attachments for Swift Testing.
+Companion to the `swift-testing` skill. Each section names the Swift Testing
+proposal (ST-nnnn) and the toolchain that ships it.
 
-## Contents
+## Warnings: `Issue.record(_:severity:)`
 
-- [Warning-Severity Issues](#warning-severity-issues)
-- [Programmatic Test Cancellation](#programmatic-test-cancellation)
-- [Exit Test Value Capturing](#exit-test-value-capturing)
-- [Image Attachments](#image-attachments)
-- [Version Gates](#version-gates)
-- [Proposal Reference](#proposal-reference)
-
-## Warning-Severity Issues
-
-ST-0013 adds a `severity` parameter to `Issue.record()` in Swift 6.3 / Xcode 26.4 and newer. Warnings are surfaced in test output but do not cause the test to fail.
+ST-0013, Swift 6.3 and Xcode 26.4 or later. An issue recorded with
+`.warning` shows up in the results without failing the test.
 
 ```swift
-@Test func dataIntegrity() {
-    let result = loadData()
-
-    // Hard failure  -  test fails
-    #expect(result.isValid)
-
-    // Warning  -  logged but test still passes
-    if result.processingTime > 2.0 {
-        Issue.record(
-            "Processing took \(result.processingTime)s  -  exceeds 2s target",
-            severity: .warning
-        )
+@Test func thumbnailBatch() async throws {
+    let clock = ContinuousClock()
+    let start = clock.now
+    let thumbnails = try await Thumbnailer().render(Fixtures.photos)
+    let elapsed = start.duration(to: clock.now)
+
+    #expect(thumbnails.count == Fixtures.photos.count)
+    if elapsed > .seconds(2) {
+        Issue.record("Batch took \(elapsed)", severity: .warning)
     }
 }
 ```
 
-Use warnings for:
-- Performance regressions that aren't blocking
-- Deprecated code paths that still work
-- Non-critical data quality checks
-- Flaky conditions you want to track without failing CI
+Good uses:
+- performance drift that should be visible but not block a merge,
+- a deprecated path that still works,
+- data checks that are nice to have,
+- a flaky condition you want to track without failing CI.
 
-## Programmatic Test Cancellation
+## Cancelling a Test: `Test.cancel(_:)`
 
-ST-0016 adds `try Test.cancel()` in Swift 6.3 / Xcode 26.4 and newer to stop a test from within without marking it as passed or failed. The test is recorded as "cancelled."
+ST-0016, Swift 6.3 and Xcode 26.4 or later. `try Test.cancel()` stops the test
+and reports it as cancelled: neither passed nor failed.
 
 ```swift
-@Test func requiresNetwork() async throws {
-    guard NetworkMonitor.shared.isConnected else {
-        try Test.cancel("No network  -  skipping integration test")
+@Test func downloadsLiveCatalog() async throws {
+    guard await Reachability.isOnline() else {
+        try Test.cancel("No network on this runner")
     }
-
-    let response = try await APIClient.shared.healthCheck()
-    #expect(response.status == .ok)
+    let catalog = try await CatalogClient.live.fetch()
+    #expect(!catalog.isEmpty)
 }
 ```
 
-Key differences from other mechanisms:
-- Throwing an error  -  marks the test as failed
-- `withKnownIssue`  -  marks a failure as expected (test still runs)
-- `try Test.cancel()`  -  marks the test as cancelled (neutral outcome, test stops)
+| Outcome | How you get it |
+|---------|----------------|
+| Failed | The test throws an error |
+| Expected failure | `withKnownIssue`; the test keeps running |
+| Cancelled | `Test.cancel`; the test stops, neutral result |
 
-## Exit Test Value Capturing
+## Capturing Values in Exit Tests
 
-ST-0012 allows exit tests to capture values from the enclosing scope when using the Swift 6.3 compiler. Exit testing itself requires Swift 6.2 / Xcode 26.0 or newer and uses the `processExitsWith:` macros.
-
-When an exit-test body reads values from the parent process, correct the sample to use an explicit capture list and mention the Swift 6.3 compiler requirement. Captured values must conform to `Sendable` and `Codable`.
+ST-0012 lets an exit test's closure capture values from the surrounding scope.
+It needs the Swift 6.3 compiler. Exit tests themselves arrived in Swift 6.2
+(Xcode 26.0) through the `processExitsWith:` macros. Captured values must be
+`Sendable` and `Codable`, because they are sent to the child process.
 
 ```swift
-@Test func exitCodeValidation() async {
-    let expectedCode: Int32 = 42
-    await #expect(processExitsWith: .failure) { [expectedCode] in
-        exit(expectedCode)  // Can now capture `expectedCode`
+@Test func abortsOnUnknownMode() async {
+    let mode = "turbo"
+    await #expect(processExitsWith: .failure) { [mode = mode as String] in
+        Launcher.start(mode: mode)
     }
 }
 ```
 
+Spell out each captured value's type as above; the macro rejects a bare
+`[mode]` as ambiguous.
+
 ## Image Attachments
 
-ST-0014 adds image attachments in Swift 6.3 / Xcode 26.4 and newer. Import both `Testing` and the relevant UI framework, then record platform image values directly and specify `as:` when you need an explicit format.
+ST-0014, Swift 6.3 and Xcode 26.4 or later. Import `Testing` together with the
+UI framework that defines the image type; the support comes from cross-import
+overlays. Pass `as:` to choose the file format.
 
 ```swift
 import Testing
 import UIKit
 
-@Test func renderedOutput() async throws {
-    let view = ChartView(data: sampleData)
-    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 400, height: 300))
-    let image = renderer.image { ctx in
-        view.drawHierarchy(in: view.bounds, afterScreenUpdates: true)
+@MainActor
+@Test func sparklineRendering() {
+    let size = CGSize(width: 240, height: 80)
+    let image = UIGraphicsImageRenderer(size: size).image { context in
+        SparklineRenderer(values: [3, 5, 2, 8]).draw(in: context.cgContext, size: size)
     }
-
-    // Attach UIImage directly
-    Attachment.record(image, named: "chart-output", as: .png)
+    Attachment.record(image, named: "sparkline", as: .png)
 }
 ```
 
-Supported Apple-platform image types include:
-- `UIImage` on iOS, tvOS, visionOS, and watchOS when importing UIKit
-- `CGImage` when importing CoreGraphics
-- `CIImage` when importing CoreImage
-- `NSImage` on macOS when importing AppKit
+| Type | Where |
+|------|-------|
+| `UIImage` | iOS, tvOS, visionOS, and watchOS with UIKit |
+| `CGImage` | Core Graphics |
+| `CIImage` | Core Image |
+| `NSImage` | macOS with AppKit |
 
 ## Version Gates
 
-| Feature | Minimum toolchain / platform |
-|---|---|
-| Attachments API for standard attachable values | Swift 6.2 / Xcode 26.0 |
-| Exit testing with `processExitsWith:` | Swift 6.2 / Xcode 26.0; supported on macOS, Linux, FreeBSD, OpenBSD, and Windows runtime targets |
-| Exit-test capture lists | Swift 6.3 compiler |
-| `Issue.record(_:severity:)` warnings | Swift 6.3 / Xcode 26.4 |
-| `Test.cancel(_:)` | Swift 6.3 / Xcode 26.4 |
-| Image attachment recording | Swift 6.3 / Xcode 26.4 |
-
-Do not use exit tests for iOS, tvOS, or watchOS runtime targets. For iOS app code that needs fatal-path coverage, move the exit behavior behind a smaller pure Swift API, test the non-exiting branches directly, and reserve exit tests for a supported host/tool target.
-
-## Proposal Reference
-
-| Proposal | Feature |
-|---|---|
-| ST-0009 | Attachments API (`Attachment` type, `.record()`) |
-| ST-0012 | Exit test value capturing |
-| ST-0013 | Warning-severity issues (`Issue.record` with `severity:`) |
-| ST-0014 | Image attachments on Apple platforms (cross-import overlays) |
-| ST-0016 | Programmatic test cancellation (`try Test.cancel()`) |
+| Feature | Minimum |
+|---------|---------|
+| Attachments of standard values | Swift 6.2, Xcode 26.0 |
+| Exit tests with `processExitsWith:` | Swift 6.2, Xcode 26.0; macOS, Linux, FreeBSD, OpenBSD, Windows |
+| Capture lists in exit tests | Swift 6.3 compiler |
+| `Issue.record(_:severity:)`, `Test.cancel(_:)`, image attachments | Swift 6.3, Xcode 26.4 |
+
+iOS, tvOS and watchOS have no exit tests. Put the exiting behaviour behind a
+small pure function, test the branches that do not exit, and keep real exit
+tests for host or tool targets where they are supported.
+
+## Proposals
+
+| Proposal | Adds |
+|----------|------|
+| ST-0009 | Attachments: the `Attachment` type and recording it |
+| ST-0012 | Capturing values in exit tests |
+| ST-0013 | Issue severity, including warnings |
+| ST-0014 | Image attachments on Apple platforms through cross-import overlays |
+| ST-0016 | `Test.cancel()` |