### Swift Example Application Naming

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/StyleGuide.md

Defines the standard naming convention for example applications, projects, and packages used in documentation. 'FoodTruck' is the recommended imaginary application.

```APIDOC
Swift Example Application Naming:

- Use 'FoodTruck' as the standard imaginary application for examples.
- FoodTruck is based on a mobile restaurant concept.
- When referencing foods, prefer internationally recognizable items or a diverse set from multiple cultures.
- Example code must be syntactically correct and runnable.
- External dependencies in examples should be easy to understand or replaceable.
```

--------------------------------

### Convert XCTest setUp() to Swift init()

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/MigratingFromXCTest.md

In XCTest, setup code runs using setUp() and tearDown(). In the Swift testing library, use init() for setup logic. The use of async and throws is optional for init().

```swift
// Before
class FoodTruckTests: XCTestCase {
  var batteryLevel: NSNumber!
  override func setUp() async throws {
    batteryLevel = 100
  }
  ...
}
```

```swift
// After
struct FoodTruckTests {
  var batteryLevel: NSNumber
  init() async throws {
    batteryLevel = 100
  }
  ...
}
```

--------------------------------

### Swift Documentation Style References

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/StyleGuide.md

Outlines the preferred style guides for documentation within the Swift project. This includes the Swift Book style guide and the Apple Style Guide.

```APIDOC
Swift Documentation Style References:

- General documentation should follow the Swift Book style guide.
- Apple Style Guide should be followed contextually where appropriate.
- References:
  - Swift Book Style Guide: https://github.com/swiftlang/swift-book/blob/main/Style.md
  - Apple Style Guide: https://support.apple.com/guide/applestyleguide/
```

--------------------------------

### Install Swift Testing Target

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/_TestDiscovery/CMakeLists.txt

Installs the '_TestDiscovery' target using a custom macro `_swift_testing_install_target`. This command handles the installation process for the library.

```CMake
_swift_testing_install_target(_TestDiscovery)
```

--------------------------------

### Install Project with CMake

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Configures and installs the built Swift Testing project content into a specified directory using CMake. This is useful for validating the build output.

```cmake
cmake -G Ninja --install-prefix "$(pwd)/build/install" -B build
cmake --install build
```

--------------------------------

### Build Swift Testing Docker Image

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Builds the Docker image for Swift Testing on macOS. Requires Docker Desktop installed. Tags the image as 'swift-testing:latest'.

```bash
$> docker build -t swift-testing:latest .
```

--------------------------------

### Interactive Docker Session for Swift Testing

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Starts an interactive Docker container session for Swift Testing development. Mounts the current directory and provides a bash shell inside the container.

```bash
$> docker run -i -t -v "$(pwd)":/swift-testing swift-testing /bin/bash
```

--------------------------------

### CMake Project Setup and Dependencies

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/TestingMacros/CMakeLists.txt

Initializes the CMake project, sets the minimum required version, and finds necessary packages like SwiftSyntax. It also handles conditional fetching of SwiftSyntax for building macros as executables.

```cmake
cmake_minimum_required(VERSION 3.19.6...3.29)

if(POLICY CMP0157)
  cmake_policy(SET CMP0157 NEW)
endif()

project(TestingMacros
  LANGUAGES Swift)

list(APPEND CMAKE_MODULE_PATH
  ${CMAKE_SOURCE_DIR}/../../cmake/modules/shared)

if(WIN32)
  add_compile_definitions(_CRT_SECURE_NO_WARNINGS)
endif()

find_package(SwiftSyntax CONFIG GLOBAL)

if(SwiftTesting_BuildMacrosAsExecutables)
  # When building the macro plugin as an executable, clone and build
  # swift-syntax.
  include(FetchContent)
  set(FETCHCONTENT_BASE_DIR ${CMAKE_BINARY_DIR}/_d)
  FetchContent_Declare(SwiftSyntax
    GIT_REPOSITORY https://github.com/swiftlang/swift-syntax
    GIT_TAG 340f8400262d494c7c659cd838223990195d7fed) # 602.0.0-prerelease-2025-04-10
  FetchContent_MakeAvailable(SwiftSyntax)
endif()

# Include these modules _after_ swift-syntax is declared above, but _before_ the
# macro plugin target is declared below, so that its settings are not applied to
# the former but are applied to the latter.
include(AvailabilityDefinitions)
include(CompilerSettings)
```

--------------------------------

### Swift #expect() Macro Expansion Example

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/ExpectationCapture.md

Provides a concrete example of how the #expect() macro transforms a simple comparison expression into a more verbose internal testing function call.

```swift
```swift
// Before
#expect(f() < g())

// After expansion (simplified)
Testing.__checkBinaryOperation(
  f(),
  { $0 < $1() },
  g(),
  expression: .__fromBinaryOperation(
    .__fromSyntaxNode("f()"),
    "<",
    .__fromSyntaxNode("g()")
  ),
  comments: [],
  isRequired: false,
  sourceLocation: Testing.SourceLocation.__here()
).__expected()
```
```

--------------------------------

### Swift Compile-Time Diagnostics Style

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/StyleGuide.md

Specifies the style guide for writing compile-time diagnostics within the Swift package. Diagnostics should adhere to the Swift style guide for compiler diagnostics.

```APIDOC
Swift Compile-Time Diagnostics Style:

- Write diagnostics according to the Swift style guide for compiler diagnostics.
- Reference: https://github.com/swiftlang/swift/blob/main/docs/Diagnostics.md
```

