Skip to content

Latest commit

 

History

History
172 lines (139 loc) · 7.94 KB

testing.md

File metadata and controls

172 lines (139 loc) · 7.94 KB

Testing guide

This project uses lightweight quality gates on plain JavaScript (CommonJS) with targeted unit tests.

Quality commands

Run these from the repository root:

  • npm run typecheck - TypeScript JS checking (tsc --noEmit)
  • npm run lint - ESLint checks
  • npm run format:check - Prettier formatting check
  • npm run check - Node syntax check for runtime modules
  • npm 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 test

Test layout

  • tests/config.test.cjs - configuration loading and validation behavior
  • tests/known-callers.test.cjs - KNOWN_CALLERS parsing and the caller label attached to twiml-response
  • tests/state.test.cjs - call session lifecycle and stale-session cleanup
  • tests/stream-auth.test.cjs - stream token issue/verify, replay and tamper rejection, TwiML builder, /media handshake signature verification (URL variants, forgery rejection, candidate-set pin)
  • tests/media-upgrade.test.cjs - /media handshake as Twilio sees it: 404/400/403/503 refusals, cap after signature, 1009 on an oversized frame, survival of malformed targets and socket errors
  • tests/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 validation
  • tests/mulaw-audio.test.cjs - mu-law encode/decode, DTMF and ringback generation, WAV rendering
  • tests/log.test.cjs - structured logger output, levels, and error normalization
  • tests/twilio-ids.test.cjs - Twilio identifier normalization
  • tests/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 teardown
  • tests/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 on
  • tests/publish-release-workflow.test.cjs - release publish workflow guards
  • tests/publish-prerelease-workflow.test.cjs - prerelease publish workflow guards
  • tests/coverage.test.cjs - coverage script scope, preload, Codecov job, and entry-point inertness guards
  • tests/helpers/env.cjs - env/module-cache test helpers
  • tests/helpers/coverage-preload.cjs - loads the entry points so coverage reports them

When adding new tests

  1. Prefer unit tests near existing module suites (tests/*.test.cjs).
  2. Cover both success and rejection paths for boundary parsers/validators.
  3. Keep tests deterministic:
    • avoid timer races
    • if needed, simulate time explicitly (as done in stale-session tests)

Isolation pitfalls and patterns

Environment variable isolation

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.

Module cache invalidation

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.

Long-lived timers/intervals

state creates a stale-session reaper interval. Tests must stop manager instances in teardown to avoid cross-test interference.

Shared singleton state

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 notes

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.