mockaton 11.1.2 → 11.1.4

package/Makefile

@@ -1,3 +1,21 @@
+docker: docker-build docker-run
+
+docker-build:
+	@docker build --tag mockaton $(PWD)
+
+docker-run: docker-stop
+	@docker run --name mockaton \
+		--publish 127.0.0.1:2020:2020 \
+		--volume $(PWD)/mockaton.config.js:/app/mockaton.config.js \
+    --volume $(PWD)/mockaton-mocks:/app/mockaton-mocks \
+    --volume $(PWD)/mockaton-static-mocks:/app/mockaton-static-mocks \
+		mockaton
+
+docker-stop:
+	@docker stop mockaton >/dev/null 2>&1 || true
+	@docker rm mockaton >/dev/null 2>&1 || true
+	
+
 start:
 	@node src/cli.js
 
@@ -10,7 +28,7 @@ test:
 
 test-docker:
 	@docker run --rm --interactive --tty \
-		--volume .:/app \
+		--volume $(PWD):/app \
 		--workdir /app \
 		node:24 \
 		make test
@@ -26,8 +44,10 @@ pixaton:
 		--import=./pixaton-tests/_setup.js \
 		'pixaton-tests/**/*.test.js'
 
+
 outdated:
 	@npm outdated --parseable |\
 		awk -F: '{ printf "npm i %-30s ;# %s\n", $$4, $$2 }'
 
+
 .PHONY: *

package/README.md

