5 Commits

Author SHA1 Message Date
tomer doron bd260f76fe Update docs/testing.md
Co-authored-by: Konrad `ktoso` Malawski <ktoso@apple.com>
2021-05-15 03:09:10 -07:00
tomer doron e6336d8dc3 Update docs/testing.md
Co-authored-by: Konrad `ktoso` Malawski <ktoso@apple.com>
2021-05-15 03:09:04 -07:00
tomer doron f28da1e09e Update testing.md 2021-05-14 17:14:59 -07:00
tomer doron 2869ac6433 Update testing.md 2021-05-14 17:13:15 -07:00
tomer doron 295cd506ae update testing guide
motivation: adjust guide around `LinuxMain`

changes: explain when `LinuxMain` is required and when it is not
2021-05-14 16:54:23 -07:00
+9 -12
View File
@@ -6,27 +6,24 @@ SwiftPM is integrated with [XCTest, Apples unit test framework](https://devel
Like building on Linux, testing on Linux requires the use of Docker. For example:
`$ docker run -v "$PWD:/code" -w /code swift:5.3 swift test`
`$ docker run -v "$PWD:/code" -w /code swift:latest swift test`
The above command will run the tests using the latest Swift 5.3 Docker image, utilizing bind mounts to the sources on your file system.
The above command will run the tests using the latest Swift Docker image, utilizing bind mounts to the sources on your file system.
Swift supports architecture-specific code. By default, Foundation imports architecture-specific libraries like Darwin or Glibc. While developing on macOS, you may end up using APIs that are not available on Linux. Since you are most likely to deploy a cloud service on Linux, it is critical to test on Linux.
Another important detail about testing for Linux is the `Tests/LinuxMain.swift` file. For versions prior to Swift 5.1, This file provides SwiftPM an index of all the tests it needs to run on Linux.
A historically important detail about testing for Linux is the `Tests/LinuxMain.swift` file.
- For version Swift 5.1 and later, this file is no longer required, and testing with `--enable-test-discovery` seamlessly discovers the tests. This will be the default behvior in future releases of Swift. Until this is the default, it can be useful
to keep `Tests/LinuxMain.swift` around but with with the following code to remind you to use the flag:
`fatalError("Please use `swift test --enable-test-discovery` to run the tests instead")`
- For versions prior to Swift 5.1, it is critical to keep this file up-to-date as you add more unit tests. To regenerate this file, run `swift test --generate-linuxmain` after adding tests. It is also a good idea to include this command as part of your continuous integration setup.
- In Swift versions 5.4 and newer tests are automaticlaly discovered on all platforms, no special file or flag needed.
- In Swift versions >= 5.1 < 5.4, tests can be automaticlaly discovered on Linux using `swift test --enable-test-discovery` flag.
- In Swift versions older than 5.1 the `Tests/LinuxMain.swift` file provides SwiftPM an index of all the tests it needs to run on Linux and it is critical to keep this file up-to-date as you add more unit tests. To regenerate this file, run `swift test --generate-linuxmain` after adding tests. It is also a good idea to include this command as part of your continuous integration setup.
### Testing for production
- For versions Swift 5.1 and later, always test with `--enable-test-discovery` to avoid forgetting tests on Linux.
- Generally, whilst testing, you may want to build using `swift build --sanitize=thread`. The binary will run slower and is not suitable for production, but you'll see many many threading issues before you deploy your software. Often threading issues are really hard to debug and reproduce and also cause random problems. TSan helps catch them early.
- For Swift versions between Swift 5.1 and 5.4, always test with `--enable-test-discovery` to avoid forgetting tests on Linux.
- Make use of the sanitizers. Before running code in production, do the following:
* Run your test suite with TSan (thread sanitizer): `swift test --sanitize=thread`
* Run your test suite with ASan (address sanitizer): `swift test --sanitize=address` and `swift test --sanitize=address -c release -Xswiftc -enable-testing`
- Generally, whilst testing, you may want to build using `swift build --sanitize=thread`. The binary will run slower and is not suitable for production, but you might be able to catch threading issues early - before you deploy your software. Often threading issues are really hard to debug and reproduce and also cause random problems. TSan helps catch them early.