--------------------------------

### Swift Symbol Abstract Guidelines

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/StyleGuide.md

Provides rules for writing concise and effective abstracts for Swift symbols. Abstracts should be a single sentence, 150 characters or less, avoid repeating technical terms, and not include links or code formatting.

```APIDOC
Swift Symbol Abstract Guidelines:

- Limit abstracts to a single sentence (150 characters or fewer).
- Move additional information to Overview or Discussion sections.
- Do not repeat technical terms from the entity's name.
- Avoid links to other symbols within the abstract.
- Use plain English instead of code font for terms.
- Avoid parentheses or slashes, except for acronyms (spell out on first use).
- Avoid locational modifiers like 'the following' or 'below'.
- Use correct grammatical style: noun phrase or verb phrase (verb ending in 's' or imperative).

Example Abstract (Class):
An object that stores the details for a specific order from a vendor.

Example Abstract (Enumeration):
Describes the flavors of an ingredient.
```

--------------------------------

### Define Swift Testing Executable Target

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/CMake.md

Shows how to define a CMake executable target for tests. It sets the target name, links necessary libraries (e.g., 'Example', 'Testing'), and configures the executable suffix to '.swift-testing'.

```cmake
add_executable(ExamplePackageTests
  ExampleTests.swift
  ...)
set_target_properties(ExamplePackageTests PROPERTIES
  SUFFIX .swift-testing)
target_link_libraries(ExamplePackageTests PRIVATE
  Example
  Testing
  ...)
```

--------------------------------

### C/C++ Symbol Naming and Visibility

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/StyleGuide.md

Illustrates C/C++ naming conventions, including prefixes for internal symbols (`swt_`), public symbols (`swift_testing_`), and types (`SWT`). Uses `SWT_EXTERN` for consistent visibility.

```c
SWT_EXTERN bool swt_isDebugModeEnabled(void);

SWT_EXTERN void swt_setDebugModeEnabled(bool isEnabled);

```

```c
SWT_EXTERN void swift_testing_debugIfNeeded(void);

```

```c
typedef intmax_t SWTBigInteger;

typedef struct SWTContainer {
  ...
} SWTContainer;

```

--------------------------------

### Install Internal Library Archive

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/_TestingInternals/CMakeLists.txt

Conditionally installs the '_TestingInternals' static library archive. This installation occurs only when building shared libraries is disabled (i.e., when building static libraries), ensuring the internal library is available alongside the main library.

```cmake
if(NOT BUILD_SHARED_LIBS)
  # When building a static library, install the internal library archive
  # alongside the main library. In shared library builds, the internal library
  # is linked into the main library and does not need to be installed separately.
  install(TARGETS _TestingInternals
    ARCHIVE DESTINATION "${SwiftTesting_INSTALL_LIBDIR}")
endif()
```

--------------------------------

### Precondition Failure Example

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/exit-testing.md

Demonstrates how a `precondition` failure in Swift can cause a process to exit. This is useful for testing error handling paths.

```Swift
extension Customer {
  func eat(_ food: consuming some Food) {
    precondition(food.isDelicious, "Tasty food only!")
    precondition(food.isNutritious, "Healthy food only!")
    ...
  }
}
```

--------------------------------

### Test Scoping and Preparation

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/Traits/Trait.md

Traits related to defining the scope of tests and executing setup or teardown code.

```APIDOC
TestScoping
  A protocol for defining test scoping behavior.

Trait/scopeProvider(for:testCase:)-cjmg
  Provides a scope provider for a given test case.
  - Parameters:
    - testCase: The test case for which to provide a scope.
  - Returns: An object conforming to TestScoping.

Trait/TestScopeProvider
  A type alias for a scope provider.

Trait/prepare(for:)-3s3zo
  Prepares the test environment before a test or suite runs.
  - Parameters:
    - context: The context in which the preparation is happening.
```

--------------------------------

### Swift Testing Project CMake Configuration

Source: https://github.com/swiftlang/swift-testing/blob/main/CMakeLists.txt

This CMakeLists.txt file configures the build system for the Swift Testing project. It sets minimum CMake version, handles platform-specific policies (like CMP0157 on Windows/Android), defines project languages (C++ and Swift), finds necessary packages (dispatch, Foundation), sets output directories, and configures installation paths and compiler options.

