[Upd4ting]

Why

A backend could not run the decorators conformance suite (dist/tests) for two server versions in parallel. The model test fetched its routes from API port 5010, a fixed value, so a second suite on the same machine failed to bind that port. AntelopeJS/mysql ran into this when running MySQL 8.4/9.7 and MariaDB 11.8/12.3 side by side, and now holds a lock so only one decorators run happens at a time. Parallel agent sessions on one machine collided on the port too.

What

• src/tests/helpers/api-port.ts adds ApiPort(). It reads DECORATORS_TEST_API_PORT, uses 5010 when the variable is unset or empty, and throws on anything that is not a port from 1 to 65535.
• src/tests/model.test.ts fetches from http://localhost:${ApiPort()}.
• This repository's src/antelope.test.ts serves api on the same port.
• AGENTS.md names the variable.

A backend that runs the suite sets DECORATORS_TEST_API_PORT and serves its api module on that same port. ApiPort is not a public subpath, so the backend reads the variable itself, for example Number(process.env.DECORATORS_TEST_API_PORT ?? 5010). With the variable unset, nothing changes for current backends.

flowchart LR
  env["DECORATORS_TEST_API_PORT (default 5010)"] --> cfg["backend antelope.test.ts: api servers port"]
  env --> test["dist/tests/model.test.js: ApiPort()"]
  cfg --> api["@antelopejs/api listens on port"]
  test -->|"fetch http://localhost:port/..."| api

Loading

Proof

Two copies of the repository, each built, each running ajs module test . -f dist/tests/model.test.js at the same time.

Before, two copies of origin/main. Both bind 5010. One run fails:

=== before-a
[ERROR]   - Error: PortReservationError: Unable to bind port 5010 for the http server: the port is already in use. Port fallback is disabled; set strictPort to false in development to accept the next free port.
✖ Failed to construct modules
exit 1
=== before-b
  17 passing (35ms)
exit 0

After, two copies of this branch. One leaves the variable unset (5010), the other sets DECORATORS_TEST_API_PORT=5011. Both pass:

=== after-a
  17 passing (37ms)
exit 0
=== after-b
  17 passing (37ms)
exit 0

src/tests/api_port.test.ts covers the default, an explicit port, and the rejection of abc, 0, 65536, 50.1, 5011 and -1.

pnpm run checks:

Checks: 11 passed, 0 failed.