mockaton 8.6.0 → 8.7.0

package/README.md

@@ -5,50 +5,55 @@
 
 ## Mock your APIs, Enhance your Development Workflow
 
-_Mockaton_ is an HTTP mock server built for improving the frontend 
-development and testing experience.
+Welcome to developer experience tooling! Mockaton is here to help
+make your frontend development and testing easier—and a lot more fun.
 
-With Mockaton you don’t need to write code for wiring your mocks. Instead, it
-scans a given directory for filenames following a convention similar to the
-URL paths. For example, the following file will be served on `/api/user/1234`
+With Mockaton you don’t need to write code for wiring your mocks. Instead, just
+place your mocks in a directory and let Mockaton do the rest. It will automatically
+scan the directory for filenames that follow a convention similar to the URL paths.
+
+For example, for this route `/api/user/1234`, the mock filename would be:
 ```
 my-mocks-dir/api/user/[user-id].GET.200.json
 ```
 
-By the way, you don’t need to mock all your APIs. You can request from
-your backend the routes you don’t have mocks for. That’s done with:
+And hey, no need to mock everything. Mockaton can fallback to your real
+backend on routes you don’t have mocks for. Just type your backend
+address in the **Fallback Backend** field. Check **Save Mocks** so you
+can collect those responses that hit your fallback server. The mocks will
+be saved to your `config.mocksDir` following the filename convention.
 
-`config.proxyFallback = 'http://mybackend'`
 
-## Scraping Mocks
-You can save mocks following the filename convention
-for the routes that reached your `proxyFallback` with:
+## Multiple Mock Variants
+Here’s how you can create multiple mocks for a particular route: 
 
-`config.collectProxied = true` 
+### Adding comments in filenames
+Want to mock a locked-out user or an invalid login attempt? You
+can just add a comment to the filename in parentheses. For example:
 
+`api/login(locked out user).POST.423.json`
 
-## Multiple Mock Variants
-Each route can have many mocks, which could either be:
-- Different response __status code__. For example, for triggering errors.
-- __Comment__ on the filename, which is anything within parentheses.
-  - e.g. `api/login(locked out user).POST.423.json`
+### Different response status code
+For instance, you can have mocks with a `4xx` or `5xx` status code for triggering
+error responses. Or with a `204` (No Content) for testing empty collections.
 
 
 ## Dashboard
-
-In the dashboard you can select a mock variant for a particular
-route, among other options. In addition, there’s a programmatic API,
+In the dashboard you can select a mock variant for a particular route, among
+other features such as delaying responses, or triggering an autogenerated
+`500` (Internal Server Error). Nonetheless, there’s a programmatic API,
 which is handy for setting up tests  (see **Commander API** below).
 
 <picture>
-  <source media="(prefers-color-scheme: light)" srcset="./pixaton-tests/pic-for-readme.vp1024x800.light.gold.png">
-  <source media="(prefers-color-scheme: dark)" srcset="./pixaton-tests/pic-for-readme.vp1024x800.dark.gold.png">
-  <img alt="Mockaton Dashboard" src="./pixaton-tests/pic-for-readme.vp1024x800.light.gold.png">
+  <source media="(prefers-color-scheme: light)" srcset="./pixaton-tests/pic-for-readme.vp860x800.light.gold.png">
+  <source media="(prefers-color-scheme: dark)" srcset="./pixaton-tests/pic-for-readme.vp860x800.dark.gold.png">
+  <img alt="Mockaton Dashboard" src="./pixaton-tests/pic-for-readme.vp860x800.light.gold.png">
 </picture>
 
 
+
 ## Basic Usage
-`tsx` is only needed if you want to write mocks in TypeScript
+`tsx` is only needed if you want to write mocks in TypeScript.
 ```sh
 npm install mockaton tsx --save-dev
 ```
@@ -72,7 +77,12 @@ node --import=tsx my-mockaton.js
 
 ## Running the demo app (Vite)
 
-This is a minimal React + Vite + Mockaton app.
+This is a minimal React + Vite + Mockaton app. It’s mainly a list of
+colors, which contains all of their possible states. For example,
+permutations for out-of-stock, new-arrival, and discontinued.
+
+Also, if you select the **Admin User** from the Mockaton dashboard,
+the color cards will have a Delete button as well.
 
 ```sh  
 git clone https://github.com/ericfortis/mockaton.git
@@ -82,9 +92,11 @@ npm run mockaton
 npm run start
 ```
 