```CMake
# 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 http://swift.org/LICENSE.txt for license information
# See http://swift.org/CONTRIBUTORS.txt for Swift project authors

cmake_minimum_required(VERSION 3.19.6...3.29)

if(POLICY CMP0157)
  if(CMAKE_HOST_SYSTEM_NAME STREQUAL Windows AND CMAKE_SYSTEM_NAME STREQUAL Android)
    # CMP0157 causes builds to fail when targetting Android with the Windows
    # toolchain, because the early swift-driver isn't (yet) available. Disable
    # it for now.
    cmake_policy(SET CMP0157 OLD)
  else()
    cmake_policy(SET CMP0157 NEW)
  endif()
endif()

project(SwiftTesting
  LANGUAGES CXX Swift)

if(NOT APPLE)
  if(NOT CMAKE_SYSTEM_NAME STREQUAL WASI)
    find_package(dispatch CONFIG)
  endif()
  find_package(Foundation CONFIG)
endif()

include(GNUInstallDirs)

list(APPEND CMAKE_MODULE_PATH
  ${PROJECT_SOURCE_DIR}/cmake/modules
  ${PROJECT_SOURCE_DIR}/cmake/modules/shared)

set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)

set(CMAKE_INSTALL_RPATH "$<IF:$<PLATFORM_ID:Darwin>,@loader_path/..,$ORIGIN>")
set(CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH YES)

set(CMAKE_MSVC_RUNTIME_LIBRARY MultiThreadedDLL)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_Swift_LANGUAGE_VERSION 6)
set(CMAKE_Swift_MODULE_DIRECTORY ${CMAKE_BINARY_DIR}/swift)

include(PlatformInfo)
include(SwiftModuleInstallation)

option(SwiftTesting_INSTALL_NESTED_SUBDIR "Install libraries under a platform and architecture subdirectory" NO)
set(SwiftTesting_INSTALL_LIBDIR "${CMAKE_INSTALL_LIBDIR}/swift$<$<NOT:$<BOOL:${BUILD_SHARED_LIBS}>>:_static>/${SwiftTesting_PLATFORM_SUBDIR}$<$<AND:$<PLATFORM_ID:Darwin>,$<NOT:$<BOOL:${SwiftTesting_INSTALL_NESTED_SUBDIR}>>>:/testing>$<$<BOOL:${SwiftTesting_INSTALL_NESTED_SUBDIR}>:/${SwiftTesting_ARCH_SUBDIR}>")
set(SwiftTesting_INSTALL_SWIFTMODULEDIR "${CMAKE_INSTALL_LIBDIR}/swift$<$<NOT:$<BOOL:${BUILD_SHARED_LIBS}>>:_static>/${SwiftTesting_PLATFORM_SUBDIR}$<$<AND:$<PLATFORM_ID:Darwin>,$<NOT:$<BOOL:${SwiftTesting_INSTALL_NESTED_SUBDIR}>>>:/testing>")

add_compile_options($<$<COMPILE_LANGUAGE:Swift>:-no-toolchain-stdlib-rpath>)

add_subdirectory(Sources)
```

--------------------------------

### Swift Testing Library Build Configuration

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/CMakeLists.txt

This CMake script configures the build for the Swift Testing library. It defines the library, links necessary internal and external libraries, sets compiler flags for Swift features like library evolution and module interfaces, and specifies installation procedures.

```cmake
add_library(Testing
  ABI/EntryPoints/ABIEntryPoint.swift
  ABI/EntryPoints/EntryPoint.swift
  ABI/EntryPoints/SwiftPMEntryPoint.swift
  ABI/ABI.Record.swift
  ABI/ABI.Record+Streaming.swift
  ABI/ABI.swift
  ABI/ABI.VersionNumber.swift
  ABI/Encoded/ABI.EncodedAttachment.swift
  ABI/Encoded/ABI.EncodedBacktrace.swift
  ABI/Encoded/ABI.EncodedError.swift
  ABI/Encoded/ABI.EncodedEvent.swift
  ABI/Encoded/ABI.EncodedInstant.swift
  ABI/Encoded/ABI.EncodedIssue.swift
  ABI/Encoded/ABI.EncodedMessage.swift
  ABI/Encoded/ABI.EncodedTest.swift
  Attachments/Attachable.swift
  Attachments/AttachableWrapper.swift
  Attachments/Attachment.swift
  Events/Clock.swift
  Events/Event.swift
  Events/Recorder/Event.ConsoleOutputRecorder.swift
  Events/Recorder/Event.HumanReadableOutputRecorder.swift
  Events/Recorder/Event.JUnitXMLRecorder.swift
  Events/Recorder/Event.Symbol.swift
  Events/TimeValue.swift
  ExitTests/ExitTest.swift
  ExitTests/ExitTest.CapturedValue.swift
  ExitTests/ExitTest.Condition.swift
  ExitTests/ExitTest.Result.swift
  ExitTests/SpawnProcess.swift
  ExitTests/ExitStatus.swift
  ExitTests/WaitFor.swift
  Expectations/Expectation.swift
  Expectations/Expectation+Macro.swift
  Expectations/ExpectationChecking+Macro.swift
  Issues/Confirmation.swift
  Issues/ErrorSnapshot.swift
  Issues/Issue.swift
  Issues/Issue+Recording.swift
  Issues/KnownIssue.swift
  Parameterization/CustomTestArgumentEncodable.swift
  Parameterization/Test.Case.Generator.swift
  Parameterization/Test.Case.ID.swift
  Parameterization/Test.Case.swift
  Parameterization/TypeInfo.swift
  Running/Configuration.swift
  Running/Configuration.TestFilter.swift
  Running/Configuration+EventHandling.swift
  Running/Runner.Plan.swift
  Running/Runner.Plan+Dumping.swift
  Running/Runner.RuntimeState.swift
  Running/Runner.swift
  Running/SkipInfo.swift
  SourceAttribution/Backtrace.swift
  SourceAttribution/Backtrace+Symbolication.swift
  SourceAttribution/CustomTestStringConvertible.swift
  SourceAttribution/Expression.swift
  SourceAttribution/Expression+Macro.swift
  SourceAttribution/SourceContext.swift
  SourceAttribution/SourceLocation.swift
  SourceAttribution/SourceLocation+Macro.swift
  Support/Additions/ArrayAdditions.swift
  Support/Additions/CollectionDifferenceAdditions.swift
  Support/Additions/CommandLineAdditions.swift
  Support/Additions/NumericAdditions.swift
  Support/Additions/ResultAdditions.swift
  Support/Additions/WinSDKAdditions.swift
  Support/CartesianProduct.swift
  Support/CError.swift
  Support/CustomIssueRepresentable.swift
  Support/Environment.swift
  Support/FileHandle.swift
  Support/GetSymbol.swift
  Support/Graph.swift
  Support/JSON.swift
  Support/Locked.swift
  Support/Locked+Platform.swift
  Support/Versions.swift
  Discovery+Macro.swift
  Test.ID.Selection.swift
  Test.ID.swift
  Test.swift
  Test+Discovery.swift
  Test+Discovery+Legacy.swift
  Test+Macro.swift
  Traits/Bug.swift
  Traits/Comment.swift
  Traits/Comment+Macro.swift
  Traits/ConditionTrait.swift
  Traits/ConditionTrait+Macro.swift
  Traits/HiddenTrait.swift
  Traits/IssueHandlingTrait.swift
  Traits/ParallelizationTrait.swift
  Traits/Tags/Tag.Color.swift
  Traits/Tags/Tag.Color+Loading.swift
  Traits/Tags/Tag.List.swift
  Traits/Tags/Tag.swift
  Traits/Tags/Tag+Macro.swift
  Traits/Tags/Tag+Predefined.swift
  Traits/TimeLimitTrait.swift
  Traits/Trait.swift)
target_link_libraries(Testing PRIVATE
  _TestDiscovery
  _TestingInternals)
if(NOT APPLE)
  if(NOT CMAKE_SYSTEM_NAME STREQUAL WASI)
    target_link_libraries(Testing PUBLIC
      dispatch)
  endif()
  target_link_libraries(Testing PUBLIC
    Foundation)
  if (CMAKE_SYSTEM_NAME STREQUAL "FreeBSD")
    target_link_libraries(Testing PUBLIC execinfo)
  endif()
endif()
if(NOT BUILD_SHARED_LIBS)
  # When building a static library, tell clients to autolink the internal
  # libraries.
  target_compile_options(Testing PRIVATE
    "SHELL:-Xfrontend -public-autolink-library -Xfrontend _TestDiscovery"
    "SHELL:-Xfrontend -public-autolink-library -Xfrontend _TestingInternals")
endif()
add_dependencies(Testing
  TestingMacros)
target_compile_options(Testing PRIVATE
  -enable-library-evolution
  -emit-module-interface -emit-module-interface-path $<TARGET_PROPERTY:Testing,Swift_MODULE_DIRECTORY>/Testing.swiftinterface)

_swift_testing_install_target(Testing)

# Install the Swift cross-import overlay directory.
_swift_testing_install_swiftcrossimport(Testing
  Testing.swiftcrossimport)
```

