@@ -6,23 +6,22 @@ This document provides a concise guide for writing TypeScript fourslash tests an
66
77### Setup
881 . 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 `
1211
1312### Common Build Tasks
1413``` 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
2625```
2726
2827## Fourslash Test Syntax Guide
@@ -248,27 +247,35 @@ const config3: Config = { optional: 42 }; // Should error - missing required
248247
249248``` bash
250249# Run a specific fourslash test
251- hereby runtests --tests=tests/cases/fourslash/completionForObjectProperty.ts
250+ npx hereby runtests --tests=tests/cases/fourslash/completionForObjectProperty.ts
252251
253252# Run a specific compiler test
254- hereby runtests --tests=tests/cases/compiler/abstractClassUnionInstantiation.ts
253+ npx hereby runtests --tests=tests/cases/compiler/abstractClassUnionInstantiation.ts
255254
256255# Run tests matching a pattern
257- hereby runtests --tests=tests/cases/fourslash/completion* .ts
256+ npx hereby runtests --tests=tests/cases/fourslash/completion* .ts
258257```
259258
260259## Important Guidelines
261260
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+
262266### Test Locations
267+
263268- 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 `
264270- Do not write direct unit tests as they are almost never the correct test format for our repo
265271
266272### Performance Expectations
273+
267274- Running a set of tests may take up to 4 minutes
268275- A full test run may take up to 15 minutes
269- - Always run ` hereby lint ` and ` hereby format ` before you're done
270276
271277### Working with Issues
278+
272279- Maintainer comments in the issue should generally take priority over OP's comments
273280- Maintainers might give you hints on where to start. They are not always right, but a good place to start
274281
@@ -287,6 +294,14 @@ When fixing bugs or implementing features, follow this workflow:
287294 - Ensure the baselines change in a way that demonstrates that the bug is fixed
288295 - Put this baseline diff in its own commit
289296
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
292304 - 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