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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
# Contributing to Swift Testing
There are many ways to contribute to this project. If you are making changes
that don't materially affect the user-facing semantics of Swift Testing, such
as fixing bugs or writing documentation, feel free to open a pull request (PR)
directly.
Larger changes that _do_ materially change the semantics of Swift Testing,
such as new APIs or modifications to existing APIs, must undergo community
discussion prior to being accepted.
> [!IMPORTANT]
> Since this package is currently experimental, a formal process for proposing
> and reviewing significant changes has not yet been established. Until that
> happens, please start a new discussion thread on the
> [Swift forums](https://forums.swift.org) about any such changes prior to
> submitting a PR.
To learn how to write tests using the testing library, rather than how to
contribute to the testing library itself, see
[Getting Started](https://github.com/swiftlang/swift-testing/tree/main/Sources/Testing/Testing.docc/TemporaryGettingStarted.md).
## Reporting issues
Issues are tracked using the testing library's
[GitHub Issue Tracker](https://github.com/swiftlang/swift-testing/issues).
Fill in the fields of the relevant template form offered on that page when
creating new issues. For bug report issues, please include a minimal example
which reproduces the issue. Where possible, attach the example as a Swift
package, or include a URL to the package hosted on GitHub or another public
hosting service.
## Setting up the development environment
First, clone the Swift Testing repository from
[https://github.com/swiftlang/swift-testing](https://github.com/swiftlang/swift-testing).
If you're preparing to make a contribution, you should fork the repository first
and clone the fork which will make opening PRs easier.
### Using Xcode (easiest)
1. Install the latest beta version of
[Xcode](https://developer.apple.com/xcode).
1. Open the `Package.swift` file from the cloned Swift Testing repository in
Xcode.
1. Select the `swift-testing-Package` scheme (if not already selected) and the
"My Mac" run destination.
1. Use Xcode to inspect, edit, build, or test the code.
### Using the command line
If you are using macOS and have Xcode installed, you can use Swift from the
command line immediately.
If you aren't using macOS or do not have Xcode installed, you need to download
and install a toolchain.
#### Installing a toolchain
1. Download a toolchain. A recent **6.0 development snapshot** toolchain is
required to build the testing library. Visit
[swift.org](http://swift.org/install) and download the most recent 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.
1. Install the toolchain and confirm it can be located successfully:
**macOS with Xcode installed**:
```bash
$> export TOOLCHAINS=swift
$> xcrun --find swift
/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin/swift
```
**Non-macOS or macOS without Xcode**:
```bash
$> export PATH=/path/to/swift-toolchain/usr/bin:"${PATH}"
$> which swift
/path/to/swift-toolchain/usr/bin/swift
```
## Local development
With a Swift toolchain installed and the Swift Testing repository cloned, you
are ready to make changes and test them locally.
### Building
```bash
$> swift build
```
### Testing
```bash
$> swift test
```
<!-- FIXME: Uncomment this once the the `swift test` command support running
specific Swift Testing tests.
To learn how to run only specific tests or other testing options, run `swift
test --help` to view the usage documentation.
-->
## Using Docker on macOS to test for Linux
1. Install [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop).
1. Run the following command from the root of this repository to build the
Docker image:
```bash
$> docker build -t swift-testing:latest .
```
1. Run the following command to run the test suite:
```bash
$> docker run -v "$(pwd)":/swift-testing -w /swift-testing swift-testing swift test --skip-update
```
1. To interactively run the test suite or do other development, first log into
the container with:
```bash
$> docker run -i -t -v "$(pwd)":/swift-testing swift-testing /bin/bash
```
And then run `swift test` or other commands within the container:
```bash
$> cd /swift-testing
$> swift test
```
## Creating Pull Requests (PRs)
1. Fork [https://github.com/swiftlang/swift-testing](https://github.com/swiftlang/swift-testing).
1. Clone a working copy of your fork.
1. Create a new branch.
1. Make your code changes.
1. Commit your changes. Include a description of the changes in the commit
message, followed by the GitHub Issue ID or Apple Radar link if there is one.
1. Push your changes to your fork.
1. Create a PR from the branch on your fork targeting the `main` branch of the
original repository.
1. Follow the PR template to provide information about the motivation and
details of the changes.
Reviewers will be automatically added to the PR once it is created. The PR will
be merged by the maintainers after it passes continuous integration (CI) testing
and receives approval from one or more reviewers. Merge timing may be impacted
by release schedule considerations.
By submitting a PR, you represent that you have the right to license your
contribution to Apple and the community, and agree by submitting the patch that
your contributions are licensed under the
[Swift license](https://swift.org/LICENSE.txt).
## Continuous integration
Swift Testing uses the [`swift-ci`](https://ci.swift.org/) infrastructure for
its continuous integration (CI) testing. The bots can be triggered on PRs if you
have commit access. Otherwise, ask one of the code owners to trigger them for
you.
To request CI, add a comment in the PR containing:
```
@swift-ci test
```
## Code style
Code should use two spaces for indentation. Block comments including markup
should be limited to 80 columns.
Refer to the testing library's
[documentation style guide](Documentation/StyleGuide.md) for more information.
## Community and support
To connect with the Swift community:
* Use the [Swift Forums](https://forums.swift.org)
* Contact the [code owners](CODEOWNERS)
## Additional resources
* [Swift.org Contributing page](https://swift.org/contributing/)
* [License](https://swift.org/LICENSE.txt)
* [Code of Conduct](https://swift.org/community/#code-of-conduct)
|
