Skip to content

Commit d38c66c

Browse files
authored
Update Getting Started docs to use Swift main branch features (#130)
* Update Getting Started docs to use Swift main branch features We now have functional support for swift-testing in Swift Package Manager (as of swiftlang/swift-package-manager#7047). We should update our documentation: - Point developers to the main branch instead of 5.10 again; - Show developers how to invoke `swift test` in a way that triggers swift-testing; and - Show developers how to use `XCTestScaffold` _only_ when using an older toolchain (with the appropriate caveats and nuances emphasized.) Resolves #126.
1 parent 9e105df commit d38c66c

File tree

2 files changed

+48
-50
lines changed

2 files changed

+48
-50
lines changed

CONTRIBUTING.md

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -59,23 +59,11 @@ and install a toolchain.
5959

6060
#### Installing a toolchain
6161

62-
<!--
63-
- Bug: A compiler bug in the Swift main branch is temporarily preventing its
64-
use with the testing library. ([swift-#69096](https://github.com/apple/swift/issues/69096))
65-
-->
66-
67-
<!--
6862
1. Download a toolchain. A recent **development snapshot** toolchain is required
6963
to build the testing library. Visit
7064
[swift.org](https://www.swift.org/download/#trunk-development-main) and
7165
download the most recent toolchain from the section titled
7266
**Snapshots — Trunk Development (main)**.
73-
-->
74-
75-
1. A recent **Swift 5.10 development snapshot** toolchain is required to build
76-
the testing library. Visit [swift.org](https://www.swift.org/download/#swift-510-development)
77-
to download and install a toolchain from the section titled
78-
**Snapshots — Swift 5.10 Development**.
7967

8068
Be aware that development snapshot toolchains are not intended for day-to-day
8169
development and may contain defects that affect the programs built with them.

Sources/Testing/Testing.docc/TemporaryGettingStarted.md

Lines changed: 48 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -17,33 +17,20 @@ Start running tests in a new or existing XCTest-based test target.
1717

1818
## Overview
1919

20-
The testing library is not (yet) integrated into Swift Package Manager, but a
21-
temporary mechanism is provided for developers who want to start using it with
22-
their Swift packages.
23-
24-
- Warning: This functionality is provided temporarily to aid in integrating the
25-
testing library with existing tools such as Swift Package Manager. It will be
26-
removed in a future release.
20+
The testing library has experimental integration with Swift Package Manager's
21+
`swift test` command and can be used to write and run tests alongside, or in
22+
place of, tests written using XCTest. This document describes how to start using
23+
the testing library to write and run tests.
2724

2825
To learn how to contribute to the testing library itself, see
2926
[Contributing to `swift-testing`](https://github.com/apple/swift-testing/blob/main/CONTRIBUTING.md).
3027

3128
### Downloading a development toolchain
3229

33-
A recent **Swift 5.10 development snapshot** toolchain is required to use the
34-
testing library. Visit [swift.org](https://www.swift.org/download/#swift-510-development)
35-
to download and install a toolchain from the section titled
36-
**Snapshots — Swift 5.10 Development**.
37-
38-
@Comment {
39-
- Bug: A compiler bug in the Swift main branch is temporarily preventing its
40-
use with the testing library. ([swift-#69096](https://github.com/apple/swift/issues/69096))
41-
}
42-
43-
<!--A recent **development snapshot** toolchain is required to use the testing
30+
A recent **development snapshot** toolchain is required to use the testing
4431
library. Visit [swift.org](https://www.swift.org/download/#trunk-development-main)
4532
to download and install a toolchain from the section titled
46-
**Snapshots — Trunk Development (main)**.-->
33+
**Snapshots — Trunk Development (main)**.
4734

4835
Be aware that development snapshot toolchains are not intended for day-to-day
4936
development and may contain defects that affect the programs built with them.
@@ -81,22 +68,6 @@ Then, add the testing library as a dependency of your existing test target:
8168
)
8269
```
8370

84-
### Adding test scaffolding
85-
86-
Add a new Swift source file to your package's test target named
87-
"Scaffolding.swift". Add the following to it:
88-
89-
```swift
90-
import XCTest
91-
import Testing
92-
93-
final class AllTests: XCTestCase {
94-
func testAll() async {
95-
await XCTestScaffold.runAllTests(hostedBy: self)
96-
}
97-
}
98-
```
99-
10071
You can now add additional Swift source files to your package's test target that
10172
contain those tests, written using the testing library, that you want to run
10273
when you invoke `swift test` from the command line or click the
@@ -119,18 +90,57 @@ export TOOLCHAINS=swift
11990

12091
In Xcode, open the **Xcode** menu, then the Toolchains submenu, and select the
12192
development toolchain from the list of toolchains presented to you&mdash;it will
122-
<!--be presented with a name such as "Swift Development Toolchain 2023-01-01 (a)".-->
123-
be presented with a name such as "Swift 5.10 Development Snapshot 2023-01-01 (a)".
93+
be presented with a name such as "Swift Development Toolchain 2023-01-01 (a)".
12494

12595
### Running tests
12696

97+
Navigate to the directory containing your package and run the following command:
98+
99+
```sh
100+
swift test --enable-experimental-swift-testing
101+
```
102+
103+
Swift Package Manager will build and run a test target that uses the testing
104+
library as well as a separate target that uses XCTest. To only run tests written
105+
using the testing library, pass `--disable-xctest` as an additional argument to
106+
the `swift test` command.
107+
108+
#### Swift 5.10
109+
110+
As of Swift 5.10, the testing library is not integrated into Swift Package
111+
Manager, but a temporary mechanism is provided for developers who want to start
112+
using it with their Swift packages and the Swift 5.10 toolchain.
113+
114+
- Warning: This functionality is provided temporarily to aid in integrating the
115+
testing library with existing tools such as Swift Package Manager. It will be
116+
removed in a future release.
117+
118+
To use the testing library with Swift 5.10, add a new Swift source
119+
file to your package's test target named "Scaffolding.swift". Add the following
120+
code to it:
121+
122+
```swift
123+
import XCTest
124+
import Testing
125+
126+
final class AllTests: XCTestCase {
127+
func testAll() async {
128+
await XCTestScaffold.runAllTests(hostedBy: self)
129+
}
130+
}
131+
```
132+
127133
Navigate to the directory containing your package, and either run `swift test`
128134
from the command line or click the Product&nbsp;&rarr;&nbsp;Test menu item in
129-
Xcode. You're done!
135+
Xcode.
130136

131137
Tests will run embedded in an `XCTestCase`-based test function named
132138
`testAll()`. If a test fails, `testAll()` will report the failure as its own.
133139

140+
#### Swift 5.9 or earlier
141+
142+
The testing library does not support Swift 5.9 or earlier.
143+
134144
## Topics
135145

136146
- ``XCTestScaffold``

0 commit comments

Comments
 (0)