@@ -6,31 +6,50 @@
 [![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)
 [![codecov](https://codecov.io/github/ericfortis/mockaton/graph/badge.svg?token=90NYLMMG1J)](https://codecov.io/github/ericfortis/mockaton)
 
-
 An HTTP mock server for simulating APIs with minimal setup
-— ideal for testing difficult to reproduce states.
+— ideal for testing difficult to reproduce backend states.
 
 ## 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.
 
-For example, for [/api/user/123](#), the filename could be:
+For example, for [/api/company/123](#), the filename could be:
 
 <pre>
-<code>my-mocks-dir/<b>api/user</b>/[user-id].GET.200.json</code>
+<code>my-mocks-dir/<b>api/company</b>/[company-id].GET.200.json</code>
 </pre>
 
 <br/>
 
-## Dashboard
 
-On the dashboard you can select a mock variant for a particular route, delaying responses,
-or triggering an autogenerated `500` error, among other features.
+## Quick Start (Docker)
+This will spin up Mockaton with the mock directories included in this repo:
+[mockaton-mocks/](./mockaton-mocks) and [mockaton-static-mocks/](./mockaton-static-mocks)
+mounted on the container.
+
+```sh
+git clone https://github.com/ericfortis/mockaton.git --depth 1
+cd mockaton
+make docker
+```
+Dashboard: http://localhost:2020/mockaton
+
+
+Test it:
+```shell
+curl localhost:2020/api/user
+```
+
 
+<br/>
+
+## Dashboard
 
-Nonetheless, there’s a programmatic API, which is handy
-for setting up tests (see **Commander&nbsp;API** section below).
+On the dashboard you can select a mock variant for a particular route,
+🕓 delaying responses, or triggering an autogenerated `500` error, among
+other features. Nonetheless, there’s a programmatic API, which is
+handy for setting up tests (see **Commander&nbsp;API** section below).
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="pixaton-tests/macos/pic-for-readme.vp761x720.light.gold.png">
@@ -54,6 +73,12 @@ api/login<b>(locked out user)</b>.POST.423.json
 api/login<b>(invalid login attempt)</b>.POST.401.json
 </pre>
 
+You can **Bulk Select** mocks by comments to simulate the complete states
+you want. For example:
+
+<img src="docs/bulk-select.png" width="180px">
+
+
 ### Different response status code
 For instance, you can use a `4xx` or `5xx` status code for triggering error
 responses, or a `2xx` such as `204` for testing empty collections.
@@ -69,13 +94,13 @@ api/videos.GET.<b>500</b>.txt   # Internal Server Error
 
 ## Scraping Mocks from your Backend
 
-### Option 1: Browser Extension
+### Option 1: Browser extension
 The companion Chrome [devtools
 extension](https://github.com/ericfortis/download-http-requests-browser-ext)
 lets you download all the HTTP responses, and they
 get saved following Mockaton’s filename convention.
 
-### Option 2: Fallback to Your Backend
+### Option 2: Fallback to your backend
 <details>
 <summary>Learn more…</summary>
 
@@ -97,138 +122,94 @@ They will be saved in your `config.mocksDir` following the filename convention.
 
 
 ## Motivation
-<details>
-<summary>Motivation…</summary>
-
-**No API state should be too hard to test.**
-With Mockaton, developers can achieve correctness and speed.
-
-### Correctness
-- Enables testing of complex scenarios that would otherwise be skipped. e.g.,
-  - Triggering errors on third-party APIs.
-  - Triggering errors on your project’s backend (if you are a frontend developer).
-- Allows for deterministic, comprehensive, and consistent state.
-  - Spot inadvertent regressions during development.
-  - Use it to set up screenshot tests, e.g., with [pixaton](https://github.com/ericfortis/pixaton).
-
-### Speed
-- Works around unstable dev backends while developing UIs.
-  - Spinning up development infrastructure.
-  - Syncing database states.
-- Prevents progress from being blocked by waiting for APIs.
-- Time travel. If you commit the mocks to your repo,
-  you don’t have to downgrade backends for:
-  - checking out long-lived branches
-  - bisecting bugs
 
-</details>
+### Testing scenarios that would otherwise be skipped
+- Simulate errors on third-party APIs, or on your project’s backend (if you are a frontend dev, or unfamiliar with that code)
+- Trigger dynamic states on an API. You can do this by using comments on mock filenames, for example, for polled alerts or notifications.
+- Trigger empty (no content) responses
+- Sometimes, the ideal flow you need is just too difficult to reproduce from the actual backend
+
+### Works around unstable dev backends while developing UIs
+- Spinning up dev infrastructure
+- Syncing the database
+- Mitigates progress from being blocked by waiting for APIs
+
+### Time travel
+If you commit the mocks to your repo, you don’t have to downgrade backends when:
+- Checking out long-lived branches
+- Bisecting bugs
+
+### Deterministic and comprehensive states
+- Ideal for setting up screenshot tests, e.g., with [pixaton](https://github.com/ericfortis/pixaton)
+- Spot inadvertent regressions during development. For example, the demo app in
+  this repo has a list of colors containing all of their possible states, such as
+  permutations for out-of-stock, new-arrival, and discontinued. This way you’ll
+  indirectly notice if something else broke.
 
+<img src="./demo-app-vite/pixaton-tests/pic-for-readme.vp740x880.light.gold.png" alt="Mockaton Demo App Screenshot" width="740" />
 
 
-## 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.
+### Standalone demo server (Docker)
+You can demo your app by compiling the frontend and putting
+its built assets in `config.staticDir`. For example, this
+repo includes a demo which builds and runs a docker container.
 
-</details>
-
-<br/>
+```sh
+git clone https://github.com/ericfortis/mockaton.git --depth 1
+cd mockaton/demo-app-vite
+make start-standalone-demo
+```
+- App: http://localhost:4040
+- Dashboard: http://localhost:4040/mockaton
 
 
+### Privacy and security
+- 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. 4 KLoC (half is UI and tests)
+  - Zero dependencies. No runtime and no build packages.
 
 <br/>
 
-## Basic Usage
 
-1. Install Node.js (v22.18+ support writing mocks in TypeScript)
+## Usage Without Docker
 
-2. Create a sample mock in the default mocks directory (`./mockaton-mocks`)
+Requires Node.js. **v22.18+** support writing mocks in TypeScript.
+
+1. Create a 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` comes with Node, and installs Mockaton if needed)
+2. Run Mockaton (`npx` comes with Node, and installs Mockaton if needed)
 ```shell
-npx mockaton --port 2345
+npx mockaton --port 4040
 ```
 
-4. Test it
+3. Test it
 ```shell
-curl localhost:2345/api/foo 
+curl localhost:4040/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>
-
-```shell
+## Or, on Node Projects
+```sh
 npm install mockaton --save-dev
 ```
 
-Then, add the script to your `package.json`:
+In your `package.json`:
 ```json
-{
-  "scripts": {
-    "mockaton": "mockaton --port 2345"
-  }
+"scripts": {
+  "mockaton": "mockaton --port 4040"
 }
 ```
-</details>
-
-
-<details>
-<summary>Without NPM…</summary>
-
-Since Mockaton has no dependencies, you can create an executable
-by linking to `src/cli.js`.
-
-```shell
-git clone https://github.com/ericfortis/mockaton.git --depth 1
-ln -s `realpath mockaton/src/cli.js` ~/bin/mockaton # some dir in your $PATH
-```
-
-</details>
-
 <br/>
 
 
 ## 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)
 
@@ -241,10 +222,9 @@ The CLI options override their counterparts in `mockaton.config.js`
 -q, --quiet            Errors only
 --no-open              Don’t open dashboard in a browser (noops onReady callback)
 
--h, --help             Show this help
--v, --version          Show version
+-h, --help
+-v, --version
 ```
-</details>
 
 
 ## mockaton.config.js (Optional)
@@ -253,8 +233,6 @@ 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,
@@ -271,9 +249,9 @@ export default defineConfig({
 
   host: '127.0.0.1',
   port: 0,
-  
+
   logLevel: 'normal',
-  
+
   delay: 1200,
   delayJitter: 0,
 
@@ -292,8 +270,8 @@ export default defineConfig({
   corsExposedHeaders: [],
   corsCredentials: true,
   corsMaxAge: 0,
-  
-  
+
+
   plugins: [
     [/\.(js|ts)$/, jsToJsonPlugin]
   ],
@@ -308,7 +286,7 @@ export default defineConfig({
 <summary><b>Config Documentation…</b></summary>
 
 ### `mocksDir?: string`
-Defaults to `'mockaton-mocks'`. 
+Defaults to `'mockaton-mocks'`.
 
 ### `staticDir?: string`
 Defaults to `'mockaton-static-mocks'`.
@@ -338,7 +316,7 @@ The regex rule is tested against the basename (filename without directory path).
 
 
 ### `watcherEnabled?: boolean`
-Defaults to `true` 
+Defaults to `true`
 
 When `false`, if you **add**, **delete**, or **rename** you’ll need to click **"Reset"**
 on the Dashboard, or call `commander.reset()` in order to re-initialize the collection.
@@ -497,7 +475,7 @@ config.plugins = [
   // IOW, your plugins array overwrites the default list. This way you can remove it.
   [/\.(js|ts)$/, jsToJsonPlugin],
 
-  
+
   [/\.yml$/, yamlToJsonPlugin],
 
 
@@ -555,7 +533,7 @@ At any rate, you can trigger any command besides opening a browser.
 
 <br/>
 
-### `logLevel?: 'quiet' | 'normal' | 'verbose'` 
+### `logLevel?: 'quiet' | 'normal' | 'verbose'`
 Defaults to `'normal'`.
 
 - `quiet`: only errors (stderr)
@@ -580,53 +558,39 @@ const server = await Mockaton(
 </details>
 
 
-
 <br/>
 
-## Demo App (Vite + React)
-
-```sh  
-git clone https://github.com/ericfortis/mockaton.git --depth 1
-cd mockaton/demo-app-vite
-npm install 
-
-npm run mockaton
-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.
-
-<img src="./demo-app-vite/pixaton-tests/pic-for-readme.vp740x880.light.gold.png" alt="Mockaton Demo App Screenshot" width="740" />
-
-<br/>
-<br/>
-
-
 
 ## You can write JSON mocks in JavaScript or TypeScript
+_TypeScript mocks need **Node 22.18+ or 23.6+**_
+
 For example, `api/foo.GET.200.js`
 
-**Option A:** An Object, Array, or String is sent as JSON.
+### Option A: An Object, Array, or String is sent as JSON
 
 ```js
 export default { foo: 'bar' }
 ```
 
-**Option B:** Function
+### Option B: Function (async or sync)
 
-Return a `string | Buffer | Uint8Array`, but don’t call `response.end()`
+**Return** a `string | Buffer | Uint8Array`, but **don’t call** `response.end()`
 
 ```js
 export default (request, response) =>
   JSON.stringify({ foo: 'bar' })
 ```
 
-Think of these functions as HTTP handlers. For example,
-you can intercept requests to write to a database.
+#### About Custom HTTP Handlers
+
+For example, you can intercept requests to write to a database. Or
+act based on some query string value, etc. In summary, you get Node’s
+`request`, `response` as arguments, so you can think of Mockaton as a
+router, but in the handlers you return, instead of ending the response.
+
 
 <details>
-<summary><b>See Intercepting Requests Examples</b></summary>
+<summary><b>Examples…</b></summary>
 
 Imagine you have an initial list of colors, and
 you want to concatenate newly added colors.
@@ -668,9 +632,12 @@ export default function listColors() {
 **What if I need to serve a static .js or .ts?**
 
 **Option A:** Put it in your `config.staticDir` without the `.GET.200.js` extension.
+In other words, mocks in `staticDir` take precedence over `mocksDir/*`.
 
 **Option B:** Read it and return it. For example:
 ```js
+import { readFileSync } from 'node:fs'
+
 export default function (_, response) {
   response.setHeader('Content-Type', 'application/javascript')
   return readFileSync('./some-dir/foo.js', 'utf8')
@@ -715,7 +682,7 @@ want a `Content-Type` header in the response.
 <br/>
 
 ### Dynamic parameters
-Anything within square brackets is always matched. 
+Anything within square brackets is always matched.
 
 For example, for <a href="#">/api/company/<b>123</b>/user/<b>789</b></a>,
 the filename could be:
@@ -786,7 +753,7 @@ All of its methods return their `fetch` response promise.
 import { Commander } from 'mockaton'
 
 
-const myMockatonAddr = 'http://localhost:2345'
+const myMockatonAddr = 'http://localhost:4040'
 const mockaton = new Commander(myMockatonAddr)
 ```
 
@@ -872,7 +839,6 @@ await mockaton.setCorsAllowed(true)
 <br/>
 
 
-
 ### Reset
 Re-initialize the collection. The selected mocks, cookies, and delays go back to
 default, but the `proxyFallback`, `colledProxied`, and `corsAllowed` are not affected.
@@ -882,16 +848,6 @@ 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
@@ -901,12 +857,13 @@ These are similar to Mockaton in the sense that you can modify the
 mock response without loosing or risking your frontend code state. For
 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
+- 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. Not easy but
+  very powerful.
 
 ### Client Side
-In contrast to Mockaton, which is an HTTP Server, these programs
-hijack the HTTP client in Node.js and browsers.
+In contrast to Mockaton, which is an HTTP Server, these
+programs hijack your browser’s HTTP client (and Node’s).
 
 - [Mock Server Worker (MSW)](https://mswjs.io)
 - [Nock](https://github.com/nock/nock)
@@ -919,8 +876,9 @@ hijack the HTTP client in Node.js and browsers.
 - [Mock](https://github.com/dhuan/mock)
 - [Swagger](https://swagger.io/)
 
+
+<br/>
 <br/>
 
----
 
 ![](mockaton-mocks/api/user/avatar.GET.200.png)

package/package.json

@@ -2,9 +2,14 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "11.1.2",
-	"main": "index.js",
-	"types": "index.d.ts",
+	"version": "11.1.4",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"import": "./index.js",
+			"types": "./index.d.ts"
+		}
+	},
 	"license": "MIT",
 	"repository": "https://github.com/ericfortis/mockaton",
 	"keywords": [
@@ -22,7 +27,7 @@
 	},
 	"devDependencies": {
 		"pixaton": "1.1.3",
-		"puppeteer": "24.24.1"
+		"puppeteer": "24.29.1"
 	},
 	"engines": {
 		"node": ">=22.18 <23 || >=23.6"

package/src/Dashboard.css

@@ -356,7 +356,6 @@ main {
 				border-color: var(--colorSecondaryActionBorder);
 			}
 		}
-
 	}
 }
 
@@ -377,11 +376,11 @@ table {
 	tr.animIn {
 		opacity: 0;
 		transform: scaleY(0);
-		animation: _kfAnimIn 180ms ease-in-out forwards;
+		animation: _kfRowIn 180ms ease-in-out forwards;
 	}
 }
 
-@keyframes _kfAnimIn {
+@keyframes _kfRowIn {
 	to {
 		opacity: 1;
 		transform: scaleY(1);
@@ -611,10 +610,7 @@ table {
 		> code {
 			white-space: pre;
 			tab-size: 2;
-
-			> .json {
-				color: var(--colorSecondaryAction);
-			}
+			color: var(--colorSecondaryAction);
 
 			.syntaxPunc {
 				color: var(--colorSecondaryAction);

package/src/Dashboard.js

@@ -36,7 +36,6 @@ const CSS = {
 	rightSide: null,
 	status4xx: null,
 
-	json: null,
 	syntaxAttr: null,
 	syntaxAttrVal: null,
 	syntaxKey: null,
@@ -649,8 +648,8 @@ async function updatePayloadViewer(proxied, file, response) {
 		}))
 	else {
 		const body = await response.text() || t`/* Empty Response Body */`
-		if (mime === 'application/json')
-			payloadViewerCodeRef.elem.replaceChildren(r('span', className(CSS.json), SyntaxJSON(body)))
+		if (mime === 'application/json') 
+			payloadViewerCodeRef.elem.replaceChildren(SyntaxJSON(body))
 		else if (isXML(mime))
 			payloadViewerCodeRef.elem.replaceChildren(SyntaxXML(body))
 		else
@@ -755,9 +754,11 @@ function initRealTimeUpdates() {
 					ErrorToast.close()
 
 				const version = await response.json()
+				const shouldSkip = oldVersion === undefined
 				if (oldVersion !== version) { // because it could be < or >
 					oldVersion = version
-					store.fetchState()
+					if (!shouldSkip)
+						store.fetchState()
 				}
 				longPoll()
 			}

package/src/MockDispatcher.js

@@ -31,7 +31,7 @@ export async function dispatchMock(req, response) {
 		if (cookie.getCurrent())
 			response.setHeader('Set-Cookie', cookie.getCurrent())
 
-		for (let i = 0; i < config.extraHeaders.length; i += 2)
+		for (let i = 0; i < config.extraHeaders.length; i += 2) // TESTME
 			response.setHeader(config.extraHeaders[i], config.extraHeaders[i + 1])
 
 		response.statusCode = broker.auto500 ? 500 : broker.status // TESTME plugins can change it

package/src/StaticDispatcher.js

@@ -9,18 +9,19 @@ import { config, calcDelay } from './config.js'
 import { sendMockNotFound, sendPartialContent } from './utils/http-response.js'
 
 
+// TODO HEAD
 export async function dispatchStatic(req, response) {
 	const broker = brokerByRoute(req.url)
 
 	setTimeout(async () => {
-		if (!broker || broker.status === 404) { // TESTME
+		if (!broker || broker.status === 404) {
 			sendMockNotFound(response)
 			return
 		}
 
 		const file = join(config.staticDir, broker.route)
 		if (!isFile(file)) {
-			sendMockNotFound(response) // TESTME
+			sendMockNotFound(response)
 			return
 		}
 		

package/src/mockBrokersCollection.js

@@ -70,7 +70,7 @@ function filenameIsValid(file) {
 
 export function unregisterMock(file) {
 	const broker = brokerByFilename(file)
-	if (!broker)
+	if (!broker) // TESTME
 		return
 	const isEmpty = broker.unregister(file)
 	if (isEmpty) {