mockaton 11.0.0 → 11.0.2

package/Makefile

@@ -6,23 +6,23 @@ watch:
 
 
 test:
-	node --test 'src/**/*.test.js'
+	@MOCKATON_WATCHER_DEBOUNCE_MS=0 node --test 'src/**/*.test.js'
 
 test-docker:
-	docker run --rm -it \
-		-v "$$PWD":/app \
-		-w /app \
+	@docker run --rm --interactive --tty \
+		--volume .:/app \
+		--workdir /app \
 		node:24 \
 		make test
 
 coverage:
-	node --test --experimental-test-coverage \
+	@MOCKATON_WATCHER_DEBOUNCE_MS=0 node --test --experimental-test-coverage \
 		--test-reporter=spec --test-reporter-destination=stdout \
 		--test-reporter=lcov --test-reporter-destination=lcov.info \
 		'src/**/*.test.js'
 
 pixaton:
-	node --test --experimental-test-isolation=none \
+	@node --test --experimental-test-isolation=none \
 		--import=./pixaton-tests/_setup.js \
 		'pixaton-tests/**/*.test.js'
 

package/README.md

@@ -77,7 +77,7 @@ get saved following Mockaton’s filename convention.
 
 ### Option 2: Fallback to Your Backend
 <details>
-<summary>Details</summary>
+<summary>Learn more…</summary>
 
 This option could be a bit elaborate if your backend uses third-party authentication,
 because you’d have to manually inject cookies or `sessionStorage` tokens.
@@ -93,7 +93,12 @@ They will be saved in your `config.mocksDir` following the filename convention.
 
 <br/>
 
+<br/>
+
+
 ## Motivation
+<details>
+<summary>Motivation…</summary>
 
 **No API state should be too hard to test.**
 With Mockaton, developers can achieve correctness and speed.
@@ -116,27 +121,54 @@ With Mockaton, developers can achieve correctness and speed.
   - checking out long-lived branches
   - bisecting bugs
 
