Skip to content

Commit e106879

Browse files
docs: list the git submodules and how to update them (#22124)
* doc: update agents.md about submodules * docs: clarify submodule setup for test suites --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent 3b68619 commit e106879

1 file changed

Lines changed: 18 additions & 2 deletions

File tree

‎AGENTS.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,23 @@ The directory listings below are the canonical map of the repository. **Whenever
105105

106106
**Tests** — see [TESTING_DOCS.md](TESTING_DOCS.md) for directory structure, naming, and how to run a single case.
107107

108-
- `test/` — All test suites (`cases/`, `configCases/`, `watchCases/`, `hotCases/`, `statsCases/`, `typesCases/`, `test262-cases/`, `html5lib-tests/`, `wpt/`, `css-parsing-tests/`, `benchmarkCases/`, `memoryLimitCases/`, etc.). `RoundTripConfigCases` re-bundles the output of `configCases` marked with a `roundTrip.js` file. `wpt/` is web-platform-tests, checked out one commit deep by the `html5lib` job alone — it is where the HTML tree-construction corpus lives since html5lib-tests dropped it.
108+
- `test/` — All test suites (`cases/`, `configCases/`, `watchCases/`, `hotCases/`, `statsCases/`, `typesCases/`, `test262-cases/`, `html5lib-tests/`, `wpt/`, `css-parsing-tests/`, `benchmarkCases/`, `memoryLimitCases/`, etc.). `RoundTripConfigCases` re-bundles the output of `configCases` marked with a `roundTrip.js` file. `wpt/` is web-platform-tests, checked out one commit deep by the `html5lib` and `syntax-equivalence` jobs — it is where the HTML tree-construction corpus lives since html5lib-tests dropped it.
109+
110+
**Git submodules** — the spec-conformance corpora are submodules, checked out on demand: `yarn setup` does not fetch them, and each CI job fetches only the submodules it needs, one commit deep.
111+
112+
| Path | Upstream | Fetched by |
113+
| ------------------------ | ------------------------------------------------------------------------------------- | -------------------------------- |
114+
| `test/test262-cases` | [tc39/test262](https://github.com/tc39/test262) | `test262`, `test262-parser` |
115+
| `test/html5lib-tests` | [html5lib/html5lib-tests](https://github.com/html5lib/html5lib-tests) | `html5lib` |
116+
| `test/wpt` | [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt) | `html5lib`, `syntax-equivalence` |
117+
| `test/css-parsing-tests` | [CourtBouillon/css-parsing-tests](https://github.com/CourtBouillon/css-parsing-tests) | `css-parsing` |
118+
119+
```sh
120+
git submodule update --init --recursive --depth 1 # check out the commits the repo pins
121+
git submodule update --init --recursive --remote --depth 1 # move every pin to its upstream tip
122+
```
123+
124+
Keep `--depth 1`: `wpt` alone is ~161k files. `--remote` changes the commit the repo records for each path, so `git status` shows the four `test/…` paths modified — commit that only once CI is green on the new commits, or run `git submodule update` to return to the pinned ones.
109125

110126
**Examples & changesets**
111127

@@ -325,7 +341,7 @@ Pitfalls that have produced wrong conclusions here:
325341
yarn test:basic --testPathPatterns="ConfigTestCases" --testNamePattern="<category> <case>"
326342
```
327343

328-
Swap `ConfigTestCases` for `StatsTestCases`, `HotTestCases`, `WatchTestCases`, … (full matrix in [TESTING_DOCS.md](TESTING_DOCS.md)). The `test262`/`html5lib`/`css-parsing` suites are git submodules — run `git submodule update --init test/<dir>` first, or they fail confusingly.
344+
Swap `ConfigTestCases` for `StatsTestCases`, `HotTestCases`, `WatchTestCases`, … (full matrix in [TESTING_DOCS.md](TESTING_DOCS.md)). The `test262`, `html5lib`, `syntax-equivalence`, and `css-parsing` suites use git submodules — run `git submodule update --init --depth 1 test/test262-cases test/html5lib-tests test/wpt test/css-parsing-tests` first, or they fail confusingly.
329345

330346
**Writing a `configCases/` case:** a case is a mini project — `index.js` (runs assertions; a thrown error fails the test) plus `webpack.config.js`. The emitted bundle is actually executed, so it must run. Optional per-case files: `errors.js` / `warnings.js` export arrays of matchers for expected build diagnostics (without them, any error/warning fails the case); `test.filter.js` returns `false` to skip the case (e.g. gate by Node version — see [Target the Node baseline](#target-the-node-baseline) when the fixture itself needs newer syntax); `test.config.js` customizes the run (e.g. `findBundle`).
331347

0 commit comments

Comments
 (0)