-By the way, that directory has a script for opening Mockaton and Vite in one command.
+By the way, that directory has scripts for opening Mockaton and Vite in one command.
+
+The app looks like this:
 
-<img src="./demo-app-vite/README-screenshot.png" alt="Mockaton Demo App Screenshot" style="max-width: 600px" />
+<img src="./demo-app-vite/pixaton-tests/pic-for-readme.vp500x800.light.gold.png" alt="Mockaton Demo App Screenshot" width="500" />
 
 
 ## Use Cases
@@ -107,7 +119,7 @@ backends to old API contracts or databases.
 Perhaps you need to demo your app, but the ideal flow is too complex to
 simulate from the actual backend. In this case, compile your frontend app and
 put its built assets in `config.staticDir`. Then, on the dashboard
-"Bulk Select" mocks to simulate the complete states you want to demo.
+**Bulk Select** mocks to simulate the complete states you want to demo.
 For bulk-selecting, you just need to add a comment to the mock
 filename, such as `(demo-part1)`, `(demo-part2)`.
 
@@ -453,7 +465,7 @@ Nonetheless, you can trigger any command besides opening a browser.
 ---
 
 ## Commander API
-`Commander` is a wrapper for the Mockaton HTTP API.
+`Commander` is a client for Mockaton’s HTTP API.
 All of its methods return their `fetch` response promise.
 ```js
 import { Commander } from 'mockaton'

package/index.d.ts

@@ -27,12 +27,12 @@ interface Config {
 	plugins?: [filenameTester: RegExp, plugin: Plugin][]
 
 	corsAllowed?: boolean,
-	corsOrigins: string[]
-	corsMethods: string[]
-	corsHeaders: string[]
-	corsExposedHeaders: string[]
-	corsCredentials: boolean
-	corsMaxAge: number
+	corsOrigins?: string[]
+	corsMethods?: string[]
+	corsHeaders?: string[]
+	corsExposedHeaders?: string[]
+	corsCredentials?: boolean
+	corsMaxAge?: number
 
 	onReady?: (address: string) => void
 }

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing frontend clients",
 	"type": "module",
-	"version": "8.6.0",
+	"version": "8.7.0",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
@@ -16,6 +16,9 @@
 	},
 	"optionalDependencies": {
 		"pixaton": ">=1.0.2",
-		"puppeteer": ">=23.10.1"
+		"puppeteer": ">=24.1.1"
+	},
+	"devDependencies": {
+		"pixaton": "1.0.2"
 	}
 }

package/src/Api.js

@@ -90,7 +90,7 @@ async function selectMock(req, response) {
 	try {
 		const file = await parseJSON(req)
 		const broker = mockBrokersCollection.getBrokerByFilename(file)
-		if (!broker || !broker.mockExists(file))
+		if (!broker || !broker.hasMock(file))
 			throw `Missing Mock: ${file}`
 		broker.updateFile(file)
 		sendOK(response)

package/src/Commander.js

@@ -1,6 +1,7 @@
 import { API, DF } from './ApiConstants.js'
 
 
+// Client for controlling Mockaton via its HTTP API
 export class Commander {
 	#addr = ''
 	constructor(addr) {

package/src/Dashboard.js

@@ -47,7 +47,7 @@ const refPayloadViewerFileTitle = useRef()
 const mockaton = new Commander(window.location.origin)
 
 function init() {
-	Promise.all([
+	return Promise.all([
 		mockaton.listMocks(),
 		mockaton.listCookies(),
 		mockaton.listComments(),
@@ -98,13 +98,12 @@ function CookieSelector({ list }) {
 		r('label', { className: CSS.Field },
 			r('span', null, Strings.cookie),
 			r('select', {
-					autocomplete: 'off',
-					disabled,
-					title: disabled ? Strings.cookie_disabled_title : '',
-					onChange
-				},
-				list.map(([value, selected]) =>
-					r('option', { value, selected }, value)))))
+				autocomplete: 'off',
+				disabled,
+				title: disabled ? Strings.cookie_disabled_title : '',
+				onChange
+			}, list.map(([value, selected]) =>
+				r('option', { value, selected }, value)))))
 }
 
 
@@ -122,14 +121,13 @@ function BulkSelector({ comments }) {
 		r('label', { className: CSS.Field },
 			r('span', null, Strings.bulk_select_by_comment),
 			r('select', {
-					'data-qaid': 'BulkSelector',
-					autocomplete: 'off',
-					disabled,
-					title: disabled ? Strings.bulk_select_by_comment_disabled_title : '',
-					onChange
-				},
-				list.map(value =>
-					r('option', { value }, value)))))
+				'data-qaid': 'BulkSelector',
+				autocomplete: 'off',
+				disabled,
+				title: disabled ? Strings.bulk_select_by_comment_disabled_title : '',
+				onChange
+			}, list.map(value =>
+				r('option', { value }, value)))))
 }
 
 
@@ -145,7 +143,7 @@ function ProxyFallbackField({ fallbackAddress = '', collectProxied }) {
 				.catch(onError)
 	}
 	return (
-		r('div', { className: CSS.Field + ' ' + CSS.FallbackBackend },
+		r('div', { className: cssClass(CSS.Field, CSS.FallbackBackend) },
 			r('label', null,
 				r('span', null, Strings.fallback_server),
 				r('input', {
@@ -203,13 +201,9 @@ function StaticFilesList({ staticFiles }) {
 				className: CSS.StaticFilesList
 			},
 			r('summary', null, Strings.static),
-			r('ul', null,
-				staticFiles.map(f =>
-					r('li', null,
-						r('a', {
-							href: f,
-							target: '_blank'
-						}, f))))))
+			r('ul', null, staticFiles.map(f =>
+				r('li', null,
+					r('a', { href: f, target: '_blank' }, f))))))
 }
 
 
@@ -221,7 +215,7 @@ function SectionByMethod({ method, brokers }) {
 				.filter(([, broker]) => broker.mocks.length > 1) // >1 because of autogen500
 				.sort((a, b) => a[0].localeCompare(b[0]))
 				.map(([urlMask, broker]) =>
-					r('tr', null,
+					r('tr', { 'data-method': method, 'data-urlMask': urlMask },
 						r('td', null, r(PreviewLink, { method, urlMask })),
 						r('td', null, r(MockSelector, { broker })),
 						r('td', null, r(DelayRouteToggler, { broker })),
@@ -237,9 +231,7 @@ function PreviewLink({ method, urlMask }) {
 				empty(refPayloadViewer.current)
 				refPayloadViewer.current.append(ProgressBar())
 			}, 180)
-			const res = await fetch(this.href, {
-				method: this.getAttribute('data-method')
-			})
+			const res = await fetch(this.href, { method })
 			document.querySelector(`.${CSS.PreviewLink}.${CSS.chosen}`)?.classList.remove(CSS.chosen)
 			this.classList.add(CSS.chosen)
 			clearTimeout(spinner)
@@ -252,7 +244,7 @@ function PreviewLink({ method, urlMask }) {
 
 			empty(refPayloadViewerFileTitle.current)
 			refPayloadViewerFileTitle.current.append(PayloadViewerTitle({
-				file: this.closest('tr').querySelector('select').value
+				file: mockSelectorFor(method, urlMask).value
 			}))
 		}
 		catch (error) {
@@ -263,7 +255,6 @@ function PreviewLink({ method, urlMask }) {
 		r('a', {
 			className: CSS.PreviewLink,
 			href: urlMask,
-			'data-method': method,
 			onClick
 		}, urlMask))
 }
@@ -301,14 +292,14 @@ function updatePayloadViewer(body, mime) {
 
 function MockSelector({ broker }) {
 	function onChange() {
-		const { status } = parseFilename(this.value)
+		const { status, urlMask, method } = parseFilename(this.value)
 		this.style.fontWeight = this.value === this.options[0].value // default is selected
 			? 'normal'
 			: 'bold'
 		mockaton.select(this.value)
 			.then(() => {
-				this.closest('tr').querySelector('a').click()
-				this.closest('tr').querySelector(`.${CSS.InternalServerErrorToggler}>[type=checkbox]`).checked = status === 500
+				linkFor(method, urlMask)?.click()
+				checkbox500For(method, urlMask).checked = status === 500
 				this.className = className(this.value === this.options[0].value, status)
 			})
 			.catch(onError)
@@ -329,17 +320,16 @@ function MockSelector({ broker }) {
 
 	return (
 		r('select', {
-				'data-qaid': urlMask,
-				autocomplete: 'off',
-				className: className(selected === files[0], status),
-				disabled: files.length <= 1,
-				onChange
-			},
-			files.map(file =>
-				r('option', {
-					value: file,
-					selected: file === selected
-				}, file))))
+			'data-qaid': urlMask,
+			autocomplete: 'off',
+			className: className(selected === files[0], status),
+			disabled: files.length <= 1,
+			onChange
+		}, files.map(file =>
+			r('option', {
+				value: file,
+				selected: file === selected
+			}, file))))
 }
 
 
@@ -373,10 +363,12 @@ function TimerIcon() {
 
 function InternalServerErrorToggler({ broker }) {
 	function onChange(event) {
+		const { urlMask, method } = parseFilename(broker.mocks[0])
 		mockaton.select(event.currentTarget.checked
 			? broker.mocks.find(f => parseFilename(f).status === 500)
 			: broker.mocks[0])
 			.then(init)
+			.then(() => linkFor(method, urlMask)?.click())
 			.catch(onError)
 	}
 	return (
@@ -395,6 +387,19 @@ function InternalServerErrorToggler({ broker }) {
 	)
 }
 
+function trFor(method, urlMask) {
+	return document.querySelector(`tr[data-method="${method}"][data-urlMask="${urlMask}"]`)
+}
+function linkFor(method, urlMask) {
+	return trFor(method, urlMask)?.querySelector(`a.${CSS.PreviewLink}`)
+}
+function checkbox500For(method, urlMask) {
+	return trFor(method, urlMask)?.querySelector(`.${CSS.InternalServerErrorToggler} > input`)
+}
+function mockSelectorFor(method, urlMask) {
+	return trFor(method, urlMask)?.querySelector(`select.${CSS.MockSelector}`)
+}
+
 
 function onError(error) {
 	if (error?.message === 'Failed to fetch')

package/src/MockBroker.js

@@ -19,10 +19,7 @@ export class MockBroker {
 	}
 
 	register(file) {
-		if (this.mockExists(file))
-			return
-		const { status } = parseFilename(file)
-		if (status === 500) {
+		if (parseFilename(file).status === 500) {
 			this.#deleteTemp500()
 			if (this.temp500IsSelected)
 				this.updateFile(file)
@@ -84,7 +81,7 @@ export class MockBroker {
 		this.updateFile(this.mocks[0])
 	}
 
-	mockExists(file) { return this.mocks.includes(file) }
+	hasMock(file) { return this.mocks.includes(file) }
 	updateFile(filename) { this.currentMock.file = filename }
 	updateDelay(delayed) { this.currentMock.delay = Number(delayed) * config.delay }
 

package/src/Mockaton.js

@@ -17,13 +17,13 @@ export function Mockaton(options) {
 	mockBrokerCollection.init()
 
 	watch(config.mocksDir, { recursive: true, persistent: false },
-		function handleAddedOrDeletedMocks(_, filename) {
-			if (!filename)
+		function handleAddedOrDeletedMocks(_, file) {
+			if (!file)
 				return
-			if (existsSync(join(config.mocksDir, filename)))
-				mockBrokerCollection.registerMock(filename, 'ensureItHas500')
+			if (existsSync(join(config.mocksDir, file)))
+				mockBrokerCollection.registerMock(file, 'ensureItHas500')
 			else
-				mockBrokerCollection.unregisterMock(filename)
+				mockBrokerCollection.unregisterMock(file)
 		})
 
 	return createServer(onRequest).listen(config.port, config.host, function (error) {

package/src/config.js

@@ -5,6 +5,7 @@ import { StandardMethods } from './utils/http-request.js'
 import { validateCorsAllowedMethods, validateCorsAllowedOrigins } from './utils/http-cors.js'
 
 
+/** @type {Config} */
 export const config = Object.seal({
 	mocksDir: '',
 	staticDir: '',

package/src/mockBrokersCollection.js

@@ -6,11 +6,15 @@ import { parseFilename, filenameIsValid } from './Filename.js'
 
 
 /**
+ * @type {{
+ * [method: string]:
+ *   { [route: string]: MockBroker }
+ * }}
  * @example
  * {
  *   GET: {
- *     /api/route-a: <MockBroker>
- *     /api/route-b: <MockBroker>
+ *     '/api/route-a': mockBrokerA,
+ *     '/api/route-b': mockBrokerB
  *   },
  *   POST: {…}
  * }
@@ -32,7 +36,9 @@ export function init() {
 }
 
 export function registerMock(file, shouldEnsure500) {
-	if (config.ignore.test(file) || !filenameIsValid(file))
+	if (getBrokerByFilename(file)?.hasMock(file)
+		|| config.ignore.test(file)
+		|| !filenameIsValid(file))
 		return
 
 	const { method, urlMask } = parseFilename(file)