Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

ci(sdk): enforce and document the Node floor for SDK tests (#1844)

Yudhi Armyndharis69a87edeae4e
diff --git a/.github/workflows/js-sdk-release.yml b/.github/workflows/js-sdk-release.yml
index 851cb9a6f..c7ce93823 100644
--- a/.github/workflows/js-sdk-release.yml
+++ b/.github/workflows/js-sdk-release.yml
@@ -84,7 +84,8 @@ jobs:
npm install -g [email protected]
npm --version
- - run: npm ci
+ # --engine-strict: the tests below must not run on a Node the locked toolchain does not support.
+ - run: npm ci --engine-strict
# Same gates as SDK CI, and for the same reason Java's release runs its tests: the artifact that
# reaches the registry must be the one that passed, not a rebuild nobody checked.
diff --git a/.github/workflows/sdk-ci.yml b/.github/workflows/sdk-ci.yml
index 4d4f95af2..e4e700464 100644
--- a/.github/workflows/sdk-ci.yml
+++ b/.github/workflows/sdk-ci.yml
@@ -40,9 +40,9 @@ jobs:
strategy:
fail-fast: false
matrix:
- # 18 is the published package's engines floor; vitest 4 needs Node 20+, so 18 only gates the
- # typecheck, build and smoke (packaging plus real requests through each build's client), and
- # the unit tests run on 20 and 22.
+ # 18 is the published package's engines floor; vitest 4 needs Node 20.19+ or 22.12+, so 18
+ # only gates the typecheck, build and smoke (packaging plus real requests through each
+ # build's client), and the unit tests run on 20 and 22.
node: ['18', '20', '22']
defaults:
run:
@@ -54,7 +54,11 @@ jobs:
node-version: ${{ matrix.node }}
cache: 'npm'
cache-dependency-path: sdk/javascript/package-lock.json
- - run: npm ci
+ # The lane that runs the tests installs with --engine-strict, so a locked toolchain that drops
+ # its Node fails here, naming the package, instead of warning and then testing on an
+ # unsupported runtime or failing at startup on a skipped native binding. The condition is the
+ # test step's own.
+ - run: npm ci --engine-strict=${{ matrix.node != '18' }}
- run: npm test
if: matrix.node != '18'
# The build tsconfigs exclude test/, and vitest strips types without checking them, so the
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4bd68b329..f855f5b78 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
- The JavaScript SDK CommonJS build no longer sets `moduleResolution` node10, which TypeScript 7 removed; the built output is unchanged.
+- JavaScript SDK CI and release jobs install with `--engine-strict` wherever they run the tests, so an unsupported Node fails at install.
- The JavaScript SDK smoke check sends requests through both built clients, so the Node 18 CI lane covers the request path.
- Retire the whatsapp-web.js download-mimetype install patch; inbound media downloads now pass the mimetype themselves.
- CI and the weekly security scan run `npm audit` over the JavaScript SDK, and Dependabot watches its lockfile.
@@ -114,7 +115,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Dependencies
- `handlebars` 4.7.9 to 4.7.10, closing two critical advisories in which a crafted template could inject JavaScript into compiled output. It reaches the root tree only through `ts-jest`, so it is dev-only and nothing that ships changes.
-- `vitest` 2.1 to 4.1 in the JavaScript SDK tree, closing its dev-only advisories. Its tests now need Node 20+; the published package still supports Node 18.
+- `vitest` 2.1 to 4.1 in the JavaScript SDK tree, closing its dev-only advisories. Its tests now need Node 20.19+ or 22.12+; the published package still supports Node 18.
### Upgrade notes (behavior changes)
diff --git a/docs/09-testing-strategy.md b/docs/09-testing-strategy.md
index ef69907e9..1b39a50e4 100644
--- a/docs/09-testing-strategy.md
+++ b/docs/09-testing-strategy.md
@@ -271,7 +271,7 @@ contract surfaces that SDKs mirror (`src/**/dto/**`, `src/**/*.controller.ts`, `
`src/engine/interfaces/whatsapp-engine.interface.ts`), so any backend controller or service change also
re-runs the SDK suites. It runs:
-- JavaScript SDK type-check, build, and dual CJS/ESM smoke test (module loading plus requests through each build's client) on Node 18 (the `engines` floor), 20 and 22, with unit tests on 20 and 22 (vitest 4 needs Node 20+).
+- JavaScript SDK type-check, build, and dual CJS/ESM smoke test (module loading plus requests through each build's client) on Node 18 (the `engines` floor), 20 and 22, with unit tests on 20 and 22 (vitest 4 needs Node 20.19+ or 22.12+).
- Python SDK type check with `mypy` and tests with `pytest` on Python 3.9 and 3.12.
- PHP SDK tests with PHPUnit.
- Java SDK tests with Maven.
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 929a73634..9ffff4c9a 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -1174,7 +1174,7 @@ The wire types live in a dedicated module (`types.ts` / `types.py`) so they can
### Release process
```bash
-# JavaScript
+# JavaScript (the tests need Node 20.19+ or 22.12+; the published package runs on Node 18+)
cd sdk/javascript && npm test && npm run build && npm run smoke # smoke = require()+import() packaging plus request check
# Python
cd sdk/python && python -m pytest -q
diff --git a/sdk/javascript/scripts/smoke.mjs b/sdk/javascript/scripts/smoke.mjs
index 1c236a6d3..7ffb745d1 100644
--- a/sdk/javascript/scripts/smoke.mjs
+++ b/sdk/javascript/scripts/smoke.mjs
@@ -31,9 +31,10 @@ for (const [format, mod] of [
}
}
-// Request smoke: the Node 18 lane skips the unit tests (vitest 4 needs Node 20+), and the typecheck
-// accepts DOM-declared globals Node 18 lacks, so send real requests through each build's client over
-// the default global fetch: a parsed 2xx body, a typed error for a non-2xx, and the abort timeout.
+// Request smoke: the Node 18 lane skips the unit tests (vitest 4 needs Node 20.19+ or 22.12+), and
+// the typecheck accepts DOM-declared globals Node 18 lacks, so send real requests through each
+// build's client over the default global fetch: a parsed 2xx body, a typed error for a non-2xx, and
+// the abort timeout.
const server = createServer((req, res) => {
if (req.url === '/api/health') {
res.writeHead(200, { 'Content-Type': 'application/json' });
diff --git a/src/common/node-engine-floor.spec.ts b/src/common/node-engine-floor.spec.ts
index f93597c3e..53b94d6cc 100644
--- a/src/common/node-engine-floor.spec.ts
+++ b/src/common/node-engine-floor.spec.ts
@@ -14,7 +14,7 @@ describe('package.json engines.node covers every installed package floor', () =>
// Hoisted by the lockfile (bullmq, sharp and ts-jest depend on it); it ships no types of its own.
// eslint-disable-next-line @typescript-eslint/no-require-imports
const semver = require('semver') as {
- minVersion(range: string): { version: string } | null;
+ minVersion(range: string): { version: string; major: number } | null;
satisfies(version: string, range: string): boolean;
};
@@ -59,4 +59,40 @@ describe('package.json engines.node covers every installed package floor', () =>
expect(unmetFloors('>=22.19', packages)).toEqual(['multi ^20.19.0 || >=24']);
expect(unmetFloors('>=24', packages)).toEqual([]);
});
+
+ // The SDK's engines floor (>=18) covers the published package only; its test toolchain needs more,
+ // so every place that tells a contributor which Node runs those tests must state a floor that the
+ // SDK lockfile actually supports.
+ it.each([
+ 'docs/09-testing-strategy.md',
+ 'docs/18-sdk-design.md',
+ '.github/workflows/sdk-ci.yml',
+ 'sdk/javascript/scripts/smoke.mjs',
+ ])('%s states an SDK test floor every locked SDK package supports', file => {
+ const lock = readJson<{ packages: Record<string, { optional?: boolean; engines?: unknown }> }>(
+ 'sdk/javascript/package-lock.json',
+ );
+ // Join wrapped comment lines so a floor split across two of them is still read.
+ const text = readFileSync(join(repo, file), 'utf8').replace(/\s*\n\s*(?:#|\/\/)?\s*/g, ' ');
+ const statements = [...text.matchAll(/needs? Node (\d+(?:\.\d+){0,2})\+(?: or (\d+(?:\.\d+){0,2})\+)?/g)];
+ expect(statements.length).toBeGreaterThan(0);
+ // Guard the scan: the published floor is below the toolchain's, so a scan that read no ranges fails here.
+ expect(unmetFloors('>=18', lock.packages)).not.toEqual([]);
+ // "20.19+ or 22.12+" admits 20.19 on the 20 line and 22.12 on the 22 line, and every later line from
+ // its first release, so the lowest release each statement admits is checked on every LTS (even) line
+ // through two past the last one it names: a bare "20.19+" answers for 22.0 too.
+ const lowest = statements.flatMap(([statement, ...floors]) => {
+ const named = floors.filter(Boolean).map(floor => semver.minVersion(floor)!);
+ const last = named[named.length - 1].major;
+ const lines: [string, string][] = [];
+ for (let major = named[0].major; major <= last + 2; major += 2) {
+ const version = named.find(v => v.major === major)?.version ?? (major > last ? `${major}.0.0` : undefined);
+ if (version) lines.push([statement, version]);
+ }
+ return lines;
+ });
+ expect(
+ lowest.map(([statement, version]) => [statement, version, unmetFloors(`>=${version}`, lock.packages)]),
+ ).toEqual(lowest.map(([statement, version]) => [statement, version, []]));
+ });
});
diff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.ts
index 6bc4077e3..96ceeab1e 100644
--- a/src/common/release-gate-parity.spec.ts
+++ b/src/common/release-gate-parity.spec.ts
@@ -178,6 +178,33 @@ describe('every npm tree is audited and kept current', () => {
});
});
+/**
+ * The SDK's engines floor (>=18) is for the published package; its test toolchain needs a newer
+ * Node. npm only warns when a locked package's engines exclude the running Node, so a toolchain bump
+ * that drops a lane's Node still installs there, then tests on an unsupported runtime or fails at
+ * startup on an optional native binding npm skipped. Each job that runs the SDK tests installs under
+ * --engine-strict on exactly the lanes the test step runs on.
+ */
+describe('the JavaScript SDK tests run only on a Node their toolchain supports', () => {
+ it.each([
+ ['sdk-ci.yml', 'javascript'],
+ ['js-sdk-release.yml', 'publish'],
+ ])('%s %s installs under --engine-strict wherever it runs npm test', (file, job) => {
+ const steps = (
+ yaml.load(fs.readFileSync(path.join(workflowDir, file), 'utf8')) as {
+ jobs: Record<string, { steps: Array<{ run?: string; if?: string }> }>;
+ }
+ ).jobs[job].steps;
+ const installs = steps.filter(step => /^npm ci\b/.test(step.run ?? ''));
+ const tests = steps.filter(step => step.run === 'npm test');
+ expect(installs).toHaveLength(1);
+ expect(tests).toHaveLength(1);
+ expect(installs[0].if).toBeUndefined();
+ const gate = tests[0].if;
+ expect(installs[0].run).toBe(gate ? `npm ci --engine-strict=\${{ ${gate} }}` : 'npm ci --engine-strict');
+ });
+});
+
/**
* BuildKit's provenance and SBOM travel inside the image index unsigned, so nothing a user could check
* tied a published image to this workflow. promote now records a signed build-provenance attestation