1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
# Getting started
<!--
This source file is part of the Swift.org open source project
Copyright (c) 2023 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See https://swift.org/LICENSE.txt for license information
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
-->
<!-- NOTE: The voice of this document is directed at the second person ("you")
because it provides instructions the reader must follow directly. -->
Start running tests in a new or existing XCTest-based test target.
## Overview
The testing library has experimental integration with Swift Package Manager's
`swift test` command, and integrates with Xcode 16 Beta and Visual Studio Code
(VS Code). These tools can be used to write and run tests alongside, or in place
of, tests written using XCTest. This document describes how to start using the
testing library to write and run tests.
To learn how to contribute to Swift Testing, see
[Contributing to Swift Testing](https://github.com/swiftlang/swift-testing/blob/main/CONTRIBUTING.md).
### Downloading a development toolchain
A recent **6.0 development snapshot** toolchain is required to use all of the
features of the Swift Testing. Visit [swift.org](http://swift.org/install)
to download and install a toolchain from the section titled **release/6.0**
under **Development Snapshots** on the page for your platform.
Be aware that development snapshot toolchains aren't intended for day-to-day
development and may contain defects that affect the programs built with them.
#### Swift 5.10 or earlier
Swift Testing doesn't support Swift 5.10 or earlier toolchains. You can use a
Swift 6.0 development snapshot toolchain to write tests or validate code which
uses the Swift 5 language mode, however.
### Adding the testing library as a dependency
- Note: When using Xcode 16 Beta, Swift Testing is available automatically and
the steps in this section aren't required.
In your package's `Package.swift` file, add the testing library as a package
dependency:
```swift
dependencies: [
.package(url: "https://github.com/swiftlang/swift-testing.git", branch: "main"),
],
```
Then, add the package's `Testing` product as a dependency of your test target:
```swift
.testTarget(
name: "FoodTruckTests",
dependencies: [
"FoodTruck",
.product(name: "Testing", package: "swift-testing"),
]
)
```
### Specifying minimum deployment targets
To ensure that your package's deployment targets meet or exceed those of the
testing library, you may also need to specify minimum deployment targets for
iOS, macOS, tvOS, visionOS, and/or watchOS, depending on which platforms your
package supports:
```swift
platforms: [
.iOS(.v13), .macOS(.v10_15), .macCatalyst(.v13), .tvOS(.v13), .visionOS(.v1), .watchOS(.v6)
],
```
### Writing tests
You can now add additional Swift source files to your package's test target that
contain those tests, written using the testing library, that you want to run
when you invoke `swift test` from the command line or click the
Product → Test menu item in Xcode.
### Configuring the environment
#### Configuring the command-line
When running macOS, the system will use the Swift toolchain included with Xcode
by default. To instruct the system to use the development toolchain you just
installed, enter the following command to configure the current command-line
session:
```sh
export TOOLCHAINS=swift
```
#### Configuring Xcode
In Xcode, open the **Xcode** menu, then the Toolchains submenu, and select the
development toolchain from the list of toolchains presented to you — it will
be presented with a name such as "Swift Development Toolchain 2023-01-01 (a)".
#### Configuring VS Code
Follow the instructions under
[Install the Extension](https://www.swift.org/documentation/articles/getting-started-with-vscode-swift.html#install-the-extension)
of the
[Getting Started with Swift in VS Code](https://www.swift.org/documentation/articles/getting-started-with-vscode-swift.html)
guide.
### Running tests
#### Running from the command line
Navigate to the directory containing your package and run the following command:
```sh
swift test
```
Swift Package Manager will build and run a test target that uses the testing
library as well as a separate target that uses XCTest. To only run tests written
using the testing library, pass `--disable-xctest` as an additional argument to
the `swift test` command.
- Note: If your package does not explicitly list the testing library as a
dependency, pass `--enable-experimental-swift-testing` to the `swift test`
command to ensure your tests are run.
#### Running tests in Xcode 16 Beta
Click the Product → Test menu item, or press ⌘+U, to run Swift Testing tests
using Xcode 16 Beta.
#### Running tests in VS Code
See the [Test Explorer](https://www.swift.org/documentation/articles/getting-started-with-vscode-swift.html#test-explorer)
section of
[Getting Started with Swift in VS Code](https://www.swift.org/documentation/articles/getting-started-with-vscode-swift.html).
#### Running tests for WebAssembly
To run tests for WebAssembly, install a Swift SDK for WebAssembly by following
[these instructions](https://book.swiftwasm.org/getting-started/setup-snapshot.html).
Because `swift test` doesn't know what WebAssembly environment you'd like to use
to run your tests, building tests and running them are two separate steps. To
build tests for WebAssembly, use the following command:
```sh
swift build --swift-sdk wasm32-unknown-wasi --build-tests
```
After building tests, you can run them using a [WASI](https://wasi.dev/)-compliant
WebAssembly runtime such as [Wasmtime](https://wasmtime.dev/) or
[WasmKit](https://github.com/swiftwasm/WasmKit). For example, to run tests using
Wasmtime, use the following command (replace `{YOURPACKAGE}` with your package's
name):
```sh
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm --testing-library swift-testing
```
Most WebAssembly runtimes forward trailing arguments to the WebAssembly program,
so you can pass command-line options of the testing library. For example, to list
all tests and filter them by name, use the following commands:
```sh
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm list --testing-library swift-testing
wasmtime .build/debug/{YOURPACKAGE}PackageTests.wasm --testing-library swift-testing --filter "FoodTruckTests.foodTruckExists"
```
|
