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
|
# Development
This document contains notes about development and testing of IndexStoreDB.
## Table of Contents
* [Writing Tests](#writing-tests)
* [Tibs, the "Test Index Build System"](Tibs.md)
## Writing Tests
As much as is practical, all code should be covered by tests. New tests can be added under the `Tests` directory and should use `XCTest`. The rest of this section will describe the additional tools available in the `ISDBTestSupport` module to make it easier to write good and efficient tests.
Most indexer tests follow a pattern:
1. Build and index a test project
2. Perform index queries
3. Compare the results against known locations in the test code
4. (Optional) modify the code and repeat.
### Test Projects (Fixtures)
Index test projects should be put in the `ISDBTestSupport/INPUTS` directory, and use the [Tibs](Tibs.md) build system to define their sources and targets. An example test project might look like:
```
ISDBTestSupport/
INPUTS/
MyTestProj/
a.swift
b.swift
c.cpp
```
Where `project.json` describes the project's targets, for example
```
{ "sources": ["a.swift", "b.swift", "c.cpp"] }
```
Tibs supports more advanced project configurations, such as multiple swift modules with dependencies, etc. For much more information about Tibs, including what features it supports and how it works, see [Tibs.md](Tibs.md).
### TibsTestWorkspace
The `TibsTestWorkspace` pulls together the various pieces needed for working with tests, including building the project, creating an IndexStoreDB instance, and keeping it up to date after modifying sources.
To create a `TibsTestWorkspace`, use the `staticTibsTestWorkspace` and `mutableTibsTestWorkspace` methods. Tests that do not mutate sources should use `staticTibsTestWorkspace`.
```swift
func testFoo() {
// Loads an immutable workspace for the test project "MyTestProj" and resolves
// all of its targets, ready to be indexed.
guard let ws = try staticTibsTestWorkspace(name: "MyTestProj") else { return }
// Perform the build and read the produced index data.
try ws.buildAndIndex()
// See the results
ws.index.occurrences(ofUSR: "<some usr>", ...)
...
}
```
#### Source Locations
It is common to want to refer to specific locations in the source code of a test project. This is supported using inline comment syntax.
```swift
Test.swift:
func /*myFuncDef*/myFunc() {
/*myFuncCall*/myFunc()
}
```
In a test, these locations can be referenced by name. The named location is immediately after the comment.
```swift
let loc = ws.testLoc("myFuncDef")
// TestLocation(url: ..., line: 1, column: 19)
```
A common use of a `TestLocation` is to form a `SymbolOccurrence` at that location.
```swift
let occurrence = Symbol(...).at(ws.testLoc("myFuncDef"), roles: .definition)
```
#### Comparing SymbolOccurrences
Rather than attempting to compare `SymbolOccurrences` for equality, prefer using the custom XCTest assertion method `checkOccurrences`. This API avoids accidentally comparing details that are undefined (e.g. the order of occurrences), or likely to change frequently (e.g. `SymbolRole`s are checked to be a superset instead of an exact match, as we often add new roles).
```
checkOccurrences(ws.index.occurrences(ofUSR: sym.usr, roles: .all), expected: [
sym.at(ws.testLoc("c"), roles: .definition),
sym.at(ws.testLoc("c_call"), roles: .call),
])
```
#### Mutating Test Sources
In order to test changes to the index, we create a mutable test workspace. The mutable project takes care of copying the sources to a new location. Afterwards, we can mutate the sources using the `TibsTestWorkspace.edit(rebuild: Bool, block: ...)` method.
```
func testMutating() {
guard let ws = try mutableTibsTestWorkspace(name: "MyTestProj") else { return }
try ws.buildAndIndex()
// Check initial state...
// Perform modifications to "url"!
ws.edit(rebuild: true) { editor, files in
// Read the original contents and add a new line.
let new = try files.get(url).appending("func /*moreCodeDef*/moreCode() {}")
// Provide the new contents for "url".
editor.write(new, to: url)
}
}
```
After we return from `edit()`, the sources are modified and any changes to stored source locations are reflected. We can now `buildAndIndex()` to update the index, or as a convenience we can pass `rebuild: true` to `edit`.
|