--------------------------------

### Add Swift Testing Foundation Subdirectory (CMake)

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Overlays/CMakeLists.txt

Integrates the Swift Testing Foundation module into the build system. This CMake command recursively processes the build script in the specified subdirectory, adding its targets to the current project. It's essential for modularizing the build and managing dependencies within the Swift-Testing project.

```cmake
add_subdirectory(_Testing_Foundation)
```

--------------------------------

### Conditional Installation of Static Library Archive

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/_TestDiscovery/CMakeLists.txt

Conditionally installs the archive of the '_TestDiscovery' static library. This is performed only when building static libraries, ensuring the internal library is available separately.

```CMake
if(NOT BUILD_SHARED_LIBS)
  # When building a static library, install the internal library archive
  # alongside the main library. In shared library builds, the internal library
  # is linked into the main library and does not need to be installed separately.
  install(TARGETS _TestDiscovery
    ARCHIVE DESTINATION "${SwiftTesting_INSTALL_LIBDIR}")
endif()
```

--------------------------------

### Swift Documentation Language and Tone

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/StyleGuide.md

Specifies the language and tone requirements for Swift documentation. Documentation should be in U.S. English for an international audience, avoiding culturally specific references.

```APIDOC
Swift Documentation Language and Tone:

- Write documentation in U.S. English.
- Target an international audience.
- Avoid culturally specific references unless directly relevant.
- Culturally insensitive or inappropriate language is not tolerated.
- Refer to the Swift Code of Conduct: https://swift.org/code-of-conduct
```

--------------------------------

### Set Swift Toolchain Path (macOS)

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Configures the environment to use the Swift toolchain when Xcode is installed on macOS. This ensures the system can locate and use the correct Swift compiler and tools.

```bash
export TOOLCHAINS=swift
xcrun --find swift
```

--------------------------------

### Swift Testing Sequential Test Execution

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/MigratingFromXCTest.md

Illustrates how to run tests sequentially in Swift Testing using the `@Suite(.serialized)` annotation. The example shows the equivalent `RefrigeratorTests` suite, now annotated to ensure serial execution, and uses `#expect` for assertions.

```swift
// After
@Suite(.serialized)
class RefrigeratorTests {
  @Test func lightComesOn() throws {
    try FoodTruck.shared.refrigerator.openDoor()
    #expect(FoodTruck.shared.refrigerator.lightState == .on)
  }
  
  @Test func lightGoesOut() throws {
    try FoodTruck.shared.refrigerator.openDoor()
    try FoodTruck.shared.refrigerator.closeDoor()
    #expect(FoodTruck.shared.refrigerator.lightState == .off)
  }
}
```

--------------------------------

### Include System Headers for Platform-Specific Functionality

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/Porting.md

Demonstrates how to conditionally include platform-specific C headers within the Swift Testing internals module. This example shows adding `DateTimeUtils.h` for the Classic Mac OS platform to enable access to functions like `GetDateTime()`.

