swift-corelibs-xctest

If you are using XCTest within a SwiftPM package, place your unit test files in the Tests subdirectory of your package. You can build and run the entire test suite using the standard Swift command.

To run tests, execute:

swift test

The xctest_checker is a Python-based tool used by the swift-corelibs-xctest functional tests (specifically when the {xctest_checker} lit substitution is employed). To view detailed usage information and available command-line options, run the script with the -h flag from its directory.

./xctest_checker.py -h

The most reliable way to build XCTest is using the Swift build script. This requires that you have already built the Swift project and can successfully run utils/build-script -R.

To build XCTest and run its tests, run:

cd swift-corelibs-xctest
../swift/utils/build-script --preset corelibs-xctest

You can run the internal unit tests for the xctest_checker tool using the standard Python unittest discovery mechanism from within the tool's directory.

python -m unittest discover

When not using SwiftPM, you must create a custom executable that links against libXCTest.so. In your main.swift file, you must invoke the XCTMain function. Pass an array of tests to XCTMain, where each test is wrapped by the testCase helper function.

XCTMain does not return; it will cause the executable to exit with code 0 for success or 1 for failure.

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

To use Xcode for browsing the source code, open XCTest.xcworkspace.

• Build Scheme: SwiftXCTest
• Test Scheme: SwiftXCTestFunctionalTests

Warning: You must use an Xcode toolchain with an extremely recent version of Swift to build successfully. If the standard toolchains are insufficient, you may need to download development snapshots or build your own toolchain using the utils/build-toolchain script in the Swift repository.

You can use CMake and Docker to build the project. This method assumes you have cloned the entire Swift project into a folder named swift-project located one level above your current directory.

1. Build the Docker image:

docker build -t swift-corelibs-xctest-docker:latest .

2. Run the container to build and test:

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/"

When running a standalone XCTest executable, you can use specific arguments to filter or inspect tests:

• Select specific tests: Provide the test name or class name to run a single method, an entire class, or a comma-separated list of methods.

  • ./FooTests Tests.FooTestCase/testFoo (Single method)
  • ./FooTests Tests.FooTestCase (All tests in class)
  • ./FooTests Tests.FooTestCase/testFoo,Tests.FooTestCase/testBar (Multiple specific methods)

• List tests:

  • --list-tests: Prints a list of all available tests.
  • --dump-tests-json: Outputs the test hierarchy in JSON format.

$ ./FooTests --list-tests
$ ./FooTests --dump-tests-json