This project uses lightweight quality gates on plain JavaScript (CommonJS) with targeted unit tests.
Run these from the repository root:
npm run typecheck- TypeScript JS checking (tsc --noEmit)npm run lint- ESLint checksnpm run format:check- Prettier formatting checknpm run check- Node syntax check for runtime modulesnpm run test- Node test runner (node --test)
For local iteration:
npm run format- apply formatting fixes
Recommended pre-PR sequence:
npm run typecheck
npm run lint
npm run format:check
npm run check
npm run testtests/config.test.cjs- configuration loading and validation behaviortests/known-callers.test.cjs-KNOWN_CALLERSparsing and the caller label attached totwiml-responsetests/state.test.cjs- call session lifecycle and stale-session cleanuptests/stream-auth.test.cjs- stream token issue/verify, replay and tamper rejection, TwiML builder,/mediahandshake signature verification (URL variants, forgery rejection, candidate-set pin)tests/media-upgrade.test.cjs-/mediahandshake as Twilio sees it: 404/400/403/503 refusals, cap after signature, 1009 on an oversized frame, survival of malformed targets and socket errorstests/media-stream.test.cjs- Twilio media stream protocol (start/media/stop, token checks, teardown, binary frames ignored, size limit in UTF-8 bytes)tests/ws-events-schema.test.cjs- Twilio WS envelope and media payload validationtests/mulaw-audio.test.cjs- mu-law encode/decode, DTMF and ringback generation, WAV renderingtests/log.test.cjs- structured logger output, levels, and error normalizationtests/twilio-ids.test.cjs- Twilio identifier normalizationtests/inbound-ffmpeg-args.test.cjs- inbound ffmpeg arguments, including the two #102 guards (no stream probing on the mu-law input, Opus RTP relabelled to a 16 kHz clock)tests/return-audio-sdp.test.cjs- return-audio SDP generation and teardowntests/homekit-shutdown.test.cjs- the shutdown path unpublishes and never destroys (pairing-loss guard)tests/homekit-hangup-grace.test.cjs- the call is held open after the live view closes, and the pending hangup is cancelled, deferred, superseded or skipped correctly (unlock-from-room-view guard)tests/cli.test.cjs---qr/--check/--help/--version, plus the hap-nodejs and node-persist behaviours they rest ontests/publish-release-workflow.test.cjs- release publish workflow guardstests/publish-prerelease-workflow.test.cjs- prerelease publish workflow guardstests/coverage.test.cjs- coverage script scope, preload, Codecov job, and entry-point inertness guardstests/helpers/env.cjs- env/module-cache test helperstests/helpers/coverage-preload.cjs- loads the entry points so coverage reports them
- Prefer unit tests near existing module suites (
tests/*.test.cjs). - Cover both success and rejection paths for boundary parsers/validators.
- Keep tests deterministic:
- avoid timer races
- if needed, simulate time explicitly (as done in stale-session tests)
Use helper wrappers from tests/helpers/env.cjs to set and restore env values
for each test. Avoid mutating process.env globally without restoring it.
The npm test script sets DOTENV_CONFIG_PATH=/dev/null so that a developer's
local .env file cannot leak values into the test environment. If you invoke
node --test directly, set this variable yourself.
Modules like config and state are loaded once by Node. If a test depends on
changed env values, reload modules with cache clearing via freshRequire.
state creates a stale-session reaper interval. Tests must stop manager
instances in teardown to avoid cross-test interference.
The runtime exports singleton-style modules. Tests should avoid relying on test execution order and should always reset state or load fresh module instances.
CI runs all five gates (lint, format check, syntax check, typecheck, tests) on
every Node line currently in LTS, using atdr/github-boilerplate's node-ci.yml.
Pull requests additionally run commitlint over the branch commits and a
conventional PR title check (pull-request.yml).
A separate Dependency audit job runs npm audit --audit-level=high twice. The
blocking run adds --omit=dev, so only advisories reaching the deployed
dependency tree fail CI; the second run covers the whole tree and reports a red
annotation on a green job, surfacing build-tool advisories without blocking
unrelated PRs. It is deliberately outside the quality-gate job — an audit result
reflects the advisory database at a point in time rather than the diff under
review, and while it ran first inside that job any advisory masked lint, tests,
and typecheck. Dev-tree advisories are fixed by Dependabot security updates
rather than by hand; a red audit check now means genuine production exposure.
A coverage job re-runs the suite under V8 instrumentation on the newest LTS
Node and uploads lcov.info to Codecov, which supplies the README badge, per-PR
comments, and history. It is reporting, not a sixth gate: the Node matrix is
what proves the suite passes. Codecov's own status checks in codecov.yml are
able to fail (the boilerplate conventions check rejects informational: true),
with a 0.1% threshold on the project status, and the upload step is
continue-on-error because an outage there says nothing about the change under
review. The coverage run itself stays blocking. CI calls npm run coverage
rather than its own command line so local and CI measure the same thing;
tests/coverage.test.cjs guards that and the rest of the setup.
npm run coverage # needs Node >= 22.5; writes lcov.info (gitignored)Two details in that script are load-bearing. --test-coverage-include is pinned
to the files array in package.json, so the measurement is what ships rather
than every file V8 happened to load. And
--require ./tests/helpers/coverage-preload.cjs loads server.js, homekit.js
and twilio-api.js, which no test requires: V8 reports nothing for an
unloaded file rather than reporting it at 0%, so dropping the preload would
delete the three least-tested shipped modules from the report and raise the
number.
That preload is only possible because both entry points are inert when required
— server.js starts from main() and homekit.js publishes from start(),
both gated on require.main === module. See the "Entry points are inert on
require" section in AGENTS.md; tests/coverage.test.cjs guards it.
Locally, husky hooks (installed automatically by npm install) run commitlint
on each commit message and lint-staged (ESLint + Prettier on staged files)
before each commit.
Releases are automated by release-please, which maintains a release PR on main
derived from conventional commit history.
Dependabot's patch and minor bumps merge themselves: auto-merge.yml calls
atdr/github-boilerplate's dependabot-auto-merge, which switches on GitHub's
auto-merge once it sees the highest bump in the PR is a patch or minor. The
merge still waits for every gate the ruleset requires, and only happens where
the repository has auto-merge on (configure.sh turns it on where the ruleset
requires the gates). Majors wait for review. Each package ecosystem has a three
day cooldown, so a freshly published release cannot merge itself within hours;
security updates skip it. A merge made this way is pushed by GITHUB_TOKEN,
which starts no push workflow, so CI on main and release-please's update of
the release PR happen on the next push. A production fix(deps) bump therefore
reaches the release PR then, not at once.
If a change passes locally but fails in CI, first verify Node version parity and rerun all commands from a clean working tree.