/commands/swift/swift-test-filter
swift test --filter: run a single Swift test or test case
- tool
- Swift
- versions
- Swift 5.x – 6.x, Swift Testing: Swift 6+
- os
- macos, linux, windows
swift test --filter MyAppTests.ParserTests runs only the tests whose identifier matches the regular expression given to --filter. Identifiers have the form TestTarget.TestCase or TestTarget.TestCase/testMethod, so --filter MyAppTests.ParserTests/testEmptyInput runs a single test. swift test --list-tests prints the identifiers, and --skip excludes matches instead.
Examples
# list the identifiers that --filter matches
swift test --list-tests
# one test case (class or suite)
swift test --filter MyAppTests.ParserTests
# one test method
swift test --filter MyAppTests.ParserTests/testEmptyInput
# everything except the slow tests
swift test --skip PerformanceTests
# build in release, then run the selection in parallel
swift test -c release -Xswiftc -enable-testing --filter Parser --parallel--filter and --skip can be given more than once. SwiftPM builds the package and its test targets first, then runs only the selected tests. Swift Testing (@Test, Swift 6 and later) and XCTest tests are both selected by these options.
Options
| Option | Effect |
|---|---|
| --filter REGEX | Run tests whose identifier matches (Target.Case or Target.Case/test) |
| --skip REGEX | Skip matching tests, for example --skip PerformanceTests |
| --list-tests | Print the test identifiers in specifier format |
| --parallel / --no-parallel | Run tests in parallel worker processes, or not |
| --num-workers N | Number of tests to execute in parallel |
| --enable-code-coverage | Collect coverage; --show-codecov-path prints where the JSON report is |
| --xunit-output FILE | Write an xUnit XML report for CI |
| --sanitize=thread / address | Run with the thread or address sanitizer |
| --skip-build | Run the already built tests without building |
Pitfalls
- Matching too much. The value is a regular expression:
--filter Parseralso runsParserIntegrationTests. Use the full identifier from--list-tests. - No tests matched. A misspelt filter builds everything and runs nothing; check the identifier with
--list-testsand remember it is case-sensitive. - Release mode.
swift test -c releasefails to compile@testable importunless you add-Xswiftc -enable-testing. - Linux differences. Code that compiles on macOS may use Foundation APIs that are missing on Linux; the Swift server guide recommends running the tests on Linux too, for example in a
swift:latestDocker image. - Go users. The Go equivalent is go test -run.
Confirm it worked
The summary at the end of the run reports how many tests were executed; it must match the number of tests you selected. With --list-tests | grep PATTERN you can preview the selection before running it.
FAQ
Is the --filter value an exact name?
No, it is a regular expression matched against the test identifiers. --filter Login runs every test whose identifier contains Login. Anchor or spell out the full Target.Case/test identifier to run exactly one test.
How do I see the exact names to filter on?
swift test --list-tests prints every test in the specifier format that --filter and --skip match against.
Do I need Tests/LinuxMain.swift for tests on Linux?
Not since Swift 5.4: tests are discovered automatically on all platforms. LinuxMain.swift and --generate-linuxmain were only needed by older toolchains.