+</details>
+
+
+
+## Use Cases
+<details>
+<summary>Use Cases…</summary>
+
+### Testing Backend or Frontend
+- Empty responses
+- Errors such as _Bad Request_ and _Internal Server Error_
+- Mocking third-party APIs
+- Polled resources (for triggering their different states)
+  - alerts
+  - notifications
+  - slow to build resources
+
+### Testing Frontend
+- Spinners by delaying responses
+- Setting up UI tests
+
+### Demoing complex backend states
+Sometimes, the ideal flow you need is too difficult to reproduce from the actual backend.
+For this, you can **Bulk Select** mocks by comments to simulate the complete states
+you want. For example, by adding `(demo-part1)`, `(demo-part2)` to the filenames.
+
+Similarly, you can deploy a **Standalone Demo Server** by compiling the frontend app and
+putting its built assets in `config.staticDir`. And simulate the flow by Bulk Selecting mocks.
+The [aot-fetch-demo repo](https://github.com/ericfortis/aot-fetch-demo) has a working example.
+
+</details>
 
 <br/>
 
-## Privacy and Security
-- Zero dependencies (no runtime and no build packages).
-- Does not write to disk. Except when you select ✅ **Save Mocks** for scraping mocks from a backend.
-- Does not initiate network connections (no logs, no telemetry).
-- Does not hijack your HTTP client.
-- Auditable. Organized and small &mdash; under 4 KLoC (half is UI and tests).
+
 
 <br/>
 
 ## Basic Usage
-1. Install Node.js, which comes with `npm` and `npx`
+
+1. Install Node.js (v22.18+ support writing mocks in TypeScript)
 
 2. Create a sample mock in the default mocks directory (`./mockaton-mocks`)
 ```sh
 mkdir -p         mockaton-mocks/api
 echo "[1,2,3]" > mockaton-mocks/api/foo.GET.200.json
 ```
-3. Run Mockaton (`npx` installs it if needed)
+3. Run Mockaton (`npx` comes with Node, and installs Mockaton if needed)
 ```shell
 npx mockaton --port 2345
 ```
@@ -146,6 +178,16 @@ npx mockaton --port 2345
 curl localhost:2345/api/foo 
 ```
 
+5. Optionally, use a `mockaton.config.js`
+```js
+import { defineConfig } from 'mockaton'
+
+export default defineConfig({
+  port: 2345,
+})
+```
+
+
 ### Alternative Installations
 <details>
 <summary>With NPM (package.json)…</summary>
@@ -184,6 +226,9 @@ ln -s `realpath mockaton/src/cli.js` ~/bin/mockaton # some dir in your $PATH
 ## CLI Options
 The CLI options override their counterparts in `mockaton.config.js`
 
+<details>
+<summary>CLI Options…</summary>
+
 ```txt
 -c, --config <file>    (default: ./mockaton.config.js)
 
@@ -199,10 +244,17 @@ The CLI options override their counterparts in `mockaton.config.js`
 -h, --help             Show this help
 -v, --version          Show version
 ```
+</details>
 
 
 ## mockaton.config.js (Optional)
+Mockaton looks for a file `mockaton.config.js` in its current working directory.
+
+<details>
+<summary>Defaults Overview… </summary>
+
 As an overview, these are the defaults:
+
 ```js
 import {
   defineConfig,
@@ -249,8 +301,10 @@ export default defineConfig({
 })
 ```
 
+</details>
+
 <details>
-<summary><b>Config Documentation</b></summary>
+<summary>Config Documentation…</summary>
 
 ### `mocksDir?: string`
 Defaults to `'mockaton-mocks'`. 
@@ -498,7 +552,7 @@ Defaults to `'normal'`.
 
 
 <details>
-<summary>Programmatic Launch (Optional)</summary>
+<summary>Programmatic Launch (Optional)…</summary>
 
 
 ```js
@@ -535,32 +589,6 @@ permutations for out-of-stock, new-arrival, and discontinued.
 <br/>
 
 
-## Use Cases
-### Testing Backend or Frontend
-- Empty responses
-- Errors such as _Bad Request_ and _Internal Server Error_
-- Mocking third-party APIs
-- Polled resources (for triggering their different states)
-  - alerts
-  - notifications
-  - slow to build resources
-
-### Testing Frontend
-- Spinners by delaying responses
-- Setting up UI tests
-
-### Demoing complex backend states
-Sometimes, the ideal flow you need is too difficult to reproduce from the actual backend.
-For this, you can **Bulk Select** mocks by comments to simulate the complete states
-you want. For example, by adding `(demo-part1)`, `(demo-part2)` to the filenames.
-
-Similarly, you can deploy a **Standalone Demo Server** by compiling the frontend app and
-putting its built assets in `config.staticDir`. And simulate the flow by Bulk Selecting mocks.
-The [aot-fetch-demo repo](https://github.com/ericfortis/aot-fetch-demo) has a working example.
-
-
-<br/>
-
 
 ## You can write JSON mocks in JavaScript or TypeScript
 For example, `api/foo.GET.200.js`
@@ -840,6 +868,16 @@ await mockaton.reset()
 </details>
 
 
+<br/>
+
+## Privacy and Security
+- Zero dependencies (no runtime and no build packages).
+- Does not write to disk. Except when you select ✅ **Save Mocks** for scraping mocks from a backend.
+- Does not initiate network connections (no logs, no telemetry).
+- Does not hijack your HTTP client.
+- Auditable. Organized and small &mdash; under 4 KLoC (half is UI and tests).
+
+
 <br/>
 
 ## Alternatives worth learning as well
@@ -861,6 +899,12 @@ hijack the HTTP client in Node.js and browsers.
 - [Fetch Mock](https://github.com/wheresrhys/fetch-mock)
 - [Mentoss](https://github.com/humanwhocodes/mentoss) Has a server side too
 
+### Server Side
+
+- [Wire Mock](https://github.com/wiremock/wiremock)
+- [Mock](https://github.com/dhuan/mock)
+- [Swagger](https://swagger.io/)
+
 <br/>
 
 ---

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "11.0.0",
+	"version": "11.0.2",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
@@ -23,5 +23,8 @@
 	"devDependencies": {
 		"pixaton": "1.1.3",
 		"puppeteer": "24.24.1"
+	},
+	"engines": {
+		"node": ">=22.18 <23 || >=23.6"
 	}
 }

package/src/Api.js

@@ -13,7 +13,7 @@ import * as mockBrokersCollection from './mockBrokersCollection.js'
 import { config, ConfigValidator } from './config.js'
 import { DashboardHtml, CSP } from './DashboardHtml.js'
 import { sendOK, sendJSON, sendUnprocessableContent, sendFile, sendHTML } from './utils/http-response.js'
-import { API, LONG_POLL_SERVER_TIMEOUT, HEADER_FOR_SYNC_VERSION } from './ApiConstants.js'
+import { API, LONG_POLL_SERVER_TIMEOUT, HEADER_SYNC_VERSION } from './ApiConstants.js'
 
 
 export const apiGetRequests = new Map([
@@ -81,7 +81,8 @@ function getState(_, response) {
 
 
 function longPollClientSyncVersion(req, response) {
-	if (uiSyncVersion.version !== Number(req.headers[HEADER_FOR_SYNC_VERSION])) {
+	const clientVersion = req.headers[HEADER_SYNC_VERSION]
+	if (clientVersion !== undefined && uiSyncVersion.version !== Number(clientVersion)) {
 		// e.g., tab was hidden while new mocks were added or removed
 		sendJSON(response, uiSyncVersion.version)
 		return
@@ -111,9 +112,9 @@ function reinitialize(_, response) {
 
 
 async function selectCookie(req, response) {
-	const label = await parseJSON(req)
+	const cookieKey = await parseJSON(req)
 
-	const error = cookie.setCurrent(label)
+	const error = cookie.setCurrent(cookieKey)
 	if (error)
 		sendUnprocessableContent(response, error?.message || error)
 	else

package/src/ApiCommander.js

@@ -1,4 +1,4 @@
-import { API, LONG_POLL_SERVER_TIMEOUT, HEADER_FOR_SYNC_VERSION } from './ApiConstants.js'
+import { API, LONG_POLL_SERVER_TIMEOUT, HEADER_SYNC_VERSION } from './ApiConstants.js'
 
 
 /** Client for controlling Mockaton via its HTTP API */
@@ -9,78 +9,49 @@ export class Commander {
 		this.#addr = addr
 	}
 
-	#patch = (api, body) =>
-		fetch(this.#addr + api, {
-			method: 'PATCH',
-			body: JSON.stringify(body)
-		})
-
 	/** @returns {JsonPromise<State>} */
 	getState = () =>
 		fetch(this.#addr + API.state)
 
-	/** @returns {JsonPromise<number>} */
-	getSyncVersion = (currSyncVer, abortSignal) =>
+	/** 
+	 * @param {number?} currSyncVer - On mismatch, it responds immediately. Otherwise, long polls.
+	 * @param {AbortSignal} abortSignal
+	 * @returns {JsonPromise<number>}
+	 */
+	getSyncVersion = (currSyncVer = undefined, abortSignal = undefined) =>
 		fetch(this.#addr + API.syncVersion, {
 			signal: AbortSignal.any([
 				abortSignal,
 				AbortSignal.timeout(LONG_POLL_SERVER_TIMEOUT + 1000)
-			]),
-			headers: {
-				[HEADER_FOR_SYNC_VERSION]: currSyncVer
-			}
+			].filter(Boolean)),
+			headers: currSyncVer !== undefined 
+				? { [HEADER_SYNC_VERSION]: currSyncVer } 
+				: {}
 		})
 
 
-	reset() {
-		return this.#patch(API.reset)
-	}
-
-	select(file) {
-		return this.#patch(API.select, file)
-	}
-
-	toggle500(method, urlMask) {
-		return this.#patch(API.toggle500, [method, urlMask])
-	}
-
-	bulkSelectByComment(comment) {
-		return this.#patch(API.bulkSelect, comment)
-	}
-
-	setRouteIsDelayed(method, urlMask, delayed) {
-		return this.#patch(API.delay, [method, urlMask, delayed])
-	}
-
-	setStaticRouteIsDelayed(urlMask, delayed) {
-		return this.#patch(API.delayStatic, [urlMask, delayed])
-	}
-
-	setStaticRouteStatus(urlMask, status) {
-		return this.#patch(API.staticStatus, [urlMask, status])
-	}
-
-	setRouteIsProxied(method, urlMask, proxied) {
-		return this.#patch(API.proxied, [method, urlMask, proxied])
+	#patch(api, body) {
+		return fetch(this.#addr + api, {
+			method: 'PATCH',
+			body: JSON.stringify(body)
+		})
 	}
 
-	selectCookie(cookieKey) {
-		return this.#patch(API.cookies, cookieKey)
-	}
+	reset = () => this.#patch(API.reset)
 
-	setProxyFallback(proxyAddr) {
-		return this.#patch(API.fallback, proxyAddr)
-	}
+	selectCookie = label => this.#patch(API.cookies, label)
+	setGlobalDelay = delay => this.#patch(API.globalDelay, delay)
+	setCorsAllowed = value => this.#patch(API.cors, value)
+	setProxyFallback = proxyAddr => this.#patch(API.fallback, proxyAddr)
+	setCollectProxied = shouldCollect => this.#patch(API.collectProxied, shouldCollect)
 
-	setCollectProxied(shouldCollect) {
-		return this.#patch(API.collectProxied, shouldCollect)
-	}
+	select = file => this.#patch(API.select, file)
+	bulkSelectByComment = comment => this.#patch(API.bulkSelect, comment)
 
-	setCorsAllowed(value) {
-		return this.#patch(API.cors, value)
-	}
+	toggle500 = (method, urlMask) => this.#patch(API.toggle500, [method, urlMask])
+	setRouteIsProxied = (method, urlMask, proxied) => this.#patch(API.proxied, [method, urlMask, proxied])
+	setRouteIsDelayed = (method, urlMask, delayed) => this.#patch(API.delay, [method, urlMask, delayed])
 
-	setGlobalDelay(delay) {
-		return this.#patch(API.globalDelay, delay)
-	}
+	setStaticRouteStatus = (urlMask, status) => this.#patch(API.staticStatus, [urlMask, status])
+	setStaticRouteIsDelayed = (urlMask, delayed) => this.#patch(API.delayStatic, [urlMask, delayed])
 }

package/src/ApiConstants.js

@@ -1,6 +1,7 @@
 const MOUNT = '/mockaton'
 export const API = {
 	dashboard: MOUNT,
+	
 	bulkSelect: MOUNT + '/bulk-select-by-comment',
 	collectProxied: MOUNT + '/collect-proxied',
 	cookies: MOUNT + '/cookies',
@@ -19,9 +20,9 @@ export const API = {
 	toggle500: MOUNT + '/toggle500'
 }
 
-export const HEADER_FOR_502 = 'Mockaton502'
-export const HEADER_FOR_SYNC_VERSION = 'sync_version'
+export const HEADER_502 = 'Mockaton502'
+export const HEADER_SYNC_VERSION = 'sync_version'
 
 export const DEFAULT_MOCK_COMMENT = '(default)'
-export const EXT_FOR_UNKNOWN_MIME = 'unknown'
+export const UNKNOWN_MIME_EXT = 'unknown'
 export const LONG_POLL_SERVER_TIMEOUT = 8_000

package/src/Dashboard.js

@@ -1,5 +1,5 @@
 import { createElement as r, createSvgElement as s, className, restoreFocus, Defer, Fragment } from './DashboardDom.js'
-import { HEADER_FOR_502 } from './ApiConstants.js'
+import { HEADER_502 } from './ApiConstants.js'
 import { parseFilename } from './Filename.js'
 import { store } from './DashboardStore.js'
 
@@ -448,7 +448,7 @@ function StaticRow(row) {
 			!groupByMethod && r('td', className(CSS.Method),
 				'GET'),
 
-			r('td', null,
+			r('td', { colspan: 2 },
 				r('a', {
 					href: row.urlMask,
 					target: '_blank',
@@ -593,7 +593,7 @@ function PayloadViewerTitle(file, statusText) {
 
 function PayloadViewerTitleWhenProxied(response) {
 	const mime = response.headers.get('content-type') || ''
-	const badGateway = response.headers.get(HEADER_FOR_502)
+	const badGateway = response.headers.get(HEADER_502)
 	return (
 		r('span', null,
 			badGateway
@@ -734,7 +734,7 @@ function SettingsIcon() {
  * The version increments when a mock file is added, removed, or renamed.
  */
 function initRealTimeUpdates() {
-	let oldVersion = -1
+	let oldVersion = undefined
 	let controller = new AbortController()
 
 	longPoll()
@@ -755,11 +755,9 @@ function initRealTimeUpdates() {
 					ErrorToast.close()
 
 				const version = await response.json()
-				const skipUpdate = oldVersion === -1
 				if (oldVersion !== version) { // because it could be < or >
 					oldVersion = version
-					if (!skipUpdate)
-						store.fetchState()
+					store.fetchState()
 				}
 				longPoll()
 			}

package/src/Filename.js

@@ -1,16 +1,10 @@
 const httpMethods = [ // @KeepSync with node:http.METHODS
-	'ACL', 'BIND', 'CHECKOUT',
-	'CONNECT', 'COPY', 'DELETE',
-	'GET', 'HEAD', 'LINK',
-	'LOCK', 'M-SEARCH', 'MERGE',
-	'MKACTIVITY', 'MKCALENDAR', 'MKCOL',
-	'MOVE', 'NOTIFY', 'OPTIONS',
-	'PATCH', 'POST', 'PROPFIND',
-	'PROPPATCH', 'PURGE', 'PUT',
-	'QUERY', 'REBIND', 'REPORT',
-	'SEARCH', 'SOURCE', 'SUBSCRIBE',
-	'TRACE', 'UNBIND', 'UNLINK',
-	'UNLOCK', 'UNSUBSCRIBE'
+	'ACL', 'BIND', 'CHECKOUT', 'CONNECT', 'COPY', 'DELETE',
+	'GET', 'HEAD', 'LINK', 'LOCK', 'M-SEARCH', 'MERGE',
+	'MKACTIVITY', 'MKCALENDAR', 'MKCOL', 'MOVE', 'NOTIFY', 'OPTIONS',
+	'PATCH', 'POST', 'PROPFIND', 'PROPPATCH', 'PURGE', 'PUT',
+	'QUERY', 'REBIND', 'REPORT', 'SEARCH', 'SOURCE', 'SUBSCRIBE',
+	'TRACE', 'UNBIND', 'UNLINK', 'UNLOCK', 'UNSUBSCRIBE'
 ]
 
 const reComments = /\(.*?\)/g // Anything within parentheses

package/src/MockBroker.js

@@ -4,7 +4,7 @@ import { DEFAULT_MOCK_COMMENT } from './ApiConstants.js'
 
 /** 
  * MockBroker is a state for a particular route. It knows the available mock 
- * files that can be served for the route, and the currently selected file, etc.
+ * files that can be served for the route, the currently selected file, etc.
  */
 export class MockBroker {
 	constructor(file) {
@@ -114,7 +114,7 @@ class UrlMatcher {
 	}
 
 	#disregardVariables(str) { // Stars out all parts that are in square brackets
-		return str.replace(/\[.*?]/g, '[^/]*')
+		return str.replace(/\[.*?]/g, '[^/]+')
 	}
 
 	// Appending a '/' so URLs ending with variables don't match

package/src/Mockaton.js

@@ -1,7 +1,7 @@
 import { createServer } from 'node:http'
 
-import { logger } from './utils/logger.js'
 import { API } from './ApiConstants.js'
+import { logger } from './utils/logger.js'
 import { config, setup } from './config.js'
 import { dispatchMock } from './MockDispatcher.js'
 import { dispatchStatic } from './StaticDispatcher.js'

package/src/Watcher.js

@@ -15,6 +15,7 @@ import * as mockBrokerCollection from './mockBrokersCollection.js'
  * and also renames, which are two events (delete + add).
  */
 export const uiSyncVersion = new class extends EventEmitter {
+	delay = Number(process.env.MOCKATON_WATCHER_DEBOUNCE_MS ?? 80)
 	version = 0
 
 	increment = this.#debounce(() => {
@@ -33,7 +34,7 @@ export const uiSyncVersion = new class extends EventEmitter {
 		let timer
 		return () => {
 			clearTimeout(timer)
-			timer = setTimeout(fn, 80)
+			timer = setTimeout(fn, this.delay)
 		}
 	}
 }
@@ -64,7 +65,7 @@ export function watchStaticDir() {
 	const dir = config.staticDir
 	if (!dir)
 		return
-	
+
 	watch(dir, { recursive: true, persistent: false }, (_, file) => {
 		if (!file)
 			return

package/src/mockBrokersCollection.js

@@ -109,7 +109,7 @@ export function extractAllComments() {
 		for (const c of b.extractComments())
 			comments.add(c)
 	})
-	return Array.from(comments)
+	return Array.from(comments).sort()
 }
 
 export function setMocksMatchingComment(comment) {

package/src/utils/http-request.js

@@ -50,6 +50,7 @@ export function readBody(req, parser = a => a) {
 }
 
 export const reControlAndDelChars = /[\x00-\x1f\x7f]/
+
 export function hasControlChars(url) {
 	try {
 		const decoded = decode(url)

package/src/utils/http-response.js

@@ -1,7 +1,7 @@
 import fs, { readFileSync } from 'node:fs'
 import { logger } from './logger.js'
 import { mimeFor } from './mime.js'
-import { HEADER_FOR_502 } from '../ApiConstants.js'
+import { HEADER_502 } from '../ApiConstants.js'
 
 
 export function sendOK(response) {
@@ -69,7 +69,7 @@ export function sendInternalServerError(response, error) {
 export function sendBadGateway(response, error) {
 	logger.warn('Fallback Proxy Error:', error.cause.message)
 	response.statusCode = 502
-	response.setHeader(HEADER_FOR_502, 1)
+	response.setHeader(HEADER_502, 1)
 	response.end()
 }
 

package/src/utils/mime.js

@@ -1,5 +1,5 @@
 import { config } from '../config.js'
-import { EXT_FOR_UNKNOWN_MIME } from '../ApiConstants.js'
+import { UNKNOWN_MIME_EXT } from '../ApiConstants.js'
 
 
 // Generated with:
@@ -119,7 +119,7 @@ export function extFor(mime) {
 function findExt(rawMime) {
 	const m = parseMime(rawMime)
 	const extraMimeToExt = mapMimeToExt(config.extraMimes)
-	return extraMimeToExt[m] || mimeToExt[m] || EXT_FOR_UNKNOWN_MIME
+	return extraMimeToExt[m] || mimeToExt[m] || UNKNOWN_MIME_EXT
 }
 
 export function parseMime(mime) {