```diff
--- a/Sources/_TestingInternals/include/Includes.h
+++ b/Sources/_TestingInternals/include/Includes.h

+#if defined(macintosh)
+#include <DateTimeUtils.h>
+#endif
```

--------------------------------

### Loading Discovered Test Content Records

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/ABI/TestContent.md

Provides an example of iterating through all discovered test content records for a specific type, checking a condition on the record's context, and then loading the actual test content instance using its `load()` method, optionally providing a hint.

```swift
for diagnosticRecord in FoodTruckDiagnostic.allTestContentRecords() {
  if diagnosticRecord.context.pointee == .briansBranMuffins {
    if let diagnostic = diagnosticRecord.load(withHint: "...") {
      diagnostic.run()
    }
  }
}
```

--------------------------------

### Executable Target Configuration for Macros

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/TestingMacros/CMakeLists.txt

Configures the 'TestingMacros' target as an executable when 'SwiftTesting_BuildMacrosAsExecutables' is enabled. It sets properties like ENABLE_EXPORTS, parses the module as a library, and defines installation rules.

```cmake
if(SwiftTesting_BuildMacrosAsExecutables)
  # When swift-syntax is built locally, the macro plugin must be built as an
  # executable.
  add_executable(TestingMacros)

  set_target_properties(TestingMacros PROPERTIES
    ENABLE_EXPORTS TRUE)

  # Parse the module as a library, even though it's an executable, because it
  # uses an `@main` type to define its entry point.
  target_compile_options(TestingMacros PRIVATE -parse-as-library)

  # Include the .swift file which contains its `@main` entry point type.
  target_compile_definitions(TestingMacros PRIVATE SWT_NO_LIBRARY_MACRO_PLUGINS)

  install(TARGETS TestingMacros
    RUNTIME DESTINATION bin)
else()
  add_library(TestingMacros SHARED)

  target_link_options(TestingMacros PRIVATE "-no-toolchain-stdlib-rpath")
  set_property(TARGET TestingMacros PROPERTY BUILD_WITH_INSTALL_RPATH YES)

  if(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
    set(plugin_destination_dir "lib/swift/host/plugins/testing")
    set_property(TARGET TestingMacros PROPERTY INSTALL_RPATH)
  else()
    set(plugin_destination_dir "lib/swift/host/plugins")
    # RPATH 'lib/swift/{system}' and 'lib/swift/host'
    set_property(TARGET TestingMacros PROPERTY
      INSTALL_RPATH "$ORIGIN/../../$<LOWER_CASE:${CMAKE_SYSTEM_NAME}>;$ORIGIN/..")
  endif()

  install(TARGETS TestingMacros
    LIBRARY DESTINATION "${plugin_destination_dir}"
    RUNTIME DESTINATION bin)
endif()
```

--------------------------------

### Swift Symbol Naming Conventions

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/StyleGuide.md

Demonstrates Swift symbol naming conventions for internal-use public symbols (double underscore) and private symbols (single underscore).

```swift
public func __check()

```

```swift
private var _errorCount: Int

public var errorCount: Int {
  get {
    _errorCount
  }
  set {
    precondition(newValue >= 0, "Error count cannot be negative")
    _errorCount = newValue
  }
}

```

--------------------------------

### Configuring Fulfillment Count with Confirmation

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/MigratingFromXCTest.md

Illustrates how to configure the number of times an expectation or confirmation should be met. This example shows setting `expectedFulfillmentCount` for XCTestExpectation and using a range for the `expectedCount` parameter in Confirmation.

```swift
// Before: XCTestExpectation with expectedFulfillmentCount
func testRegularCustomerOrders() async {
  let soldFood = expectation(description: "...")
  soldFood.expectedFulfillmentCount = 10
  soldFood.assertForOverFulfill = false
  FoodTruck.shared.eventHandler = { event in
    if case .soldFood = event {
      soldFood.fulfill()
    }
  }
  for customer in regularCustomers() {
    await customer.buy(customer.regularOrder)
  }
  await fulfillment(of: [soldFood])
  ...
}
```

```swift
// After: Confirmation with expectedCount range
@Test func regularCustomerOrders() async {
  await confirmation(
    "...",
    expectedCount: 10...
  ) { soldFood in
    FoodTruck.shared.eventHandler = { event in
      if case .soldFood = event {
        soldFood()
      }
    }
    for customer in regularCustomers() {
      await customer.buy(customer.regularOrder)
    }
  }
  ...
}
```

--------------------------------

### Creating an Exit Test with Expect

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/exit-testing.md

Shows how to use the `expect(processExitsWith:)` macro to create an exit test. The macro starts a child process to execute the provided closure and asserts that the child process exits with the specified condition.

```Swift
@Test func `Customer won't eat food unless it's delicious`() async {
  let result = await #expect(processExitsWith: .failure) {
    var food = ...
    food.isDelicious = false
    Customer.current.eat(food)
  }
}
```

--------------------------------

### Tag Color Configuration JSON

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/AddingTags.md

Example JSON structure for `tag-colors.json` to map Swift test tags to specific colors. Colors can be predefined names or hexadecimal RGB values.

```JSON
{
  ".critical": "orange",
  ".legallyRequired": "#66FFCC"
}
```

--------------------------------

### XCTest Sequential Test Execution

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/MigratingFromXCTest.md

Demonstrates how to define tests in XCTest that may exhibit unexpected behavior when run in parallel due to shared state. The example shows two test functions, `testLightComesOn` and `testLightGoesOut`, within the `RefrigeratorTests` class.

