Swift XCTest

https://github.com/swiftlang/swift-corelibs-xctest
Admin
XCTest is a Swift library providing a common framework for writing unit tests across Swift packages...
Tokens:2,563
Snippets:31
Trust Score:9.4
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install XCTest Targets and Modules

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

Installs the XCTest target artifacts (libraries, executables) and Swift modules to their designated installation directories. This prepares the built components for deployment or use in other projects.

```cmake
install(TARGETS XCTest
  ARCHIVE DESTINATION ${XCTest_INSTALL_LIBDIR}
  LIBRARY DESTINATION ${XCTest_INSTALL_LIBDIR}
  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/swift/XCTest.swiftdoc
  DESTINATION ${XCTest_INSTALL_SWIFTMODULEDIR}/XCTest.swiftmodule
  RENAME ${XCTest_MODULE_TRIPLE}.swiftdoc)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/swift/XCTest.swiftmodule
  DESTINATION ${XCTest_INSTALL_SWIFTMODULEDIR}/XCTest.swiftmodule
  RENAME ${XCTest_MODULE_TRIPLE}.swiftmodule)
```

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

### View xctest_checker Help

Source: https://github.com/swiftlang/swift-corelibs-xctest/blob/main/Tests/Functional/xctest_checker/README.md

Execute this command to display the help message and available options for the xctest_checker tool.

```sh
./xctest_checker.py -h
```

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

### Build XCTest with Swift Build Script

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

Build XCTest and run its tests using the Swift project's build script. Ensure you can build the main Swift project first.

```bash
$ cd swift-corelibs-xctest
$ ../swift/utils/build-script --preset corelibs-xctest
```

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

### Build XCTest with CMake and Docker

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

Recommended method for building and testing XCTest using CMake and Docker. This involves building a Docker image and then running the build script within a container.

```bash
$ docker build -t swift-corelibs-xctest-docker:latest .
# This assumes you've cloned the entire Swift project earlier into a folder named "swift-project"
$ docker run -it -v ../../swift-project:/swift-project -w /swift-project/swift-corelibs-xctest swift-corelibs-xctest-docker \
      sh -c "cmake -G Ninja -B .build && cmake --build .build && \
      ./build_script.py test \
      --swiftc=/usr/bin/swiftc \
      --foundation-build-dir .build/ \
      .build/"
```

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

### Initialize XCTest with Test Cases

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

Use XCTMain to run tests from XCTestCase subclasses when XCTest is used standalone. This function takes an array of test cases wrapped by the testCase helper function and does not return.

```swift
XCTMain([
    testCase(TestNSString.allTests),
    testCase(TestNSArray.allTests),
    testCase(TestNSDictionary.allTests),
])
```

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

### Select Specific Tests for Execution

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

When running XCTest from the command line, you can specify individual test methods, entire test cases, or multiple methods to execute.

```bash
$ ./FooTests Tests.FooTestCase/testFoo                            # Run a single test method
$ ./FooTests Tests.FooTestCase                                    # Run all the tests in FooTestCase
$ ./FooTests Tests.FooTestCase/testFoo,Tests.FooTestCase/testBar  # Run multiple test methods
```

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

### Find SwiftTesting Package

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

Finds the SwiftTesting package configuration and macros. This is a prerequisite for enabling testing features.

```cmake
find_package(SwiftTesting CONFIG)
find_package(SwiftTestingMacros CONFIG)
```

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

### Run xctest_checker Unit Tests

Source: https://github.com/swiftlang/swift-corelibs-xctest/blob/main/Tests/Functional/xctest_checker/README.md

Use this command to discover and run the unit tests for the xctest_checker tool using Python's unittest module.

```python
python -m unittest discover
```

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

### Update Swift Checkout

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

Before contributing, ensure your Swift development environment is up-to-date by running the update-checkout script. This is crucial for compatibility with the latest Swift commits.

```bash
$ ../swift/utils/update-checkout
```

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

### List Available Tests

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

Use the --list-tests argument to display all available tests in the test executable without running them.

```bash
$ ./FooTests --list-tests
Listing 4 tests in FooTests.xctest:

Tests.FooTestCase/testFoo
Tests.FooTestCase/testBar
Tests.BarTestCase/test123
```

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

### Enable Testing and Find LLVM

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

Enables testing, finds the LLVM configuration, and includes LLVM's CMake modules. This is required for running tests that depend on LLVM tools.

```cmake
if(ENABLE_TESTING)
  enable_testing()

  enable_language(C)
  find_package(LLVM CONFIG)
  if(LLVM_FOUND)
    message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
    message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")

    include(${LLVM_DIR}/LLVMConfig.cmake)

    list(APPEND CMAKE_MODULE_PATH ${LLVM_DIR})
    include(AddLLVM)
  elseif(NOT DEFINED LLVM_MAIN_SRC_DIR OR NOT EXISTS ${LLVM_MAIN_SRC_DIR})
    message(SEND_ERROR "LLVM not found and LLVM_MAIN_SRC_DIR not defined - required for testing")
  endif()

  if(EXISTS ${LLVM_MAIN_SRC_DIR}/utils/lit/lit.py)
    set(LIT_COMMAND "${LLVM_MAIN_SRC_DIR}/utils/lit/lit.py"
        CACHE STRING "command used to spawn llvm-lit")
  elseif(LLVM_DEFAULT_EXTERNAL_LIT)
    set(LIT_COMMAND "${LLVM_DEFAULT_EXTERNAL_LIT}"
        CACHE STRING "command used to spawn llvm-lit")
  else()
    find_program(LIT_COMMAND NAMES llvm-lit lit.py lit)
  endif()

  find_package(Python3 COMPONENTS Interpreter REQUIRED)
```

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

