Skip to content

Commit ab3a2d9

Browse files
briancroombriancroom
committed
Merge pull request #77 from modocache/readme-getting-started
[README] Encourage using the Swift build script
2 parents 440a092 + db60942 commit ab3a2d9

File tree

3 files changed

+95
-106
lines changed

3 files changed

+95
-106
lines changed

‎Documentation/Linux.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Additional Considerations for Swift on Linux
2+
3+
When running on the Objective-C runtime, XCTest is able to find all of your tests by simply asking the runtime for the subclasses of `XCTestCase`. It then finds the methods that start with the string `test`. This functionality is not currently present when running on the Swift runtime. Therefore, you must currently provide an additional property, conventionally named `allTests`, in your `XCTestCase` subclass. This method lists all of the tests in the test class. The rest of your test case subclass still contains your test methods.
4+
5+
```swift
6+
class TestNSURL : XCTestCase {
7+
static var allTests : [(String, TestNSURL -> () throws -> Void)] {
8+
return [
9+
("test_URLStrings", test_URLStrings),
10+
("test_fileURLWithPath_relativeToURL", test_fileURLWithPath_relativeToURL),
11+
("test_fileURLWithPath", test_fileURLWithPath),
12+
("test_fileURLWithPath_isDirectory", test_fileURLWithPath_isDirectory),
13+
// Other tests go here
14+
]
15+
}
16+
17+
func test_fileURLWithPath_relativeToURL() {
18+
// Write your test here. Most of the XCTAssert macros you are familiar with are available.
19+
XCTAssertTrue(theBestNumber == 42, "The number is wrong")
20+
}
21+
22+
// Other tests go here
23+
}
24+
```
25+
26+
Also, this version of XCTest does not use the external test runner binary. Instead, create your own executable which links `libXCTest.so`. In your `main.swift`, invoke the `XCTMain` function with an array of the test cases classes that you wish to run, wrapped by the `testCase` helper function. For example:
27+
28+
```swift
29+
XCTMain([testCase(TestNSString.allTests), testCase(TestNSArray.allTests), testCase(TestNSDictionary.allTests)])
30+
```
31+
32+
The `XCTMain` function does not return, and will cause your test app to exit with either `0` for success or `1` for failure. Command line arguments given to the executable can be used to select a particular test or test case to execute. For example:
33+
34+
```sh
35+
./FooTests FooTestCase/testFoo # Run a single test method
36+
./FooTests FooTestCase # Run all the tests in FooTestCase
37+
```
38+
39+
We are currently investigating ideas on how to make these additional steps for test discovery automatic when running on the Swift runtime.

‎README.md

Lines changed: 18 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -6,113 +6,47 @@ This version of XCTest uses the same API as the XCTest you are familiar with fro
66

77
## Current Status and Project Goals
88

9-
This project is the very earliest stages of development. It is scheduled to be part of the Swift 3 release.
9+
This project is in the very earliest stages of development. It is scheduled to be part of the Swift 3 release.
1010

1111
Only the most basic functionality is currently present. This year, we have the following goals for the project:
1212

13-
* Finish implementing support for the most important non-UI testing APIs present in XCTest for Xcode
13+
* Finish implementing support for the most important non-UI testing APIs present in XCTest for Xcode.
1414
* Develop an effective solution to the problem of test discoverability without the Objective-C runtime.
1515
* Provide support for efforts to standardize test functionality across the Swift stack.
1616

17+
For more details, visit the `Documentation` directory.
18+
1719
## Using XCTest
1820

1921
Your tests are organized into a simple hierarchy. Each `XCTestCase` subclass has a set of `test` methods, each of which should test one part of your code.
2022

