@@ -6,23 +6,22 @@ This document provides a concise guide for writing TypeScript fourslash tests an
6
6
7
7
### Setup
8
8
1 . Install Node.js (current or LTS)
9
- 2 . Install hereby: ` npm install -g hereby `
10
- 3 . Clone the repository: ` git clone --depth=1 https://github.com/microsoft/TypeScript `
11
- 4 . Install dependencies: ` npm ci `
9
+ 2 . Clone the repository: ` git clone --depth=1 https://github.com/microsoft/TypeScript `
10
+ 3 . Install dependencies: ` npm ci `
12
11
13
12
### Common Build Tasks
14
13
``` bash
15
- hereby local # Build the compiler into built/local
16
- hereby clean # Delete the built compiler
17
- hereby tests # Build the test infrastructure
18
- hereby runtests # Run all tests
19
- hereby runtests-parallel # Run tests in parallel (recommended)
20
- hereby runtests --runner=fourslash # Run only fourslash tests
21
- hereby runtests --runner=compiler # Run only compiler tests
22
- hereby runtests --tests=< testPath> # Run specific test
23
- hereby baseline-accept # Accept new test baselines
24
- hereby lint # Run eslint
25
- hereby format # Run code formatting
14
+ npx hereby local # Build the compiler into built/local
15
+ npx hereby clean # Delete the built compiler
16
+ npx hereby tests # Build the test infrastructure
17
+ npx hereby runtests # Run all tests
18
+ npx hereby runtests-parallel # Run tests in parallel (recommended)
19
+ npx hereby runtests --runner=fourslash # Run only fourslash tests
20
+ npx hereby runtests --runner=compiler # Run only compiler tests
21
+ npx hereby runtests --tests=< testPath> # Run specific test
22
+ npx hereby baseline-accept # Accept new test baselines
23
+ npx hereby lint # Run eslint
24
+ npx hereby format # Run code formatting
26
25
```
27
26
28
27
## Fourslash Test Syntax Guide
@@ -248,27 +247,35 @@ const config3: Config = { optional: 42 }; // Should error - missing required
248
247
249
248
``` bash
250
249
# Run a specific fourslash test
251
- hereby runtests --tests=tests/cases/fourslash/completionForObjectProperty.ts
250
+ npx hereby runtests --tests=tests/cases/fourslash/completionForObjectProperty.ts
252
251
253
252
# Run a specific compiler test
254
- hereby runtests --tests=tests/cases/compiler/abstractClassUnionInstantiation.ts
253
+ npx hereby runtests --tests=tests/cases/compiler/abstractClassUnionInstantiation.ts
255
254
256
255
# Run tests matching a pattern
257
- hereby runtests --tests=tests/cases/fourslash/completion* .ts
256
+ npx hereby runtests --tests=tests/cases/fourslash/completion* .ts
258
257
```
259
258
260
259
## Important Guidelines
261
260
261
+ ### Keeping Things Tidy
262
+
263
+ - Once you think you're done, run ` npx hereby lint ` and fix any issues
264
+ - Then always run ` npx hereby format ` as your last step
265
+
262
266
### Test Locations
267
+
263
268
- Only add testcases in ` tests/cases/compiler ` or ` tests/cases/fourslash `
269
+ - Filenames in ` tests/cases/compiler ` must always end with ` .ts ` , not ` .d.ts `
264
270
- Do not write direct unit tests as they are almost never the correct test format for our repo
265
271
266
272
### Performance Expectations
273
+
267
274
- Running a set of tests may take up to 4 minutes
268
275
- A full test run may take up to 15 minutes
269
- - Always run ` hereby lint ` and ` hereby format ` before you're done
270
276
271
277
### Working with Issues
278
+
272
279
- Maintainer comments in the issue should generally take priority over OP's comments
273
280
- Maintainers might give you hints on where to start. They are not always right, but a good place to start
274
281
@@ -287,6 +294,14 @@ When fixing bugs or implementing features, follow this workflow:
287
294
- Ensure the baselines change in a way that demonstrates that the bug is fixed
288
295
- Put this baseline diff in its own commit
289
296
290
- 4 . ** Run all other tests to ensure you didn't break anything**
291
- - Some collateral baseline changes are normal
297
+ 4 . ** Add more testing**
298
+ - Once you've got the basics figured out, enhance your test to cover edge cases and other variations
299
+ - Run the test again and commit the baseline diff along with the test edit
300
+
301
+ 5 . ** Run all other tests to ensure you didn't break anything**
302
+ - Run ` npx hereby runtests-parallel ` and wait for it to finish (10-15 minutes is normal!)
303
+ - Some collateral baseline changes are normal, but review for correctness
292
304
- Put these diffs in another commit
305
+
306
+ 6 . ** Always format and lint**
307
+ - Don't forget to run ` npx hereby lint ` and ` npx hereby format ` before you're done
0 commit comments