Technical Manual sections
Reference › Technical Manual › Testing
Kitten’s tests are in tests/, and the npm scripts in package.json run them. These are the suites:
Unit tests (tests/*.ts, tests/lib/, tests/routes/, tests/middleware/, and tests/data/) use
node:test, with the@small-web/test-monkeyreporter, and run the source through the loader (--import ./src/entry/loader.js). Most of them don’t need an installed Kitten. (tests/lib/Version.ts reads the installed Kitten’s version.json, and tests/lib/launcher-guard.ts skips its tests until a build has created dist/update-guard.js.)Regression tests (tests/regression/) start Kitten servers on the apps in tests/fixtures/regression/ and in examples/, and check what they serve with the JSDOM-based helpers in tests/helpers/Browser.ts (e.g.,
getDom()).End-to-end tests (tests/end-to-end/) use Playwright in Chromium, Firefox, and WebKit. The fixtures in tests/end-to-end/helpers/fixtures.ts start isolated servers (
startKitten), close every browser context that a test opens, and abort requests to hosts other thanlocalhostand*.localhost. Tests tagged@networkneed the network, and the-offlinescripts skip them.The start-up benchmark (tests/benchmarks/startup.ts) measures how long the installed Kitten takes to start, and to restart its worker after a crash (the same restart that happens each time you save a file in development). It measures each ten times (
RUNS) and compares both medians with a baseline recorded on your machine (.cache/startup-benchmark-baseline.json), and exits with 1 when either is more than 25% (ALLOWED_SLOWDOWN) above it. The first run records the baseline. Pass-- --update-baselineto record a new one (e.g., after you upgrade Node.js or move to another machine). The baseline records the exact version of Kitten it was measured with, which includes the Node.js version. Run the benchmark before a release and after any change that might affect start-up, on an otherwise idle machine.The automatic updates rehearsal (tests/rehearsal/) runs a reset and fifteen scenarios on a real server and a staging distribution server. Its README.md lists what it needs, and Updates lists when to run it.
The Kitten helper (tests/helpers/Kitten.ts) runs the kitten command on your path in a subprocess, on a free port unless you pass one. It waits for the server to report that it is listening, and stops its whole process tree. A server on a free port deletes its data folder when it stops. tests/helpers/global-setup.ts runs before the regression and end-to-end suites. It installs the dependencies of the examples that have them, and starts a throwaway server so the localhost certificate authority exists before parallel workers start.
These scripts run the suites:
npm test: the unit, regression, and end-to-end tests, one suite after the other.npm run quick-tests: the unit and regression tests, and the end-to-end tests in Chromium only.npm run unit-tests,npm run regression-tests, andnpm run end-to-end-tests: one suite each. (npm run unit-tests-debuguses Node’s built-in test reporter instead of Test Monkey, so you can see debug output.)npm run end-to-end-tests-in-browser: the end-to-end tests in Playwright’s UI mode.npm run startup-benchmark: the start-up benchmark.npm run rehearsal: the reset and all fifteen scenarios of the automatic updates rehearsal, or the reset and the scenarios whose numbers you pass (e.g.,npm run rehearsal -- 1 2 14).
(Use npm run -s to silence npm’s own output.)
These scripts run other checks:
npm run typecheck: TypeScript (see Types).npm run unimported: modules that the entry points in .unimportedrc.json don’t reach.npm run coverage: unit test coverage of src/ and web/.
The regression and end-to-end suites test the installed Kitten, not the source, so run ./install first. (The test scripts whose names don’t contain without-install, e.g., npm test, do this for you.)
Note that installing restarts the Kitten servers that are running in development (see Kitten Process Manager), including the servers of a test suite that is running.
Source code: