mockaton 8.20.0 → 8.20.2

package/README.md

@@ -1,25 +1,43 @@
-<img src="src/mockaton-logo.svg" alt="Mockaton Logo" width="210" style="margin-top: 30px"/>
+<img src="src/logo.svg" alt="Mockaton Logo" width="210" style="margin-top: 30px"/>
 
 ![NPM Version](https://img.shields.io/npm/v/mockaton)
 ![NPM Version](https://img.shields.io/npm/l/mockaton)
 [![Test](https://github.com/ericfortis/mockaton/actions/workflows/test.yml/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/test.yml)
 [![CodeQL](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql)
 
-An HTTP mock server for simulating APIs with minimal setup
-&mdash; ideal for testing difficult to reproduce backend states.
+An HTTP mock server for simulating APIs with minimal setup &mdash; ideal for testing
+difficult to reproduce states. For example, triggering an error on a third-party API.
+Similarly, if you are a frontend developer, triggering it on your project’s backend.
 
+<br/>
+
+## Motivation
+
+**No API state should be too hard to test.**
+With Mockaton, developers can achieve correctness without sacrificing speed.
+
+### Correctness
+- Enables testing of complex or rare scenarios that would otherwise be skipped.
+- Allows for deterministic, comprehensive, and consistent state.
+
+### Speed
+- Prevents progress from being blocked by waiting for APIs.
+- Avoids spinning up and updating hefty backends when developing UIs.
+
+<br/>
 
 ## Overview
 With Mockaton, you don’t need to write code for wiring up your
 mocks. Instead, a given directory is scanned for filenames
-following a convention similar to the URLs. 
+following a convention similar to the URLs.
 
-For example, for [/api/user/123](#), the mock filename could be:
+For example, for [/api/user/123](#), the filename could be:
 
 <pre>
 <code>my-mocks-dir/<b>api/user</b>/[user-id].GET.200.json</code>
 </pre>
 
+<br/>
 
 ## Dashboard
 
@@ -62,30 +80,34 @@ api/videos.GET.<b>500</b>.txt               # Internal Server Error
 
 <br/>
 
-## Scraping mocks from your Backend
+## Scraping Mocks from your Backend
 
 ### Option 1: Browser Extension
-This [browser extension](https://github.com/ericfortis/download-http-requests-browser-ext)
-lets you download all the HTTP responses, and they
+This companion [browser-devtools extension](https://github.com/ericfortis/download-http-requests-browser-ext)
+lets you download all the HTTP responses at once, and they
 get saved following Mockaton’s filename convention.
 
 ### Option 2: Fallback to Your Backend
-This option could be a bit elaborate if your backend uses third-party auth, 
+<details>
+<summary>Details</summary>
+
+This option could be a bit elaborate if your backend uses third-party auth,
 because you’d have to manually inject cookies or `sessionStorage` tokens.
 
 On the other hand, proxying to your backend is straightforward if your backend
-handles the session cookie, or if you can develop without auth. 
+handles the session cookie, or if you can develop without auth.
 
 Either way you can forward requests to your backend for routes you don’t have
 mocks for, or routes that have the ☁️ **Cloud Checkbox** checked. In addition, by
 checking ✅ **Save Mocks**, you can collect the responses that hit your backend.
 They will be saved in your `config.mocksDir` following the filename convention.
+</details>
 
 
 <br/>
 
 
-## Basic Usage (See below for Node < 23.6)
+## Basic Usage
 ```sh
 npm install mockaton --save-dev
 ```
@@ -95,23 +117,25 @@ Create a `my-mockaton.js` file
 import { resolve } from 'node:path'
 import { Mockaton } from 'mockaton'
 
-// See the Config section for more options
 Mockaton({
   mocksDir: resolve('my-mocks-dir'), // must exist
   port: 2345
-})
+}) // The Config section below documents more options
 ```
 
 ```sh
 node my-mockaton.js
 ```
 
-### TypeScript with Node < 23.6
+<details>
+<summary>About TypeScript in Node < 23.6</summary>
 If you want to write mocks in TypeScript in a version older than Node 23.6:
+
 ```shell
 npm install tsx
 node --import=tsx my-mockaton.js
 ```
+</details>
 
 
 <br/>
@@ -128,11 +152,13 @@ npm run start # in another terminal
 ```
 
 The demo app has a list of colors containing all of their possible states. For example,
-permutations for out-of-stock, new-arrival, and discontinued. It looks like this:
+permutations for out-of-stock, new-arrival, and discontinued.
 
 <img src="./demo-app-vite/pixaton-tests/pic-for-readme.vp740x880.light.gold.png" alt="Mockaton Demo App Screenshot" width="740" />
 
 <br/>
+<br/>
+
 
 ## Use Cases
 ### Testing Backend or Frontend
@@ -163,21 +189,12 @@ putting its built assets in `config.staticDir`. And simulate the flow by Bulk Se
 The [aot-fetch-demo repo](https://github.com/ericfortis/aot-fetch-demo) has a working example.
 
 
-<br/>
-
-## Motivation
-- Avoids spinning up and updating hefty backends when developing UIs.
-- Allows for a deterministic, comprehensive, and consistent backend state. For example, having
-  a collection with all the possible state variants helps for spotting inadvertent bugs.
-- Sometimes frontend progress is blocked by waiting for backend APIs.
-
 <br/>
 
 
 ## You can write JSON mocks in JavaScript or TypeScript
 For example, `api/foo.GET.200.js`
 
-
 **Option A:** An Object, Array, or String is sent as JSON.
 
 ```js
@@ -189,7 +206,7 @@ export default { foo: 'bar' }
 Return a `string | Buffer | Uint8Array`, but don’t call `response.end()`
 
 ```js
-export default (request, response) => 
+export default (request, response) =>
   JSON.stringify({ foo: 'bar' })
 ```
 
@@ -206,6 +223,7 @@ you want to concatenate newly added colors.
 ```js
 import { parseJSON } from 'mockaton'
 
+
 export default async function insertColor(request, response) {
   const color = await parseJSON(request)
   globalThis.newColorsDatabase ??= []
@@ -223,6 +241,7 @@ export default async function insertColor(request, response) {
 ```js
 import colorsFixture from './colors.json' with { type: 'json' }
 
+
 export default function listColors() {
   return JSON.stringify([
     ...colorsFixture,
@@ -305,7 +324,7 @@ A filename can have many comments.
 <br/>
 
 ### Default mock for a route
-You can add the comment: `(default)`. 
+You can add the comment: `(default)`.
 Otherwise, the first file in **alphabetical order** wins.
 
 <pre>
@@ -322,7 +341,8 @@ api/video<b>?limit=[limit]</b>.GET.200.json
 </pre>
 
 On Windows, filenames containing "?" are [not
-permitted](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file), but since that’s part of the query string it’s ignored anyway.
+permitted](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file), but since that’s part of the query
+string it’s ignored anyway.
 
 <br/>
 
@@ -353,9 +373,9 @@ it’s convenient for serving 200 GET requests without having to add the filenam
 extension convention. For example, for using Mockaton as a standalone demo server,
 as explained above in the _Use Cases_ section.
 
-Files under `config.staticDir` don’t use the filename convention, and they take
-precedence over corresponding `GET` mocks in `config.mocksDir` (regardless
-of status code). For example, if you have two files for `GET /foo/bar.jpg`:
+Files under `config.staticDir` take precedence over corresponding
+`GET` mocks in `config.mocksDir` (regardless of status code).
+For example, if you have two files for `GET /foo/bar.jpg`:
 <pre>
 my-static-dir<b>/foo/bar.jpg</b> <span style="color:green"> // Wins</span>
  my-mocks-dir<b>/foo/bar.jpg</b>.GET.200.jpg <span style="color:red"> // Unreachable</span>
@@ -365,7 +385,9 @@ my-static-dir<b>/foo/bar.jpg</b> <span style="color:green"> // Wins</span>
 <br/>
 
 ### `ignore?: RegExp`
-Defaults to `/(\.DS_Store|~)$/`
+Defaults to `/(\.DS_Store|~)$/`. The regex rule is
+tested against the basename (filename without directory path).
+
 
 <br/>
 
@@ -378,13 +400,13 @@ Defaults to `0`, which means auto-assigned
 
 <br/>
 
-### `delay?: number` 
+### `delay?: number`
 Defaults to `1200` milliseconds. Although routes can individually be delayed
 with the 🕓 Checkbox, the amount is globally configurable with this option.
 
 ### `delayJitter?: number`
 Defaults to `0`. Range: `[0.0, 3.0]`. Maximum percentage of the delay to add.
-For example, `0.5` will add at most `600ms` to the default delay.   
+For example, `0.5` will add at most `600ms` to the default delay.
 
 <br/>
 
@@ -396,7 +418,7 @@ or that you manually picked with the ☁️ **Cloud Checkbox**.
 
 ### `collectProxied?: boolean`
 Defaults to `false`. With this flag you can save mocks that hit
-your proxy fallback to `config.mocksDir`. If the URL has v4 UUIDs, 
+your proxy fallback to `config.mocksDir`. If the URL has v4 UUIDs,
 the filename will have `[id]` in their place. For example:
 
 <pre>
@@ -423,7 +445,7 @@ the predefined list. For that, you can add it to <code>config.extraMimes</code>
 
 
 ### `formatCollectedJSON?: boolean`
-Defaults to `true`. Saves the mock with two spaces indentation &mdash; 
+Defaults to `true`. Saves the mock with two spaces indentation &mdash;
 the formatting output of `JSON.stringify(data, null, '  ')`
 
 
@@ -435,6 +457,7 @@ the formatting output of `JSON.stringify(data, null, '  ')`
 ```js
 import { jwtCookie } from 'mockaton'
 
+
 config.cookies = {
   'My Admin User': 'my-cookie=1;Path=/;SameSite=strict',
   'My Normal User': 'my-cookie=0;Path=/;SameSite=strict',
@@ -449,7 +472,7 @@ The selected cookie, which is the first one by default, is sent in every respons
 `Set-Cookie` header (as long as its value is not an empty string). The object key is just
 a label for UI display purposes, and also for selecting a cookie via the Commander API.
 
-If you need to send more than one cookie, you can inject them globally 
+If you need to send more than one cookie, you can inject them globally
 in `config.extraHeaders`, or individually in a function `.js` or `.ts` mock.
 
 By the way, the `jwtCookie` helper has a hardcoded header and signature.
@@ -509,12 +532,13 @@ import { parse } from 'yaml'
 import { readFileSync } from 'node:js'
 import { jsToJsonPlugin } from 'mockaton'
 
+
 config.plugins = [
-  
+
   // Although `jsToJsonPlugin` is set by default, you need to include it if you need it.
   // IOW, your plugins array overwrites the default list. This way you can remove it.
-  [/\.(js|ts)$/, jsToJsonPlugin], 
-  
+  [/\.(js|ts)$/, jsToJsonPlugin],
+
   [/\.yml$/, yamlToJsonPlugin],
   [/foo\.GET\.200\.txt$/, capitalizePlugin], // e.g. GET /api/foo would be capitalized
 ]
@@ -575,6 +599,7 @@ All of its methods return their `fetch` response promise.
 ```js
 import { Commander } from 'mockaton'
 
+
 const myMockatonAddr = 'http://localhost:2345'
 const mockaton = new Commander(myMockatonAddr)
 ```
@@ -649,11 +674,17 @@ example, if you are polling, and you want to test the state change.
 - Chrome DevTools allows for [overriding responses](https://developer.chrome.com/docs/devtools/overrides)
 - Reverse Proxies such as [Burp](https://portswigger.net/burp) are also handy for overriding responses
 
-### Client side
+### Client Side
 In contrast to Mockaton, which is an HTTP Server, these programs
-mock the client (e.g., `fetch`) in Node.js and browsers.
+hijack the client (e.g., `fetch`) in Node.js and browsers.
 
-- [MSW (Mock Server Worker)](https://mswjs.io)
+- [Mock Server Worker (MSW)](https://mswjs.io)
 - [Nock](https://github.com/nock/nock)
 - [Fetch Mock](https://github.com/wheresrhys/fetch-mock)
 - [Mentoss](https://github.com/humanwhocodes/mentoss) Has a server side too
+
+<br/>
+
+---
+
+![](./fixtures-mocks/api/user/avatar.GET.200.png)

package/index.d.ts

@@ -55,33 +55,31 @@ export function jwtCookie(cookieName: string, payload: any, path?: string): stri
 
 export function parseJSON(request: IncomingMessage): Promise<any>
 
+export type JsonPromise<T> = Promise<Response & { json(): Promise<T> }>
 
-export class Commander {
-	constructor(addr: string)
 
-	listMocks(): Promise<Response>
+// API
 
-	select(file: string): Promise<Response>
-
-	bulkSelectByComment(comment: string): Promise<Response>
-
-
-	setRouteIsDelayed(routeMethod: string, routeUrlMask: string, delayed: boolean): Promise<Response>
-
-
-	listCookies(): Promise<Response>
-
-	selectCookie(cookieKey: string): Promise<Response>
-
-
-	listComments(): Promise<Response>
-
-	setProxyFallback(proxyAddr: string): Promise<Response>
-
-	reset(): Promise<Response>
+export type ClientMockBroker = {
+	mocks: string[]
+	currentMock: {
+		file: string
+		delayed: boolean
+	}
+}
+export type ClientBrokersByMethod = {
+	[method: string]: {
+		[urlMask: string]: ClientMockBroker
+	}
+}
 
+export type ClientStaticBroker = {
+	route: string
+	delayed: boolean
+	status: number
+}
+export type ClientStaticBrokers = {
+	[route: string]: ClientStaticBroker
+}
 
-	getCorsAllowed(): Promise<Response>
 
-	setCorsAllowed(value: boolean): Promise<Response>
-}

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "8.20.0",
+	"version": "8.20.2",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
@@ -18,12 +18,12 @@
 	"scripts": {
 		"test": "node --test \"src/**/*.test.js\"",
 		"coverage": "node --test --test-reporter=lcov --test-reporter-destination=.coverage/lcov.info --experimental-test-coverage \"src/**/*.test.js\"",
-		"start": "node dev-mockaton.js",
+		"start": "node --watch dev-mockaton.js",
 		"pixaton": "node --test --import=./pixaton-tests/_setup.js --experimental-test-isolation=none \"pixaton-tests/**/*.test.js\"",
 		"outdated": "npm outdated --parseable | awk -F: '{ printf \"npm i %-30s ;# %s\\n\", $4, $2 }'"
 	},
 	"optionalDependencies": {
-		"open": "^10.0.0"
+		"open": "^10"
 	},
 	"devDependencies": {
 		"pixaton": "1.1.2",

package/src/Api.js

@@ -20,7 +20,7 @@ const dashboardAssets = [
 	'/Dashboard.css',
 	'/Dashboard.js',
 	'/Filename.js',
-	'/mockaton-logo.svg'
+	'/logo.svg'
 ]
 
 export const apiGetRequests = new Map([
@@ -101,7 +101,7 @@ function longPollClientSyncVersion(req, response) {
 
 function reinitialize(_, response) {
 	mockBrokersCollection.init()
-	staticCollection.init() // TESTME
+	staticCollection.init()
 	sendOK(response)
 }
 
@@ -131,17 +131,17 @@ async function setRouteIsDelayed(req, response) {
 		body[DF.routeMethod],
 		body[DF.routeUrlMask])
 
-	if (!broker) // TESTME
+	if (!broker)
 		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeMethod]} ${body[DF.routeUrlMask]}`)
 	else if (typeof delayed !== 'boolean')
-		sendUnprocessableContent(response, `Expected a boolean for "delayed"`) // TESTME
+		sendUnprocessableContent(response, `Expected boolean for "delayed"`)
 	else {
 		broker.setDelayed(delayed)
 		sendOK(response)
 	}
 }
 
-async function setRouteIsProxied(req, response) { // TESTME
+async function setRouteIsProxied(req, response) {
 	const body = await parseJSON(req)
 	const proxied = body[DF.proxied]
 	const broker = mockBrokersCollection.brokerByRoute(
@@ -151,7 +151,7 @@ async function setRouteIsProxied(req, response) { // TESTME
 	if (!broker)
 		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeMethod]} ${body[DF.routeUrlMask]}`)
 	else if (typeof proxied !== 'boolean')
-		sendUnprocessableContent(response, `Expected a boolean for "proxied"`)
+		sendUnprocessableContent(response, `Expected boolean for "proxied"`)
 	else if (proxied && !config.proxyFallback)
 		sendUnprocessableContent(response, `There’s no proxy fallback`)
 	else {
@@ -163,10 +163,10 @@ async function setRouteIsProxied(req, response) { // TESTME
 async function updateProxyFallback(req, response) {
 	const fallback = await parseJSON(req)
 	if (!ConfigValidator.proxyFallback(fallback)) {
-		sendUnprocessableContent(response)
+		sendUnprocessableContent(response, `Invalid Proxy Fallback URL`)
 		return
 	}
-	if (!fallback) // TESTME
+	if (!fallback)
 		mockBrokersCollection.ensureAllRoutesHaveSelectedMock()
 	config.proxyFallback = fallback
 	sendOK(response)
@@ -174,8 +174,8 @@ async function updateProxyFallback(req, response) {
 
 async function setCollectProxied(req, response) {
 	const collectProxied = await parseJSON(req)
-	if (!ConfigValidator.collectProxied(collectProxied)) { // TESTME
-		sendUnprocessableContent(response)
+	if (!ConfigValidator.collectProxied(collectProxied)) {
+		sendUnprocessableContent(response, `Expected a boolean for "collectProxied"`)
 		return
 	}
 	config.collectProxied = collectProxied
@@ -188,12 +188,22 @@ async function bulkUpdateBrokersByCommentTag(req, response) {
 }
 
 async function setCorsAllowed(req, response) {
-	config.corsAllowed = await parseJSON(req)
+	const corsAllowed = await parseJSON(req)
+	if (!ConfigValidator.corsAllowed(corsAllowed)) {
+		sendUnprocessableContent(response, `Expected boolean for "corsAllowed"`)
+		return
+	}
+	config.corsAllowed = corsAllowed
 	sendOK(response)
 }
 
-async function setGlobalDelay(req, response) { // TESTME
-	config.delay = parseInt(await parseJSON(req), 10)
+async function setGlobalDelay(req, response) {
+	const delay = await parseJSON(req)
+	if (!ConfigValidator.delay(delay)) {
+		sendUnprocessableContent(response, `Expected non-negative integer for "delay"`)
+		return
+	}
+	config.delay = delay
 	sendOK(response)
 }
 
@@ -203,10 +213,10 @@ async function setStaticRouteStatusCode(req, response) {
 	const status = Number(body[DF.statusCode])
 	const broker = staticCollection.brokerByRoute(body[DF.routeUrlMask])
 
-	if (!broker) // TESTME
-		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeUrlMask]}`)
+	if (!broker)
+		sendUnprocessableContent(response, `Static route does not exist: ${body[DF.routeUrlMask]}`)
 	else if (!(status === 200 || status === 404))
-		sendUnprocessableContent(response, `Expected a 200 or 404 status code. Received ${status}`) // TESTME
+		sendUnprocessableContent(response, `Expected 200 or 404 status code`)
 	else {
 		broker.setStatus(status)
 		sendOK(response)
@@ -219,10 +229,10 @@ async function setStaticRouteIsDelayed(req, response) {
 	const delayed = body[DF.delayed]
 	const broker = staticCollection.brokerByRoute(body[DF.routeUrlMask])
 
-	if (!broker) // TESTME
-		sendUnprocessableContent(response, `Route does not exist: ${body[DF.routeUrlMask]}`)
+	if (!broker)
+		sendUnprocessableContent(response, `Static route does not exist: ${body[DF.routeUrlMask]}`)
 	else if (typeof delayed !== 'boolean')
-		sendUnprocessableContent(response, `Expected a boolean for "delayed". Received ${delayed}`) // TESTME
+		sendUnprocessableContent(response, `Expected boolean for "delayed"`)
 	else {
 		broker.setDelayed(delayed)
 		sendOK(response)

package/src/Commander.js

@@ -18,13 +18,65 @@ export class Commander {
 		})
 	}
 
+	/** @type {JsonPromise<ClientBrokersByMethod>} */
 	listMocks() {
 		return this.#get(API.mocks)
 	}
 
+	/** @type {JsonPromise<ClientStaticBrokers>} */
+	listStaticFiles() {
+		return this.#get(API.static)
+	}
+
+	/** @type {JsonPromise<[label:string, selected:boolean][]>} */
+	listCookies() {
+		return this.#get(API.cookies)
+	}
+
+	/** @type {JsonPromise<string[]>} */
+	listComments() {
+		return this.#get(API.comments)
+	}
+
+	/** @type {JsonPromise<string>} */
+	getProxyFallback() {
+		return this.#get(API.fallback)
+	}
+
+	/** @type {JsonPromise<boolean>} */
+	getCollectProxied() {
+		return this.#get(API.collectProxied)
+	}
+
+	/** @type {JsonPromise<boolean>} */
+	getCorsAllowed() {
+		return this.#get(API.cors)
+	}
+
+	/** @type {JsonPromise<number>} */
+	getGlobalDelay() {
+		return this.#get(API.globalDelay)
+	}
+
+	/** @type {JsonPromise<number>} */
+	getSyncVersion(currentSyncVersion, abortSignal) {
+		return fetch(API.syncVersion, {
+			signal: AbortSignal.any([abortSignal, AbortSignal.timeout(LONG_POLL_SERVER_TIMEOUT + 1000)]),
+			headers: {
+				[DF.syncVersion]: currentSyncVersion
+			}
+		})
+	}
+
+
+	reset() {
+		return this.#patch(API.reset)
+	}
+
 	select(file) {
 		return this.#patch(API.select, file)
 	}
+
 	bulkSelectByComment(comment) {
 		return this.#patch(API.bulkSelect, comment)
 	}
@@ -59,59 +111,23 @@ export class Commander {
 		})
 	}
 
-	listCookies() {
-		return this.#get(API.cookies)
-	}
 	selectCookie(cookieKey) {
 		return this.#patch(API.cookies, cookieKey)
 	}
 
-	listComments() {
-		return this.#get(API.comments)
-	}
-
-	getProxyFallback() {
-		return this.#get(API.fallback)
-	}
 	setProxyFallback(proxyAddr) {
 		return this.#patch(API.fallback, proxyAddr)
 	}
 
-	getCollectProxied() {
-		return this.#get(API.collectProxied)
-	}
 	setCollectProxied(shouldCollect) {
 		return this.#patch(API.collectProxied, shouldCollect)
 	}
 
-	getCorsAllowed() {
-		return this.#get(API.cors)
-	}
 	setCorsAllowed(value) {
 		return this.#patch(API.cors, value)
 	}
 
-	getGlobalDelay() {
-		return this.#get(API.globalDelay)
-	}
 	setGlobalDelay(delay) {
 		return this.#patch(API.globalDelay, delay)
 	}
-
-	listStaticFiles() {
-		return this.#get(API.static)
-	}
-
-	reset() {
-		return this.#patch(API.reset)
-	}
-
-	getSyncVersion(currentSyncVersion, abortSignal) {
-		return fetch(API.syncVersion, {
-			signal: AbortSignal.any([abortSignal, AbortSignal.timeout(LONG_POLL_SERVER_TIMEOUT + 1000)]),
-			headers: {
-				[DF.syncVersion]: currentSyncVersion
-			}
-		})
-	}
 }