```swift
// Before
class RefrigeratorTests : XCTestCase {
  func testLightComesOn() throws {
    try FoodTruck.shared.refrigerator.openDoor()
    XCTAssertEqual(FoodTruck.shared.refrigerator.lightState, .on)
  }
  
  func testLightGoesOut() throws {
    try FoodTruck.shared.refrigerator.openDoor()
    try FoodTruck.shared.refrigerator.closeDoor()
    XCTAssertEqual(FoodTruck.shared.refrigerator.lightState, .off)
  }
}
```

--------------------------------

### XCTest Value Attachment

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/MigratingFromXCTest.md

Shows how to attach an object to a test result in XCTest using `XCTAttachment`. The example demonstrates attaching a `Tortilla` object (conforming to `NSSecureCoding`) to the test results.

```swift
// Before
import Foundation

class Tortilla: NSSecureCoding { /* ... */ }

func testTortillaIntegrity() async {
  let tortilla = Tortilla(diameter: .large)
  ...
  let attachment = XCTAttachment(
    archivableObject: tortilla
  )
  self.add(attachment)
}
```

--------------------------------

### Get System Time on Classic OS

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/Porting.md

Retrieves the current system time on platforms with the 'Classic' OS identifier. It calculates the time difference from a specific epoch and returns it as a TimeValue. This implementation is conditional and relies on the GetDateTime function.

```swift
filefileprivate(set) var wall: TimeValue = {
 #if !SWT_NO_TIMESPEC
   // ...
 #elseif os(Classic)
   var seconds = CUnsignedLong(0)
   GetDateTime(&seconds)
   seconds -= 2_082_844_800 // seconds between epochs
   return TimeValue((seconds: Int64(seconds), attoseconds: 0))
 #else
 #warning("Platform-specific implementation missing: UTC time unavailable (no timespec)")
 #endif
 }
```

--------------------------------

### Invalid Test Suite Due to Availability Attribute in Swift

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/OrganizingTests.md

This example shows that a test suite type cannot be annotated with the `@available` attribute, as test suites must always be available.

```Swift
@Suite struct FoodTruckTests { ... } // ✅ OK: The type is always available.

@available(macOS 11.0, *) // ❌ ERROR: The suite type must always be available.
@Suite struct CashRegisterTests { ... }

@available(macOS 11.0, *) struct MenuItemTests { // ❌ ERROR: The suite type's
                                                 // containing type must always
                                                 // be available too.
  @Suite struct BurgerTests { ... }
}
```

--------------------------------

### Declare Test Functions: XCTest vs Swift Testing

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/MigratingFromXCTest.md

Demonstrates the syntax difference for declaring test functions. XCTest requires methods to be part of a class and start with 'test', while the Swift Testing library uses the `@Test` attribute on functions within structs or classes.

```swift
// Before (XCTest)
class FoodTruckTests: XCTestCase {
  func testEngineWorks() { ... }
  ...
}

// After (Swift Testing)
struct FoodTruckTests {
  @Test func engineWorks() { ... }
  ...
}
```

--------------------------------

### Swift Testing Value Attachment

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/MigratingFromXCTest.md

Demonstrates how to attach a value to a test result in Swift Testing using the `Attachment.record` method. The example shows attaching a `Tortilla` object (conforming to `Codable` and `Attachable`) to the test results.

```swift
// After
import Foundation

struct Tortilla: Codable, Attachable { /* ... */ }

@Test func tortillaIntegrity() async {
  let tortilla = Tortilla(diameter: .large)
  ...
  Attachment.record(tortilla)
}
```

--------------------------------

### Swift Macro Expansion for Type/Variable Name Ambiguity

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/ExpectationCapture.md

Shows an example where Swift Testing might append '.self' to a syntax node to resolve ambiguity between type and variable names. Users should report cases where this logic fails.

```swift
```swift
#expect(a.b == c) // a may not be expressible in isolation
```
```

--------------------------------

### Running Swift Tests

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

This command executes the Swift test suite in the current directory.

```bash
$> swift test
```

--------------------------------

### Fetch Swift Testing with CMake

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/CMake.md

Demonstrates how to include the Swift Testing library in a CMake project using FetchContent. It specifies the Git repository and tag for fetching the library.

```cmake
include(FetchContent)
FetchContent_Declare(SwiftTesting
  GIT_REPOSITORY https://github.com/swiftlang/swift-testing.git
  GIT_TAG main)
FetchContent_MakeAvailable(SwiftTesting)
```

--------------------------------

### Swift: Create Bug Trait with Unique Identifier

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/BugIdentifiers.md

Shows how to create a Bug trait instance using a unique identifier. The library does not enforce a specific format for identifiers, but recognizes identifiers starting with "FB" as belonging to Apple Feedback Assistant. Integers can also be passed directly.

```swift
Trait.bug(id: 12345)
Trait.bug(id: "12345")
Trait.bug(id: "FB12345")
```

--------------------------------

### Configure CMake Project

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Configures the Swift Testing project to be built using CMake with the Ninja generator. This command sets up the build system and output directory.

```cmake
cmake -G Ninja -B build
```

--------------------------------

### Swift Entry Point for Test Runner

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/CMake.md

Provides the '@main' entry point for a Swift test executable. It defines the expected ABI signature for the entry point function and uses it to run tests, exiting with success or failure.