### Configure XCTest Target for Interoperability

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

Links the XCTest target with _TestingInterop and defines XCT_BUILD_WITH_INTEROP when SwiftTesting is found. This enables build-time interoperability features.

```cmake
if(SwiftTesting_FOUND)
  target_link_libraries(XCTest PRIVATE
    _TestingInterop)
  target_compile_definitions(XCTest PRIVATE
    XCT_BUILD_WITH_INTEROP)
endif()
```

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

### Configure XCTest Export File

Source: https://github.com/swiftlang/swift-corelibs-xctest/blob/main/cmake/modules/CMakeLists.txt

Configures the XCTest export file using CMake. This script sets the path for the export file and then configures it from a template.

```cmake
set(XCTest_EXPORTS_FILE ${CMAKE_CURRENT_BINARY_DIR}/XCTestExports.cmake)
configure_file(XCTestConfig.cmake.in
  ${CMAKE_CURRENT_BINARY_DIR}/XCTestConfig.cmake)
```

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

### Link Libraries for Non-Darwin Systems

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

Links the XCTest target with 'dispatch' and 'Foundation' libraries on systems that are not Darwin. Also applies a linker option to prevent rpath for non-Windows systems.

```cmake
if(NOT CMAKE_SYSTEM_NAME STREQUAL Darwin)
  target_link_libraries(XCTest PRIVATE
    dispatch
    Foundation)
  if(NOT CMAKE_SYSTEM_NAME STREQUAL Windows)
    target_link_options(XCTest PRIVATE "SHELL:-no-toolchain-stdlib-rpath")
  endif()
endif()
```

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

### Dump Tests in JSON Format

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

The --dump-tests-json argument outputs a JSON representation of all tests, useful for external tooling or analysis.

```bash
$ ./FooTests --dump-tests-json
{"tests":[{"tests":[{"tests":[{"name":"testFoo"},{"name":"testBar"}],"name":"Tests.FooTestCase"},{"tests":[{"name":"test123"}],"name":"Tests.BarTestCase"}],"name":"Tests.xctest"}],"name":"All tests"}
```

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

### Add CMake Modules Subdirectory

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

Includes CMake modules from a subdirectory. This is a standard way to organize and reuse CMake code.

```cmake
add_subdirectory(cmake/modules)
```

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

### Set XCTest Target Properties

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

Sets Swift module directory and interface include directories for the XCTest target. This configures where Swift modules are located during the build.

```cmake
set_target_properties(XCTest PROPERTIES
  Swift_MODULE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/swift
  INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_CURRENT_BINARY_DIR}/swift)
```

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

### Add XCTest Functional Test Suite Target

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

Adds a custom target 'check-xctest' to run the XCTest functional test suite using 'lit.py'. It sets up necessary environment variables for the test execution.

```cmake
add_custom_target(check-xctest
                    COMMAND
                    ${CMAKE_COMMAND} -E env
                      BUILT_PRODUCTS_DIR=${CMAKE_BINARY_DIR}
                      FOUNDATION_BUILT_PRODUCTS_DIR=${XCTEST_PATH_TO_FOUNDATION_BUILD}
                      LIBDISPATCH_SRC_DIR=${XCTEST_PATH_TO_LIBDISPATCH_SOURCE}
                      LIBDISPATCH_BUILD_DIR=${XCTEST_PATH_TO_LIBDISPATCH_BUILD}
                      LIBDISPATCH_OVERLAY_DIR=${XCTEST_PATH_TO_LIBDISPATCH_BUILD}/src/swift
                      SWIFT_TESTING_BUILD_DIR=${SwiftTesting_BUILD_DIR}
                      SWIFT_TESTING_MACRO_BUILD_DIR=${SwiftTesting_MACRO_DIR}
                      SWIFT_EXEC=${CMAKE_Swift_COMPILER}
                      $<TARGET_FILE:Python3::Interpreter> ${LIT_COMMAND} -sv ${CMAKE_SOURCE_DIR}/Tests/Functional
                    COMMENT
                      "Running XCTest functional test suite"
                    DEPENDS
                      XCTest
                    USES_TERMINAL)
endif()
```

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

### Conditional Foundation Framework Definition

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

Defines USE_FOUNDATION_FRAMEWORK for the XCTest target if the USE_FOUNDATION_FRAMEWORK variable is set. This is used for conditional compilation.

```cmake
if(USE_FOUNDATION_FRAMEWORK)
  target_compile_definitions(XCTest PRIVATE
    USE_FOUNDATION_FRAMEWORK)
endif()
```

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

### Conditional Linker Option for Build ID

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

Adds a linker option to use SHA1 for build ID if the linker supports it. This is a build-time optimization for identifying build artifacts.

```cmake
if(LINKER_SUPPORTS_BUILD_ID)
  target_link_options(XCTest PRIVATE "LINKER:--build-id=sha1")
endif()
```

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

### Export XCTest Target

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

Sets a global property to export the XCTest target. This makes the target available for other CMake projects that might depend on it.

```cmake
set_property(GLOBAL APPEND PROPERTY XCTest_EXPORTS XCTest)
```

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

### Export XCTest Targets

Source: https://github.com/swiftlang/swift-corelibs-xctest/blob/main/cmake/modules/CMakeLists.txt

Exports the specified XCTest targets to a file. This is used to make targets available for other CMake projects.

```cmake
get_property(XCTest_EXPORTS GLOBAL PROPERTY XCTest_EXPORTS)
export(TARGETS ${XCTest_EXPORTS} FILE ${XCTest_EXPORTS_FILE})
```
Tokens:
Raw