mockaton 8.3.4 → 8.4.0

package/README.md

@@ -3,8 +3,10 @@
 ![NPM Version](https://img.shields.io/npm/v/mockaton)
 ![NPM Version](https://img.shields.io/npm/l/mockaton)
 
+## Mock your APIs, Enhance your Development Workflow
 
-_Mockaton_ is a mock server for improving the frontend development and testing experience.
+_Mockaton_ is an HTTP mock server built for improving the frontend 
+development and testing experience.
 
 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
@@ -13,13 +15,17 @@ URL paths. For example, the following file will be served on `/api/user/1234`
 my-mocks-dir/api/user/[user-id].GET.200.json
 ```
 
-## Scraping Mocks
-You don’t need to mock all your APIs. Mockaton can request
-from your backend the routes you don’t have mocks for. That’s done with:
+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:
 
 `config.proxyFallback = 'http://mybackend'`
 
-`config.collectProxied = true` lets you save those responses as mocks following the filename convention.
+## Scraping Mocks
+You can save mocks following the filename convention
+for the routes that reached your `proxyFallback` with:
+
+`config.collectProxied = true` 
+
 
 ## Multiple Mock Variants
 Each route can have many mocks, which could either be:
@@ -28,9 +34,9 @@ Each route can have many mocks, which could either be:
   - e.g. `api/login(locked out user).POST.423.json`
 
 
-## Dashboard UI
+## Dashboard
 
-In the dashboard, you can select a mock variant for a particular
+In the dashboard you can select a mock variant for a particular
 route, among other options. In addition, there’s a programmatic API,
 which is handy for setting up tests  (see **Commander API** below).
 
@@ -64,7 +70,7 @@ node --import=tsx my-mockaton.js
 ```
 
 
-## Running the Demo Example
+## Running the Built-in Demo
 This demo uses the [sample-mocks/](./sample-mocks) of this repository.
 
 ```sh  
@@ -80,8 +86,7 @@ Experiment with the Dashboard:
 - Toggle the 🕓 _Delay Responses_ button, (e.g. for testing spinners)
 - Toggle the _500_ button, which sends and _Internal Server Error_ on that endpoint
 
-Finally, edit a mock file in your IDE. You don’t need to restart Mockaton for that.
-The _Reset_ button is for registering newly added, removed, or renamed mocks.
+Finally, edit a mock file in your IDE. You don’t need to restart Mockaton.
 
 
 ## Use Cases
@@ -183,9 +188,7 @@ export default function listColors() {
 ```
 </details>
 
----
-
-If you are wondering, what if I need to serve a static `.js`?
+**What if I need to serve a static .js?**
 Put it in your `config.staticDir` without the mock filename convention.
 
 ---
@@ -194,8 +197,8 @@ Put it in your `config.staticDir` without the mock filename convention.
 
 ### Extension
 
-The last 3 dots are reserved for the HTTP Method,
-Response Status Code, and the File Extension.
+The last three dots are reserved for the HTTP Method,
+Response Status Code, and File Extension.
 
 ```
 api/user.GET.200.json
@@ -235,7 +238,7 @@ api/video<b>?limit=[limit]</b>.GET.200.json
 </pre>
 
 Speaking of which, 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.
 
 
 ### Index-like routes
@@ -272,8 +275,10 @@ Defaults to `/(\.DS_Store|~)$/`
 
 
 ### `delay?: number` 
-Routes can individually be delayed with the 🕓 checkbox. On the other hand, 
-the amount is globally configurable. It defaults to `config.delay=1200` milliseconds.
+Defaults to `config.delay=1200` milliseconds.
+
+Although routes can individually be delayed with the 🕓
+checkbox, delay the amount is globally configurable.
 
 
 ### `proxyFallback?: string`
@@ -290,11 +295,7 @@ URL the filename will have `[id]` in their place. For example,
 my-mocks-dir/api/user/[id]/likes.GET.200.json
 ```
 
-Note that newly saved mocks won’t be served until you
-**register them** by reinitializing Mockaton or clicking "Reset".
-
-Registered mocks won’t be overwritten (they don’t hit the fallback server).
-On the other hand, newly saved mocks get overwritten while they are unregistered.
+Your existing mocks won’t be overwritten (they don’t hit the fallback server).
 
 <details>
   <summary>Extension Details</summary>
@@ -343,7 +344,7 @@ response in a `Set-Cookie` header. If you need to send more
 cookies, inject them globally in `config.extraHeaders`.
 
 By the way, the `jwtCookie` helper has a hardcoded header and signature.
-In other words, it’s useful only if you care about the payload.
+In other words, it’s useful only if you care about its payload.
 
 
 ### `extraHeaders?: string[]`
@@ -490,9 +491,8 @@ await mockaton.setProxyFallback('http://example.com')
 Pass an empty string to disable it.
 
 ### Reset
-Re-initialize the collection. So if you added or removed mocks they will
-be considered. The selected mocks, cookies, and delays go back to default,
-but `config.proxyFallback` and `config.corsAllowed` are not affected.
+Re-initialize the collection. The selected mocks, cookies, and delays go back to
+default, but `config.proxyFallback` and `config.corsAllowed` are not affected.
 ```js
 await mockaton.reset()
 ```

package/TODO.md

@@ -1,7 +1,5 @@
 # TODO
 
 - Refactor tests
-- Rename 'Reset' to 'Reload'
 - Add Collect Proxied checkbox to the dashboard
-- Subscribe button for newly added mocks
-  - or perhaps registering them automatically without full reset?
+- Dashboard refresh (poll?)

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing frontend clients",
 	"type": "module",
-	"version": "8.3.4",
+	"version": "8.4.0",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",

package/src/Dashboard.js

@@ -43,7 +43,7 @@ const refPayloadViewerFileTitle = useRef()
 
 const mockaton = new Commander(window.location.origin)
 
-
+window.onfocus = init
 function init() {
 	Promise.all([
 		mockaton.listMocks(),
@@ -204,7 +204,8 @@ function SectionByMethod({ method, brokers }) {
 		r('tbody', null,
 			r('th', null, method),
 			Object.entries(brokers)
-				.filter(([, broker]) => broker.mocks.length > 1) // Excludes Markdown only routes (>1 because of the autogen500)
+				.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('td', null, r(PreviewLink, { method, urlMask })),

package/src/MockBroker.js

@@ -18,7 +18,37 @@ export class MockBroker {
 		this.register(file)
 	}
 
-	register(file) { this.mocks.push(file) }
+	register(file) {
+		if (this.mockExists(file))
+			return
+		const { status } = parseFilename(file)
+		if (status === 500) {
+			this.#deleteTemp500()
+			if (this.temp500IsSelected)
+				this.updateFile(file)
+		}
+		this.mocks.push(file)
+		this.sortMocks()
+	}
+
+	#deleteTemp500() {
+		this.mocks = this.mocks.filter(file => !this.#isTemp500(file))
+	}
+
+	#registerTemp500() {
+		const { urlMask, method } = parseFilename(this.mocks[0])
+		const file = urlMask.replace(/^\//, '') // Removes leading slash
+		this.mocks.push(`${file}${DEFAULT_500_COMMENT}.${method}.500.empty`)
+	}
+
+	unregister(file) {
+		this.mocks = this.mocks.filter(f => f !== file)
+		const isEmpty = !this.mocks.length
+			|| this.mocks.length === 1 && this.#isTemp500(this.mocks[0])
+		if (!isEmpty && this.file === file)
+			this.selectDefaultFile()
+		return isEmpty
+	}
 
 	// Appending a '/' so URLs ending with variables don't match
 	// URLs that have a path after that variable. For example,
@@ -34,21 +64,24 @@ export class MockBroker {
 	get file() { return this.currentMock.file }
 	get delay() { return this.currentMock.delay }
 	get status() { return parseFilename(this.file).status }
-	get isTemp500() { return includesComment(this.file, DEFAULT_500_COMMENT) }
+	get temp500IsSelected() { return this.#isTemp500(this.file) }
 
-	selectDefaultFile() {
-		const userSpecifiedDefault = this.#findMockWithDefaultComment()
-		if (userSpecifiedDefault) // Sort for dashboard list
-			this.mocks = [
-				userSpecifiedDefault,
-				...this.mocks.filter(m => m !== userSpecifiedDefault)
-			]
-		this.updateFile(userSpecifiedDefault || this.mocks[0])
+	#isTemp500(file) { return includesComment(file, DEFAULT_500_COMMENT) }
+
+	sortMocks() {
+		this.mocks.sort()
+		const defaults = this.mocks.filter(file => includesComment(file, DEFAULT_MOCK_COMMENT))
+		const temp500 = this.mocks.filter(file => includesComment(file, DEFAULT_500_COMMENT))
+		this.mocks = this.mocks.filter(file => !defaults.includes(file) && !temp500.includes(file))
+		this.mocks = [
+			...defaults,
+			...this.mocks,
+			...temp500
+		]
 	}
-	#findMockWithDefaultComment() {
-		for (const f of this.mocks)
-			if (includesComment(f, DEFAULT_MOCK_COMMENT))
-				return f
+
+	selectDefaultFile() {
+		this.updateFile(this.mocks[0])
 	}
 
 	mockExists(file) { return this.mocks.includes(file) }
@@ -77,11 +110,6 @@ export class MockBroker {
 	#has500() {
 		return this.mocks.some(mock => parseFilename(mock).status === 500)
 	}
-	#registerTemp500() {
-		const { urlMask, method } = parseFilename(this.mocks[0])
-		const file = urlMask.replace(/^\//, '') // Removes leading slash
-		this.register(`${file}${DEFAULT_500_COMMENT}.${method}.500.empty`)
-	}
 }
 
 // Stars out (for regex) all the paths that are in square brackets

package/src/MockDispatcher.js

@@ -29,7 +29,7 @@ export async function dispatchMock(req, response) {
 		for (let i = 0; i < config.extraHeaders.length; i += 2)
 			response.setHeader(config.extraHeaders[i], config.extraHeaders[i + 1])
 
-		const { mime, body } = broker.isTemp500
+		const { mime, body } = broker.temp500IsSelected
 			? { mime: '', body: '' }
 			: await applyPlugins(join(config.mocksDir, broker.file), req, response)
 

package/src/Mockaton.js

@@ -1,4 +1,6 @@
+import { join } from 'node:path'
 import { createServer } from 'node:http'
+import { watch, existsSync } from 'node:fs'
 
 import { API } from './ApiConstants.js'
 import { dispatchMock } from './MockDispatcher.js'
@@ -13,6 +15,16 @@ import { apiPatchRequests, apiGetRequests } from './Api.js'
 export function Mockaton(options) {
 	setup(options)
 	mockBrokerCollection.init()
+
+	watch(config.mocksDir, { recursive: true, persistent: false }, (_, filename) => {
+		if (existsSync(join(config.mocksDir, filename))) {
+			const broker = mockBrokerCollection.registerMock(filename)
+			broker.ensureItHas500()
+		}
+		else
+			mockBrokerCollection.unregisterMock(filename)
+	})
+
 	return createServer(onRequest).listen(config.port, config.host, function (error) {
 		const { address, port } = this.address()
 		const url = `http://${address}:${port}`

package/src/Mockaton.test.js

@@ -1,12 +1,11 @@
 import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
 import { promisify } from 'node:util'
 import { describe, it } from 'node:test'
 import { createServer } from 'node:http'
+import { dirname, join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { equal, deepEqual, match } from 'node:assert/strict'
-import { writeFileSync, mkdtempSync, mkdirSync } from 'node:fs'
-
+import { writeFileSync, mkdtempSync, mkdirSync, unlinkSync } from 'node:fs'
 
 import { config } from './config.js'
 import { mimeFor } from './utils/mime.js'
@@ -21,7 +20,6 @@ import { API, DEFAULT_500_COMMENT, DEFAULT_MOCK_COMMENT } from './ApiConstants.j
 
 const tmpDir = mkdtempSync(tmpdir()) + '/'
 const staticTmpDir = mkdtempSync(tmpdir()) + '/'
-console.log(tmpDir)
 
 const fixtureCustomMime = [
 	'/api/custom-mime',
@@ -44,6 +42,29 @@ const fixtureDelayed = [
 	'Route_To_Be_Delayed'
 ]
 
+/* Only fixtures with PUT */
+const fixtureForRegisteringPutA = [
+	'/api/register',
+	'api/register(a).PUT.200.json',
+	'fixture_for_registering_a'
+]
+const fixtureForRegisteringPutB = [
+	'/api/register',
+	'api/register(b).PUT.200.json',
+	'fixture_for_registering_b'
+]
+const fixtureForRegisteringPutA500 = [
+	'/api/register',
+	'api/register.PUT.500.json',
+	'fixture_for_registering_500'
+]
+const fixtureForUnregisteringPutC = [
+	'/api/unregister',
+	'api/unregister.PUT.200.json',
+	'fixture_for_unregistering'
+]
+
+
 const fixtures = [
 	[
 		'/api',
@@ -242,6 +263,8 @@ async function runTests() {
 	await testCorsAllowed()
 	testWindowsPaths()
 
+	await testRegistering()
+
 	server.close()
 }
 
@@ -291,14 +314,82 @@ async function testMockDispatching(url, file, expectedBody, forcedMime = undefin
 async function testDefaultMock() {
 	await testMockDispatching(...fixtureDefaultInName)
 	await it('sorts mocks list with the user specified default first for dashboard display', async () => {
-		const res = await commander.listMocks()
-		const body = await res.json()
-		const { mocks } = body.GET[fixtureDefaultInName[0]]
+		const body = await (await commander.listMocks()).json()
+		const { mocks } = body['GET'][fixtureDefaultInName[0]]
 		equal(mocks[0], fixtureDefaultInName[1])
 		equal(mocks[1], fixtureNonDefaultInName[1])
 	})
 }
 
+async function testRegistering() {
+	await describe('Registering', async () => {
+		const temp500 = `api/register${DEFAULT_500_COMMENT}.PUT.500.empty`
+
+		await it('registering new route creates temp 500 as well and re-registering is a noop', async () => {
+			write(fixtureForRegisteringPutA[1], '')
+			await sleep()
+			write(fixtureForRegisteringPutB[1], '')
+			await sleep()
+			write(fixtureForRegisteringPutA[1], '')
+			await sleep()
+			const collection = await (await commander.listMocks()).json()
+			deepEqual(collection['PUT'][fixtureForRegisteringPutA[0]].mocks, [
+				fixtureForRegisteringPutA[1],
+				fixtureForRegisteringPutB[1],
+				temp500
+			])
+		})
+		await it('registering a 500 removes the temp 500 (and selects the new 500)', async () => {
+			await commander.select(temp500)
+			write(fixtureForRegisteringPutA500[1], '')
+			await sleep()
+			const collection = await (await commander.listMocks()).json()
+			const { mocks, currentMock } = collection['PUT'][fixtureForRegisteringPutA[0]]
+			deepEqual(mocks, [
+				fixtureForRegisteringPutA[1],
+				fixtureForRegisteringPutB[1],
+				fixtureForRegisteringPutA500[1]
+			])
+			deepEqual(currentMock, {
+				file: fixtureForRegisteringPutA500[1],
+				delay: 0
+			})
+		})
+		await it('unregisters selected', async () => {
+			await commander.select(fixtureForRegisteringPutA[1])
+			remove(fixtureForRegisteringPutA[1])
+			await sleep()
+			const collection = await (await commander.listMocks()).json()
+			const { mocks, currentMock } = collection['PUT'][fixtureForRegisteringPutA[0]]
+			deepEqual(mocks, [
+				fixtureForRegisteringPutB[1],
+				fixtureForRegisteringPutA500[1]
+			])
+			deepEqual(currentMock, {
+				file: fixtureForRegisteringPutB[1],
+				delay: 0
+			})
+		})
+		await it('unregistering the last mock removes broker', async () => {
+			write(fixtureForUnregisteringPutC[1], '') // Register another PUT so it doesn't delete PUT from collection
+			await sleep()
+			remove(fixtureForUnregisteringPutC[1])
+			await sleep()
+			const collection = await (await commander.listMocks()).json()
+			equal(collection['PUT'][fixtureForUnregisteringPutC[0]], undefined)
+		})
+
+		await it('unregistering the last PUT mock removes PUT from collection', async () => {
+			remove(fixtureForRegisteringPutB[1])
+			remove(fixtureForRegisteringPutA500[1])
+			await sleep()
+			const collection = await (await commander.listMocks()).json()
+			equal(collection['PUT'], undefined)
+		})
+	})
+}
+
+
 async function testItUpdatesTheCurrentSelectedMock(url, file, expectedStatus, expectedBody) {
 	await commander.select(file)
 	const res = await request(url)
@@ -537,6 +628,10 @@ function write(filename, data) {
 	_write(tmpDir + filename, data)
 }
 
+function remove(filename) {
+	unlinkSync(tmpDir + filename)
+}
+
 function writeStatic(filename, data) {
 	_write(staticTmpDir + filename, data)
 }
@@ -546,3 +641,6 @@ function _write(absPath, data) {
 	writeFileSync(absPath, data, 'utf8')
 }
 
+async function sleep(ms = 50) {
+	return new Promise(resolve => setTimeout(resolve, ms))
+}

package/src/mockBrokersCollection.js

@@ -21,39 +21,58 @@ export function init() {
 	collection = {}
 	cookie.init(config.cookies)
 
-	const files = listFilesRecursively(config.mocksDir)
+	listFilesRecursively(config.mocksDir)
 		.sort()
 		.filter(f => !config.ignore.test(f) && filenameIsValid(f))
-
-	for (const file of files) {
-		const { method, urlMask } = parseFilename(file)
-		collection[method] ??= {}
-		if (!collection[method][urlMask])
-			collection[method][urlMask] = new MockBroker(file)
-		else
-			collection[method][urlMask].register(file)
-	}
+		.forEach(registerMock)
 
 	forEachBroker(broker => {
-		broker.selectDefaultFile()
 		broker.ensureItHas500()
+		broker.selectDefaultFile()
 	})
 }
 
+/** @returns {MockBroker} */
+export function registerMock(file) {
+	const { method, urlMask } = parseFilename(file)
+	collection[method] ??= {}
+	if (!collection[method][urlMask])
+		collection[method][urlMask] = new MockBroker(file)
+	else
+		collection[method][urlMask].register(file)
+	return collection[method][urlMask]
+}
+
+export function unregisterMock(file) {
+	const broker = getBrokerByFilename(file)
+	if (!broker)
+		return
+	const isEmpty = broker.unregister(file)
+	if (isEmpty) {
+		const { method, urlMask } = parseFilename(file)
+		delete collection[method][urlMask]
+		if (!Object.keys(collection[method]).length)
+			delete collection[method]
+	}
+}
 
 export const getAll = () => collection
 
-export const getBrokerByFilename = file => {
+
+/** @returns {MockBroker | undefined} */
+export function getBrokerByFilename(file) {
 	const { method, urlMask } = parseFilename(file)
 	if (collection[method])
 		return collection[method][urlMask]
 }
 
-// Searching the routes in reverse order so dynamic params (e.g.
-// /user/[id]) don’t take precedence over exact paths (e.g.
-// /user/name). That’s because "[]" chars are lower than alphanumeric ones.
-// BTW, `urlMasks` always start with "/", so there’s no need to
-// worry about the primacy of array-like keys when iterating.
+/**
+ * Searching the routes in reverse order so dynamic params (e.g.
+ * /user/[id]) don’t take precedence over exact paths (e.g.
+ * /user/name). That’s because "[]" chars are lower than alphanumeric ones.
+ * BTW, `urlMasks` always start with "/", so there’s no need to
+ * worry about the primacy of array-like keys when iterating.
+ @returns {MockBroker | undefined} */
 export function getBrokerForUrl(method, url) {
 	if (!collection[method])
 		return