```swift
typealias EntryPoint = @convention(thin) @Sendable (_ configurationJSON: UnsafeRawBufferPointer?, _ recordHandler: @escaping @Sendable (_ recordJSON: UnsafeRawBufferPointer) -> Void) async throws -> Bool

@_extern(c, "swt_abiv0_getEntryPoint")
func swt_abiv0_getEntryPoint() -> UnsafeRawPointer

@main struct Runner {
    static func main() async throws {
        nonisolated(unsafe) let configurationJSON: UnsafeRawBufferPointer? = nil
        let recordHandler: @Sendable (UnsafeRawBufferPointer) -> Void = { _ in }

        let entryPoint = unsafeBitCast(swt_abiv0_getEntryPoint(), to: EntryPoint.self)

        if try await entryPoint(configurationJSON, recordHandler) {
            exit(EXIT_SUCCESS)
        } else {
            exit(EXIT_FAILURE)
        }
    }
}
```

--------------------------------

### Basic Test with Expectation

Source: https://github.com/swiftlang/swift-testing/blob/main/README.md

Demonstrates a simple test case using the `@Test` macro and the `#expect` macro for asserting conditions. It shows how to declare a test function and perform a basic equality check.

```swift
import Testing

@Test func helloWorld() {
  let greeting = "Hello, world!"
  #expect(greeting == "Hello") // Expectation failed: (greeting → "Hello, world!") == "Hello"
}
```

--------------------------------

### Build Swift Project

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Builds the Swift Testing project using the Swift Package Manager. This command compiles the project's source code and dependencies.

```bash
swift build
```

--------------------------------

### Test Swift Project

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Runs the test suite for the Swift Testing project using the Swift Package Manager. This command executes all defined tests to verify the project's functionality.

```bash
swift test
```

--------------------------------

### List Tests in WebAssembly Executable

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/WASI.md

Lists all available tests within the WebAssembly executable using Wasmtime. This is useful for inspecting the test suite before execution. Replace `{YOURPACKAGE}` with your package's name.

```sh
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm list --testing-library swift-testing
```

--------------------------------

### Build Swift Tests for WebAssembly

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/WASI.md

Builds Swift tests specifically for the WebAssembly target using the `wasm32-unknown-wasi` SDK. This command prepares the test executables for execution in a WASI environment.

```sh
swift build --swift-sdk wasm32-unknown-wasi --build-tests
```

--------------------------------

### Run WebAssembly Tests with Wasmtime

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/WASI.md

Executes the compiled WebAssembly test executable using Wasmtime. It requires the path to the test executable and specifies the testing library to use. Replace `{YOURPACKAGE}` with your package's name.

```sh
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm --testing-library swift-testing
```

--------------------------------

### Test Suite Instance vs. Static Methods

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/OrganizingTests.md

Illustrates how the testing library handles instance methods within a `@Suite` type by creating an instance and calling the method. It also shows the equivalent static method call, highlighting that each instance method is called on a distinct instance of the suite type.

```swift
@Suite struct FoodTruckTests {
  @Test func foodTruckExists() { ... }
}

// Equivalent to:
@Suite struct FoodTruckTests {
  func foodTruckExists() { ... }

  @Test static func staticFoodTruckExists() {
    let instance = FoodTruckTests()
    instance.foodTruckExists()
  }
}
```

--------------------------------

### Build Project with CMake

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Performs the build process for the Swift Testing project using CMake and the Ninja generator. This command compiles the project based on the configuration.

```cmake
cmake --build build
```

--------------------------------

### Run Swift Testing Suite via Docker

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

Executes the Swift Testing suite within a Docker container. Mounts the current directory into the container and sets the working directory. Skips update checks.

```bash
$> docker run -v "$(pwd)":/swift-testing -w /swift-testing swift-testing swift test --skip-update
```

--------------------------------

### Swift: API Documentation for Testing Expectations

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/Expectations.md

Provides an overview of key types and functions used for creating and managing expectations in Swift tests. This includes macros for asserting conditions, checking for thrown errors, and confirming asynchronous events.