2123
You can find all kinds of useful information on using XCTest in [Apple's documentation](https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/testing_with_xcode/chapters/03-testing_basics.html).
2224

23-
The rest of this document will focus on how this version of XCTest differs from the one shipped with Xcode.
24-
25-
## Working on XCTest
26-
27-
### On Linux
28-
29-
XCTest can be built as part of the overall Swift package. When following [the instructions for building Swift](http://www.github.com/apple/swift), pass the `--xctest` option to the build script:
30-
31-
```sh
32-
swift/utils/build-script --xctest
33-
```
34-
35-
If you want to build just XCTest, use the `build_script.py` script at the root of the project. The `master` version of XCTest must be built with the `master` version of Swift. XCTest has a dependency upon Foundation, so you must have built the `master` version of that as well.
36-
37-
If your install of Swift is located at `/swift` and you wish to install XCTest into that same location, here is a sample invocation of the build script:
38-
39-
```sh
40-
./build_script.py \
41-
--swiftc="/swift/usr/bin/swiftc" \
42-
--build-dir="/tmp/XCTest_build" \
43-
--foundation-build-dir "/swift/usr/lib/swift/linux" \
44-
--library-install-path="/swift/usr/lib/swift/linux" \
45-
--module-install-path="/swift/usr/lib/swift/linux/x86_64"
46-
```
47-
48-
To run the tests on Linux, use the `--test` option:
49-
50-
```sh
51-
./build_script.py \
52-
--swiftc="/swift/usr/bin/swiftc" \
53-
--foundation-build-dir "/swift/usr/lib/swift/linux" \
54-
--test
55-
```
25+
## Contributing to XCTest
5626

57-
You may add tests for XCTest by including them in the `Tests/Functional/` directory. For an example, see `Tests/Functional/SingleFailingTestCase`.
27+
To contribute, you'll need to be able to build this project and and run its test suite. The easiest way to do so is via the Swift build script.
5828

59-
### On OS X
29+
First, follow [the instructions in the Swift README](https://github.com/apple/swift/blob/master/README.md) to build Swift from source. Confirm you're able to build the Swift project using `utils/build-script -R`.
6030

61-
You may build XCTest via the "SwiftXCTest" scheme in `XCTest.xcworkspace`. The workspace assumes that Foundation and XCTest are checked out from GitHub in sibling directories. For example:
31+
Once you are able to build the Swift project, build XCTest and run its tests:
6232

6333
```
64-
% cd Development
65-
% ls
66-
swift-corelibs-foundation swift-corelibs-xctest
67-
%
34+
$ cd swift-corelibs-xctest
35+
$ ../swift/utils/build-script --preset corelibs-xctest
6836
```
6937

70-
Unlike on Linux, you do not need to build Foundation prior to building XCTest. The "SwiftXCTest" Xcode scheme takes care of that for you.
71-
72-
To run the tests on OS X, build and run the `SwiftXCTestFunctionalTests` target in the Xcode workspace. You may also run them via the command line:
38+
This project is only guaranteed to build with the very latest commit on the Swift and swift-corelibs-foundation `master` branches. You may update to the latest commits using the Swift `utils/update-checkout` script:
7339

7440
```
75-
xcodebuild -workspace XCTest.xcworkspace -scheme SwiftXCTestFunctionalTests
76-
```
77-
78-
When adding tests to the `Tests/Functional` directory, make sure they can be opened in the `XCTest.xcworkspace` by adding references to them, but do not add them to any of the targets.
79-
80-
### Additional Considerations for Swift on Linux
81-
82-
When running on the Objective-C runtime, XCTest is able to find all of your tests by simply asking the runtime for the subclasses of `XCTestCase`. It then finds the methods that start with the string `test`. This functionality is not currently present when running on the Swift runtime. Therefore, you must currently provide an additional property, conventionally named `allTests`, in your `XCTestCase` subclass. This method lists all of the tests in the test class. The rest of your test case subclass still contains your test methods.
83-
84-
```swift
85-
class TestNSURL : XCTestCase {
86-
static var allTests : [(String, TestNSURL -> () throws -> Void)] {
87-
return [
88-
("test_URLStrings", test_URLStrings),
89-
("test_fileURLWithPath_relativeToURL", test_fileURLWithPath_relativeToURL),
90-
("test_fileURLWithPath", test_fileURLWithPath),
91-
("test_fileURLWithPath_isDirectory", test_fileURLWithPath_isDirectory),
92-
// Other tests go here
93-
]
94-
}
95-
96-
func test_fileURLWithPath_relativeToURL() {
97-
// Write your test here. Most of the XCTAssert macros you are familiar with are available.
98-
XCTAssertTrue(theBestNumber == 42, "The number is wrong")
99-
}
100-
101-
// Other tests go here
102-
}
41+
$ ../swift/utils/update-checkout
10342
```
10443

105-
Also, this version of XCTest does not use the external test runner binary. Instead, create your own executable which links `libXCTest.so`. In your `main.swift`, invoke the `XCTMain` function with an array of the test cases classes that you wish to run, wrapped by the `testCase` helper function. For example:
44+
### Using Xcode
10645

107-
```swift
108-
XCTMain([testCase(TestNSString.allTests), testCase(TestNSArray.allTests), testCase(TestNSDictionary.allTests)])
109-
```
110-
111-
The `XCTMain` function does not return, and will cause your test app to exit with either `0` for success or `1` for failure. Command line arguments given to the executable can be used to select a particular test or test case to execute. For example:
46+
To browse files in this project using Xcode, use `XCTest.xcworkspace`. You may build the project using the "SwiftXCTest" scheme. Run the "SwiftXCTestFunctionalTests" scheme to run the tests.
11247

113-
```sh
114-
./FooTests FooTestCase/testFoo # Run a single test method
115-
./FooTests FooTestCase # Run all the tests in FooTestCase
116-
```
48+
However, in order to successfully build the project in Xcode, **you must use an Xcode toolchain with an extremely recent version of Swift**. The Swift website provides [Xcode toolchains to download](https://swift.org/download/#latest-development-snapshots), as well as [instructions on how to use Xcode with those toolchains](https://swift.org/download/#apple-platforms). Swift development moves fairly quickly, and so even a week-old toolchain may no longer work.
11749

118-
We are currently investigating ideas on how to make these additional steps for test discovery automatic when running on the Swift runtime.
50+
> If none of the toolchains available to download are recent enough to build XCTest, you may build your own toolchain by using [the `utils/build-toolchain` script in the Swift repository](https://github.com/apple/swift/blob/master/utils/build-toolchain).
51+
>
52+
> Keep in mind that the build script invocation in "Contributing to XCTest" above will always work, regardless of which Swift toolchains you have installed. The Xcode workspace exists simply for the convenience of contibutors. It is not necessary to successfully build this project in Xcode in order to contribute.

‎build_script.py

Lines changed: 38 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
import subprocess
1616
import sys
1717
import tempfile
18+
import textwrap
1819

1920
SOURCE_DIR = os.path.dirname(os.path.abspath(__file__))
2021

@@ -184,40 +185,60 @@ def main(args=sys.argv[1:]):
184185
function.
185186
"""
186187
parser = argparse.ArgumentParser(
187-
description="Builds, tests, and installs XCTest.")
188+
formatter_class=argparse.RawDescriptionHelpFormatter,
189+
description=textwrap.dedent("""
190+
Build, test, and install XCTest.
191+
192+
WARNING: This script is only meant to be used on Linux
193+
environments, and in general should not be invoked directly. The
194+
recommended way to build and test XCTest is via the Swift build
195+
script. See this project's README for details.
196+
197+
The Swift build script invokes this %(prog)s script to build,
198+
test, and install this project on Linux. Assuming you are on a
199+
Linux environment, you may invoke it in the same way to build this
200+
project directly. For example, If your install of Swift is located
201+
at "/swift" and you wish to install XCTest into that same location,
202+
here is a sample invocation of the build script:
203+
204+
$ %(prog)s \\
205+
--swiftc="/swift/usr/bin/swiftc" \\
206+
--build-dir="/tmp/XCTest_build" \\
207+
--foundation-build-dir "/swift/usr/lib/swift/linux" \\
208+
--library-install-path="/swift/usr/lib/swift/linux" \\
209+
--module-install-path="/swift/usr/lib/swift/linux/x86_64"
210+
"""))
188211
subparsers = parser.add_subparsers(
189-
description="Use one of these to specify whether to build, test, "
190-
"or install XCTest. If you don't specify any of these, "
191-
"'build' is executed as a default. You may also use "
192-
"'build' to also test and install the built products. "
193-
"Pass the -h or --help option to any of the subcommands "
194-
"for more information.")
212+
description=textwrap.dedent("""
213+
Use one of these to specify whether to build, test, or install
214+
XCTest. If you don't specify any of these, 'build' is executed as a
215+
default. You may also use 'build' to also test and install the
216+
built products. Pass the -h or --help option to any of the
217+
subcommands for more information."""))
195218

196219
build_parser = subparsers.add_parser(
197220
"build",
198-
description="Build XCTest.so, XCTest.swiftmodule, and XCTest.swiftdoc "
199-
"using the given Swift compiler. This command may also "
200-
"test and install the built products.")
221+
description=textwrap.dedent("""
222+
Build XCTest.so, XCTest.swiftmodule, and XCTest.swiftdoc using the
223+
given Swift compiler. This command may also test and install the
224+
built products."""))
201225
build_parser.set_defaults(func=_build)
202226
build_parser.add_argument(
203227
"--swiftc",
204228
help="Path to the 'swiftc' compiler that will be used to build "
205229
"XCTest.so, XCTest.swiftmodule, and XCTest.swiftdoc. This will "
206230
"also be used to build the tests for those built products if the "
207231
"--test option is specified.",
208-
metavar="PATH",
209232
required=True)
210233
build_parser.add_argument(
211234
"--build-dir",
212235
help="Path to the output build directory. If not specified, a "
213236
"temporary directory is used",
214-
metavar="PATH",
215237
default=tempfile.mkdtemp())
216238
build_parser.add_argument(
217239
"--foundation-build-dir",
218240
help="Path to swift-corelibs-foundation build products, which "
219241
"the built XCTest.so will be linked against.",
220-
metavar="PATH",
221242
required=True)
222243
build_parser.add_argument("--swift-build-dir",
223244
help="deprecated, do not use")
@@ -262,8 +283,7 @@ def main(args=sys.argv[1:]):
262283
test_parser.add_argument(
263284
"build_dir",
264285
help="An absolute path to a directory containing the built XCTest.so "
265-
"library.",
266-
metavar="PATH")
286+
"library.")
267287
test_parser.add_argument(
268288
"--swiftc",
269289
help="Path to the 'swiftc' compiler used to build and run the tests.",
@@ -278,7 +298,6 @@ def main(args=sys.argv[1:]):
278298
"--foundation-build-dir",
279299
help="Path to swift-corelibs-foundation build products, which the "
280300
"tests will be linked against.",
281-
metavar="PATH",
282301
required=True)
283302

284303
install_parser = subparsers.add_parser(
@@ -288,19 +307,16 @@ def main(args=sys.argv[1:]):
288307
install_parser.add_argument(
289308
"build_dir",
290309
help="An absolute path to a directory containing a built XCTest.so, "
291-
"XCTest.swiftmodule, and XCTest.swiftdoc.",
292-
metavar="PATH")
310+
"XCTest.swiftmodule, and XCTest.swiftdoc.")
293311
install_parser.add_argument(
294312
"-m", "--module-install-path",
295313
help="Location at which to install XCTest.swiftmodule and "
296314
"XCTest.swiftdoc. This directory will be created if it doesn't "
297-
"already exist.",
298-
metavar="PATH")
315+
"already exist.")
299316
install_parser.add_argument(
300317
"-l", "--library-install-path",
301318
help="Location at which to install XCTest.so. This directory will be "
302-
"created if it doesn't already exist.",
303-
metavar="PATH")
319+
"created if it doesn't already exist.")
304320

305321
# Many versions of Python require a subcommand must be specified.
306322
# We handle this here: if no known subcommand (or none of the help options)

0 commit comments

Comments
 (0)