Stefan Hacker
79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# AGENTS.md
|
|
|
|
ts-loader is a TypeScript loader for webpack, enabling webpack to compile `.ts` and `.tsx` files via the TypeScript compiler.
|
|
|
|
## Package manager
|
|
|
|
Use `yarn` (not npm).
|
|
|
|
## Key commands
|
|
|
|
```bash
|
|
yarn build # compile src/ → dist/ (tsc --project "./src")
|
|
yarn lint # type-check + ESLint (no separate typecheck script)
|
|
yarn test # full test suite (comparison + execution tests)
|
|
yarn comparison-tests # fast subset: compare webpack output against snapshots
|
|
yarn execution-tests # run compiled code via Karma/Jasmine
|
|
```
|
|
|
|
To run a single test:
|
|
```bash
|
|
yarn comparison-tests -- --single-test <testName>
|
|
yarn execution-tests -- --single-test <testName> --watch
|
|
```
|
|
|
|
## Comparison tests (`test/comparison-tests/`)
|
|
|
|
Each sub-directory is a mini webpack project. The harness compiles it and diffs the output against `expectedOutput/` snapshots (`bundle.js`, `output.txt`, `err.txt`). These are especially useful for failure cases — asserting that the right compiler errors appear.
|
|
|
|
Full docs: [`test/comparison-tests/README.md`](test/comparison-tests/README.md)
|
|
|
|
**Watch-mode tests** apply a series of patches (`patch0/`, `patch1/`, …) after the initial build, re-compiling and re-comparing after each one.
|
|
|
|
**Flaky tests**: place an empty `_FLAKY_` file in the test directory to allow occasional failures without blocking the build.
|
|
|
|
```bash
|
|
yarn comparison-tests # all tests
|
|
yarn comparison-tests -- --single-test <name> # one test
|
|
yarn comparison-tests -- --save-output # regenerate all snapshots
|
|
yarn comparison-tests -- --save-output --single-test <name> # regenerate one snapshot
|
|
```
|
|
|
|
> Note: test name casing must be exact when using `--single-test`.
|
|
|
|
### Seeding snapshots for a new TypeScript version
|
|
|
|
When adding support for a new TypeScript version, run:
|
|
|
|
```bash
|
|
yarn comparison-tests-generate
|
|
```
|
|
|
|
This does two things:
|
|
1. `git clean -xfd test/comparison-tests` — wipes all untracked/generated files in the test directory.
|
|
2. Runs `test/comparison-tests/stub-new-version.js`, which copies every `expectedOutput-{OLD}/` and `expectedOutput-transpile-{OLD}/` folder to the corresponding `expectedOutput-{NEW}/` counterpart across all test sub-directories.
|
|
|
|
The `OLD_VERSION` and `NEW_VERSION` constants at the top of `stub-new-version.js` must be updated manually before running this script each time a new TypeScript version is introduced. After running, review and commit the seeded snapshots, then use `--save-output` to correct any that differ from the new version's actual output.
|
|
|
|
## Execution tests (`test/execution-tests/`)
|
|
|
|
Each sub-directory is a mini webpack project with a Karma/Jasmine test suite. The harness compiles the project and **runs the compiled code** — useful for asserting correct runtime behaviour. These are matrix-tested in CI across Node 20/22 and TypeScript 5.x versions.
|
|
|
|
Full docs: [`test/execution-tests/README.md`](test/execution-tests/README.md)
|
|
|
|
Tests prefixed with a TypeScript version (e.g. `2.0.3_es2016`) are skipped when the installed TypeScript is older than that prefix.
|
|
|
|
Every `webpack.config.js` in this pack must include this alias so the local ts-loader is resolved:
|
|
```js
|
|
// for test harness purposes only
|
|
module.exports.resolveLoader = { alias: { 'ts-loader': path.join(__dirname, "../../../index.js") } }
|
|
```
|
|
|
|
```bash
|
|
yarn execution-tests # all tests
|
|
yarn execution-tests -- --single-test <name> # one test
|
|
yarn execution-tests -- --single-test <name> --watch # watch mode (open http://localhost:9876/)
|
|
```
|
|
|
|
Always add or update tests when fixing bugs or adding features — see [CONTRIBUTING.md](CONTRIBUTING.md).
|