```APIDOC
Swift Testing Library API Overview:

Core Expectation Macros:

- expect(_:_:sourceLocation:)
  - Validates an expression against an expected value. Continues test execution on failure.
  - Parameters:
    - expression: The expression to evaluate.
    - expected: The expected value.
    - sourceLocation: The source location of the assertion.
  - Example:
    #expect(result == expectedValue)

- require(_:_:sourceLocation:)
  - Validates a critical expression. Stops test execution on failure by throwing `ExpectationFailedError`.
  - Parameters:
    - expression: The expression to evaluate.
    - expected: The expected value.
    - sourceLocation: The source location of the assertion.
  - Example:
    let value = try #require(optionalValue)

Error Handling Macros:

- expect(throws:_:sourceLocation:performing:)
- expect(throws:_:sourceLocation:performing:)
- expect(_:sourceLocation:performing:throws:)
  - Asserts that a closure throws a specific error or any error.
  - Parameters:
    - error: The expected error type or instance.
    - sourceLocation: The source location of the assertion.
    - performing: The closure to execute.
  - Example:
    #expect(throws: MyError.self, performing: { try performAction() })

- require(throws:_:sourceLocation:performing:)
- require(throws:_:sourceLocation:performing:)
- require(_:sourceLocation:performing:throws:)
  - Asserts that a closure throws a specific error or any error, stopping the test on failure.
  - Parameters:
    - error: The expected error type or instance.
    - sourceLocation: The source location of the assertion.
    - performing: The closure to execute.
  - Example:
    try #require(throws: MyError.self, performing: { try performCriticalAction() })

Asynchronous Event Confirmation:

- confirmation(_:expectedCount:isolation:sourceLocation:_:)
- confirmation(_:expectedCount:isolation:sourceLocation:_:)
  - Confirms the occurrence of asynchronous events, optionally with an expected count.
  - Parameters:
    - description: A description of the event.
    - expectedCount: The number of times the event is expected.
    - isolation: The actor isolation context for the confirmation.
    - sourceLocation: The source location of the assertion.
    - closure: The closure to execute that triggers the event.
  - Example:
    let confirmation = confirmation("data loaded") { await loadData() }

Exit Status Testing:

- expect(processExitsWith:observing:_:sourceLocation:performing:)
- require(processExitsWith:observing:_:sourceLocation:performing:)
  - Asserts or requires that a process exits with a specific status code.
  - Parameters:
    - expectedExitStatus: The expected exit status.
    - observing: A closure to observe the process output.
    - sourceLocation: The source location of the assertion.
    - performing: The closure to execute that starts the process.
  - Example:
    #expect(processExitsWith: 0, performing: { launchProcess() })

Key Types:

- Confirmation: Manages the state and verification of asynchronous events.
- Expectation: Represents a single assertion within a test.
- ExpectationFailedError: The error thrown when a `#require` assertion fails.
- CustomTestStringConvertible: Protocol for custom string representations in test failures.
- SourceLocation: Represents the file and line number of an assertion.
```

--------------------------------

### Define Swift Static Library

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/_TestDiscovery/CMakeLists.txt

Defines a static library target named '_TestDiscovery' and lists its associated Swift source files. This is a core step in building the library.

```CMake
add_library(_TestDiscovery STATIC
  Additions/WinSDKAdditions.swift
  DiscoverableAsTestContent.swift
  SectionBounds.swift
  TestContentKind.swift
  TestContentRecord.swift)
```

--------------------------------

### Parameterized Test with Arguments

Source: https://github.com/swiftlang/swift-testing/blob/main/README.md

Demonstrates parameterized testing, allowing the same test logic to be executed with a sequence of different inputs. This reduces code duplication and improves test coverage by iterating over provided arguments.

```swift
import Testing

@Test("Continents mentioned in videos", arguments: [
    "A Beach",
    "By the Lake",
    "Camping in the Woods"
])
func mentionedContinents(videoName: String) async throws {
    let videoLibrary = try await VideoLibrary()
    let video = try #require(await videoLibrary.video(named: videoName))
    #expect(video.mentionedContinents.count <= 3)
}
```

--------------------------------

### Test with Conditional Behavior and Require

Source: https://github.com/swiftlang/swift-testing/blob/main/README.md

Illustrates how to apply traits to tests, such as conditional enabling based on application features. It also shows the use of the `#require` macro to unwrap optional values or throw errors, ensuring necessary conditions are met before proceeding.

```swift
import Testing

@Test(.enabled(if: AppFeatures.isCommentingEnabled))
func videoCommenting() async throws {
    let video = try #require(await videoLibrary.video(named: "A Beach"))
    #expect(video.comments.contains("So picturesque!"))
}
```

--------------------------------

### Simple Expression Capture with #expect

Source: https://github.com/swiftlang/swift-testing/blob/main/Documentation/ExpectationCapture.md

Demonstrates how Swift Testing's #expect() macro captures simple expressions, allowing for detailed runtime diagnostics by examining the expression's Abstract Syntax Tree (AST).

```swift
#expect(f() < g())
```

--------------------------------

### Navigating to Swift Testing Directory

Source: https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md

This command changes the current directory to '/swift-testing' inside the Docker container.

```bash
$> cd /swift-testing
```

--------------------------------

### Test with Descriptive Name and Tags

Source: https://github.com/swiftlang/swift-testing/blob/main/README.md

Shows how to provide a descriptive string name for a test and apply tags for flexible organization and filtering. This helps in managing tests with common characteristics across a suite.

```swift
import Testing

@Test("Check video metadata",
      .tags(.metadata))
func videoMetadata() {
    let video = Video(fileName: "By the Lake.mov")
    let expectedMetadata = Metadata(duration: .seconds(90))
    #expect(video.metadata == expectedMetadata)
}
```

--------------------------------

### Importing the Testing Module

Source: https://github.com/swiftlang/swift-testing/blob/main/README.md

Shows the basic import statement required to use the Swift Testing package in your Swift code. This is the foundational step for leveraging any of its testing functionalities.

```swift
import Testing
```

--------------------------------

### Swift: Parameterized Tests with Multiple Collections

Source: https://github.com/swiftlang/swift-testing/blob/main/Sources/Testing/Testing.docc/ParameterizedTesting.md

Demonstrates how to use multiple collections of arguments for parameterized tests in Swift. It shows the default Cartesian product behavior and how to use `zip()` to combine collections for a more controlled test execution.

```swift
@Test("Can make large orders", arguments: Food.allCases, 1 ... 100)
func makeLargeOrder(of food: Food, count: Int) async throws {
  let foodTruck = FoodTruck(selling: food)
  #expect(await foodTruck.cook(food, quantity: count))
}
```

```swift
@Test("Can make large orders", arguments: zip(Food.allCases, 1 ... 100))
func makeLargeOrder(of food: Food, count: Int) async throws {
  let foodTruck = FoodTruck(selling: food)
  #expect(await foodTruck.cook(food, quantity: count))
}
```