mockaton 0.9.5 → 0.9.7

package/Api.js

@@ -97,7 +97,7 @@ async function bulkUpdateBrokersByCommentTag(req, response) {
 async function updateBrokerTransform(req, response) {
 	try {
 		const body = await parseJSON(req)
-		const broker = mockBrokersCollection.getBroker(body[DF.method], body[DF.urlMask])
+		const broker = mockBrokersCollection.getBrokerByFilename(body[DF.file])
 		broker.updateTransform(body[DF.file])
 		sendOK(response)
 	}

package/ApiConstants.js

@@ -15,7 +15,5 @@ export const DF = { // Dashboard Fields (XHR)
 	delayed: 'delayed',
 	file: 'file',
 	currentCookieKey: 'current_cookie_key',
-	isForDashboard: 'mock_request_payload',
-	method: 'method',
-	urlMask: 'url_mask'
+	isForDashboard: 'mock_request_payload'
 }

package/Dashboard.js

@@ -257,15 +257,13 @@ function Transforms({ brokersByMethod }) {
 			r('tr', null,
 				r('td', null, r(PreviewLink, { method: broker.method, urlMask })),
 				r('td', null, r(TransformSelector, {
-					urlMask,
-					method: broker.method,
 					items: ['', ...broker.transforms],
 					selected: broker.currentTransform
 				})))
 		)))
 }
 
-function TransformSelector({ method, urlMask, items, selected }) {
+function TransformSelector({ items, selected }) {
 	const className = defaultIsSelected => cssClass(
 		CSS.TransformSelector,
 		!defaultIsSelected && CSS.bold)
@@ -273,16 +271,10 @@ function TransformSelector({ method, urlMask, items, selected }) {
 		r('select', {
 			className: className(selected === items[0]),
 			autocomplete: 'off',
-			'data-urlMask': urlMask,
-			'data-method': method,
 			onChange() {
 				fetch(DP.transform, {
 					method: 'PATCH',
-					body: JSON.stringify({
-						[DF.file]: this.value,
-						[DF.urlMask]: this.getAttribute('data-urlMask'),
-						[DF.method]: this.getAttribute('data-method')
-					})
+					body: JSON.stringify({ [DF.file]: this.value })
 				}).then(() => {
 					this.closest('tr').querySelector('a').click()
 					this.className = className(this.value === this.options[0].value)

package/MockBroker.js

@@ -20,7 +20,7 @@ export class MockBroker {
 		this.mocks = [] // *.json,txt
 		this.currentMock = {
 			file: '',
-			status: 200,
+			get status() { return Route.parseFilename(this.file).status },
 			delay: 0
 		}
 
@@ -36,10 +36,8 @@ export class MockBroker {
 		else if (file.endsWith('.mjs'))
 			this.transforms.push(file)
 		else {
-			if (!this.mocks.length) {
+			if (!this.mocks.length)
 				this.currentMock.file = file // The first mock file option for a particular route becomes the default
-				this.currentMock.status = Route.parseFilename(file).status
-			}
 			this.mocks.push(file)
 		}
 	}
@@ -52,7 +50,6 @@ export class MockBroker {
 
 	updateFile(filename) {
 		this.currentMock.file = filename
-		this.currentMock.status = Route.parseFilename(filename).status
 	}
 
 	updateDelay(delayed) {
@@ -83,24 +80,24 @@ export class MockBroker {
 		return comments
 	}
 
-	ensureItHas501() {
-		if (!this.#has501())
-			this.#write501()
+	ensureItHas500() {
+		if (!this.#has500())
+			this.#write500()
 	}
 
-	#has501() {
+	#has500() {
 		return this.mocks.some(mock =>
-			Route.parseFilename(mock).status === 501)
+			Route.parseFilename(mock).status === 500)
 	}
 
-	#write501() {
+	#write500() {
 		// TODO handle route with transforms but without mocks
 		const { urlMask, method } = Route.parseFilename(this.mocks[0])
 		let mask = urlMask
 		const t = join(Config.mocksDir, urlMask)
 		if (existsSync(t) && lstatSync(t).isDirectory())
 			mask = urlMask + '/'
-		const file = `${mask}.${method}.501.txt`
+		const file = `${mask}.${method}.500.txt`
 		writeFileSync(join(Config.mocksDir, file), '')
 		this.register(file)
 	}

package/MockDispatcher.js

@@ -10,46 +10,45 @@ import { parseJSON, JsonBodyParserError } from './utils/http-request.js'
 import { sendInternalServerError, sendNotFound, sendFile, sendBadRequest } from './utils/http-response.js'
 
 
-function serveDocumentation(req, response) {
-	sendFile(response, join(Config.mocksDir, decodeURIComponent(req.url)))
-}
-
 export async function dispatchMock(req, response) {
+	/* Serve Documentation */
 	if (req.method === 'GET' && req.url.endsWith('.md')) {
-		serveDocumentation(req, response)
+		sendFile(response, join(Config.mocksDir, decodeURIComponent(req.url)))
 		return
 	}
 
 	const mockBroker = MockBrokerCollection.findMatchingBroker(req.method, req.url)
-	if (!mockBroker)
+	if (!mockBroker) {
 		sendNotFound(response)
-	else
-		try {
-			const { file, status, delay, currentTransform } = mockBroker
-			console.log(decodeURIComponent(req.url), '->', file)
+		return
+	}
+	
+	try {
+		const { file, status, delay, currentTransform } = mockBroker
+		console.log('\n', req.url, '->\n ', file)
 
-			response.statusCode = status
-			response.setHeader('content-type', mimeFor(file))
-			if (cookie.getCurrent())
-				response.setHeader('set-cookie', cookie.getCurrent())
+		response.statusCode = status
+		response.setHeader('content-type', mimeFor(file))
+		if (cookie.getCurrent())
+			response.setHeader('set-cookie', cookie.getCurrent())
 
-			let mockAsText = readMock(file)
-			if (mockBroker.currentTransform) {
-				const body = await requestBodyForTransform(req, mockAsText)
-				const transformFunc = await importTransformFunc(currentTransform)
-				mockAsText = transformFunc(mockAsText, body, Config)
-			}
-			setTimeout(() => response.end(mockAsText), delay)
-		}
-		catch (error) {
-			console.error(error)
-			if (error instanceof JsonBodyParserError)
-				sendBadRequest(response)
-			else if (error.code === 'ENOENT')
-				sendNotFound(response) // file has been deleted
-			else
-				sendInternalServerError(response)
+		let mockAsText = readMock(file)
+		if (mockBroker.currentTransform) {
+			const body = await requestBodyForTransform(req, mockAsText)
+			const transformFunc = await importTransformFunc(currentTransform)
+			mockAsText = transformFunc(mockAsText, body, Config)
 		}
+		setTimeout(() => response.end(mockAsText), delay)
+	}
+	catch (error) {
+		console.error(error)
+		if (error instanceof JsonBodyParserError)
+			sendBadRequest(response)
+		else if (error.code === 'ENOENT')
+			sendNotFound(response) // file has been deleted
+		else
+			sendInternalServerError(response)
+	}
 }
 
 const nonSafeMethods = ['PATCH', 'POST', 'PUT', 'DELETE', 'CONNECT']

package/README.md

@@ -1,8 +1,9 @@
 # Mockaton 
 _Mockaton_ is a mock server for developing and testing frontends.
 
-It scans `Config.mocksDir` for files following a specific file name convention, which is
-similar to the URLs. For example, the following file will be served for `/api/user/1234`
+It scans `Config.mocksDir` for files following a specific
+file name convention, which is similar to the URL paths. For
+example, the following file will be served for `/api/user/1234`
 ```
 api/
 api/user/
@@ -22,10 +23,12 @@ Each route can have many mocks, which could either be:
 Those alternatives can be manually selected in the dashboard
 UI, or programmatically, for instance, for setting up tests.
 
+About the default mock file, the first file in **alphabetical order** wins.
+
 
 ## Getting Started
 The best way to learn _Mockaton_ is by checking out this repo and
-exploring its [sample-mocks/](./sample-mocks) directory. Then run
+exploring its [sample-mocks/](./sample-mocks) directory. Then, run
 [`./_usage_example.js`](./_usage_example.js) and you’ll see this dashboard:
 
 ![](./README-dashboard.png)
@@ -36,8 +39,8 @@ The **sample-mocks/** directory has three mock alternatives for serving
 `/api/user/friends`:
 - _200 - OK_
 - _204 - No Content_ with an empty list of friends
-- _501 - Internal Server Error_
-	- BTW, 501 mocks get autogenerated for routes that have no 501’s.
+- _500 - Internal Server Error_
+	- BTW, 500 mocks get autogenerated for routes that have no 500’s.
 
 ![](./README-dashboard-dropdown.png)
 
@@ -46,7 +49,7 @@ Comments are anything within parentheses, including them.
 ![](./README-mocks-with-comments.png)
 
 ## Delay 🕓
-The clock icon next to the mock selector dropdown is a checkbox for delaying a
+The clock icon next to the mock selector is a checkbox for delaying a
 particular response. They are handy for testing spinners.
 
 The milliseconds for the delay is globally configurable via `Config.delay = 1200`
@@ -102,7 +105,7 @@ Config.cookies = {
 ```
 
 That `jwtCookie` has a hardcoded header and signature. In other
-words, it’s useful iff you care about its payload in frontend.
+words, it’s useful iff you care about its payload in the frontend.
 
 ---
 
@@ -134,13 +137,13 @@ api/foo.GET.200.json
 ```
 api/video?limit=[limit].GET.200.json
 ```
-The query string behaves like comments in the sense it’s
-only used for documenting the URL API contract.
+The query string behaves like comments in the sense it’s only used for documenting
+the URL API contract. In other words, the query string is ignored when routing to it.
 
-In other words, the query string is ignored when routing to it. BTW, in Windows,
-filenames containing "?" are not permitted, but they are ignored anyway.
+BTW, in 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.
 
-https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
 
 
 ### Default (index-like) file
@@ -153,28 +156,6 @@ api/foo/?bar=[bar].GET.200.json
 api/foo/(my comment).GET.200.json
 ```
 
-
----
-## Mock Precedence
-The first file in **alphabetical order** wins when a particular route has many files.
-
-### Why do we have many mocks per Route+Method?
-Each route has mocks for many status codes, and also different
-mocks (by having comments) for testing particular scenarios.
-For example, different 422 validation error messages.
-
----
-
-## Reset the Dashboard UI after insert or delete
-When deleting the currently selected option, without refreshing the dashboard, the
-served mock will be an alternative mock if it exists. That is, the dashboard won't show
-a 404 after deleting the current mock if there’s another mock for that particular route.
-
-Similarly, inserting a file that goes first in alphabetical order will
-send a different mock from the one stated in the dashboard dropdown.
-
----
-
 ## Documenting Contracts (.md)
 This is handy for documenting request payload parameters. The dashboard will
 print the markdown document (as plain text) above the actual payload content.
@@ -183,15 +164,14 @@ Create a markdown file following the same filename convention.
 The status code can be any number. For example,
 ```text
 api/foo/[user-id].POST.201.md
+api/foo/[user-id].POST.201.json
 ```
 
----
-
-## Non-Deterministic Mocks (.mjs handlers)
+## Transforms (.mjs)
 Using the same filename convention, files ending
 with `.mjs` will process the mock before serving it.
 
-For example, this handler will uppercase the mock body.
+For example, this handler will capitalize the mock body and increment a counter.
 ```js
 export default function capitalizeAllText(mockAsText, requestBody, Config) {
   Config.database.myCount ??= 0
@@ -200,43 +180,60 @@ export default function capitalizeAllText(mockAsText, requestBody, Config) {
 }
 ```
 
-In demo mode, transforms tagged with the string `demo` within a filename
-comment get activated. Mock sets tags e.g. `demo-a` have no effect. In
-other words, only one transform per route is supported in demo mode.
-
 ---
 
 ## API
 
-### Changing a mock for one route
+### `/mockaton/edit` Select a mock for a route
 ```
-PATCH http://localhost:2345/mockaton/edit
+PATCH /mockaton/edit
 { 
   "file": "api/foo.200.GET.json"
   "delayed": true // optional
 }
 ```
+---
+
+### `/mockaton/bulk-select` Select all mocks that have a particular comment
 
-### Bulk Selecting Mocks by Matching comments
 ```
-PATCH http://localhost:2345/mockaton/bulk-select
+PATCH /mockaton/bulk-select
 {
   "comment": "demo-a"
 }
 ```
+---
 
-Many mocks can be changed at once. We do that by searching the
-comments on the filename. For example, `api/foo(demo-a).GET.200.json`
+### `/mockaton/reset` Reset
+Re-Initialize the collection and its states (selected mocks and cookies, delays, etc.).
+```
+PATCH /mockaton/reset
+```
+---
 
-Non-matching mocks are ignored. For instance, if for a
-particular API there is only `demo-a` and `demo-b`, changing to
-`demo-c` will preserve the last one that was successfully set.
+### `/mockaton/cookies` Select a cookie
+In `Config.cookies`, each key is the label used
+for changing it. Only one cookie can be set.
+```
+PATCH /mockaton/cookies
+{
+  "current_cookie_key": "My Normal User"
+}
+```
 
-Similarly, if there’s no demo mock at all for
-a route, the first dev mock (a-z) will be served.
+### `/mockaton/cookies` List Cookies
+Sends a list of the available cookies along with a flag indicated if it’s the selected.
+```
+GET /mockaton/cookies
+```
 
+---
 
-### Reset
+### `/mockaton/transform` Select a Transform
 ```
-PATCH http://localhost:2345/mockaton/reset
+PATCH /mockaton/transform
+{
+  "file": "api/video/list(concat newly uploaded).GET.200.mjs"
+}
 ```
+---

package/Route.js

@@ -16,7 +16,7 @@ export class Route {
 	constructor(file) {
 		const { urlMask, method } = Route.parseFilename(file)
 		this.method = method
-		this.#urlRegex = new RegExp(`^${disregardVariables(removeQueryStringAndFragment(urlMask))}/*$`)
+		this.#urlRegex = new RegExp('^' + disregardVariables(removeQueryStringAndFragment(urlMask)) + '/*$')
 	}
 
 	urlMaskMatches(url) {
@@ -45,20 +45,18 @@ export class Route {
 	static parseFilename(file) {
 		const tokens = file.replace(Route.reComments, '').split('.')
 
-		let error = ''
 		if (tokens.length < 4)
-			error = 'Invalid Filename Convention'
-
-		const method = tokens.at(-3)
-		if (!httpMethods.includes(method))
-			error = `Unrecognized HTTP Method: "${method}"`
+			return { error: 'Invalid Filename Convention' }
 
 		const status = Number(tokens.at(-2))
 		if (!responseStatusIsValid(status))
-			error = `Invalid HTTP Response Status: "${status}"`
+			return { error: `Invalid HTTP Response Status: "${status}"` }
+
+		const method = tokens.at(-3)
+		if (!httpMethods.includes(method))
+			return { error: `Unrecognized HTTP Method: "${method}"` }
 
 		return {
-			error,
 			urlMask: '/' + removeTrailingSlash(tokens.at(-4)),
 			method,
 			status

package/Tests.js

@@ -90,15 +90,10 @@ const fixtures = [
 for (const [, file, body] of fixtures)
 	write(file, file.endsWith('.json') ? JSON.stringify(body) : body)
 
-write('api/.GET.501.txt', 'keeps non-autogenerated 501')
+write('api/.GET.500.txt', 'keeps non-autogenerated 500')
 write('api/alternative(comment-2).GET.200.json', JSON.stringify({ comment: 2 }))
 write('api/my-route(comment-2).GET.200.json', JSON.stringify({ comment: 2 }))
 
-// These files ensure the server doesn’t crash. We don’t test their console.error 
-write('api/bad-filename.200.json', 'missing method')
-write('api/bad-filename.GET.200', 'missing extension')
-write('api/bad-filename.GET.json', 'missing response status')
-
 writeStatic('index.html', '<h1>Static</h1>')
 writeStatic('assets/app.js', 'const app = 1')
 writeStatic('another-entry/index.html', '<h1>Another</h1>')
@@ -125,14 +120,14 @@ async function runTests() {
 		'/api/alternative',
 		'api/alternative(comment-1).GET.200.json')
 
-	await testAutogenerates501(
+	await testAutogenerates500(
 		'/api/company-e/123?limit=9',
-		'api/company-e/[id]?limit=[limit].GET.501.txt')
+		'api/company-e/[id]?limit=[limit].GET.500.txt')
 
-	await testPreservesExiting501(
+	await testPreservesExiting500(
 		'/api',
-		'api/.GET.501.txt',
-		'keeps non-autogenerated 501')
+		'api/.GET.500.txt',
+		'keeps non-autogenerated 500')
 
 	await reset()
 	await testItUpdatesTheCurrentSelectedMock(
@@ -148,12 +143,10 @@ async function runTests() {
 		'(this is the actual comment)',
 		'(another comment)'
 	])
-	await testItBulkSelectsByComment('(comment-2)',
-		[
-			['/api/alternative', 'api/alternative(comment-2).GET.200.json', { comment: 2 }],
-			['/api/my-route', 'api/my-route(comment-2).GET.200.json', { comment: 2 }]
-		]
-	)
+	await testItBulkSelectsByComment('(comment-2)', [
+		['/api/alternative', 'api/alternative(comment-2).GET.200.json', { comment: 2 }],
+		['/api/my-route', 'api/my-route(comment-2).GET.200.json', { comment: 2 }]
+	])
 
 	await reset()
 	for (const [url, file, body] of fixtures)
@@ -161,9 +154,8 @@ async function runTests() {
 
 	await testItUpdatesUserRole()
 	await testTransforms()
-
 	await testStaticFileServing()
-
+	await testInvalidFilenamesAreIgnored()
 	server.close()
 }
 
@@ -223,29 +215,29 @@ async function testItUpdatesDelayAndFile(url, file) {
 }
 
 
-async function testAutogenerates501(url, file) {
+async function testAutogenerates500(url, file) {
 	await request(DP.edit, {
 		method: 'PATCH',
 		body: JSON.stringify({ [DF.file]: file })
 	})
 	const res = await request(url)
 	const body = await res.text()
-	await describe('autogenerated 501', () => {
+	await describe('autogenerated 500', () => {
 		it('body is empty', () => equal(body, ''))
-		it('status is: 501', () => equal(res.status, 501))
+		it('status is: 500', () => equal(res.status, 500))
 	})
 }
 
-async function testPreservesExiting501(url, file, expectedBody) {
+async function testPreservesExiting500(url, file, expectedBody) {
 	await request(DP.edit, {
 		method: 'PATCH',
 		body: JSON.stringify({ [DF.file]: file })
 	})
 	const res = await request(url)
 	const body = await res.text()
-	await describe('preserves existing 501', () => {
+	await describe('preserves existing 500', () => {
 		it('body is empty', () => equal(body, expectedBody))
-		it('status is: 501', () => equal(res.status, 501))
+		it('status is: 500', () => equal(res.status, 500))
 	})
 }
 
@@ -259,9 +251,7 @@ async function testExtractsAllComments(expected) {
 async function testItBulkSelectsByComment(comment, tests) {
 	await request(DP.bulkSelect, {
 		method: 'PATCH',
-		body: JSON.stringify({
-			[DF.comment]: comment
-		})
+		body: JSON.stringify({ [DF.comment]: comment })
 	})
 	for (const [url, file, body] of tests)
 		await testMockDispatching(url, file, body)
@@ -305,11 +295,7 @@ export default function (mock, reqBody, config) {
 		await reset() // for registering the files
 		await request(DP.transform, {
 			method: 'PATCH',
-			body: JSON.stringify({
-				[DF.method]: 'POST',
-				[DF.urlMask]: '/api/transform',
-				[DF.file]: 'api/transform.POST.200.mjs'
-			})
+			body: JSON.stringify({ [DF.file]: 'api/transform.POST.200.mjs' })
 		})
 		await testMockDispatching('/api/transform',
 			'api/transform.POST.200.json',
@@ -344,6 +330,22 @@ async function testStaticFileServing() {
 	})
 }
 
+async function testInvalidFilenamesAreIgnored() {
+	await it('Invalid filenames get skipped, so they don’t crash the server', async (t) => {
+		const consoleErrorSpy = t.mock.method(console, 'error')
+		consoleErrorSpy.mock.mockImplementation(() => {}) // so they don’t render in the test report
+		
+		// An extension is needed for testing because of `Config.allowedExt`
+		write('api/_INVALID_FILENAME_CONVENTION_.json', '')
+		write('api/bad-filename.GET._INVALID_STATUS_.json', '')
+		write('api/bad-filename._INVALID_METHOD_.200.json', '')
+		await reset()
+		equal(consoleErrorSpy.mock.calls[0].arguments[0], 'Invalid Filename Convention')
+		equal(consoleErrorSpy.mock.calls[1].arguments[0], 'Invalid HTTP Response Status: "NaN"')
+		equal(consoleErrorSpy.mock.calls[2].arguments[0], 'Unrecognized HTTP Method: "_INVALID_METHOD_"')
+	})
+}
+
 
 // Utils
 

package/_usage_example.js

@@ -8,8 +8,8 @@ Mockaton({
 	mocksDir: resolve('sample-mocks'),
 	staticDir: resolve('sample-static'),
 	cookies: {
-		'Admin User': 'my-cookie=1;Path=/;SameSite=strict',
-		'Normal User': 'my-cookie=0;Path=/;SameSite=strict',
+		'My Admin User': 'my-cookie=1;Path=/;SameSite=strict',
+		'My Normal User': 'my-cookie=0;Path=/;SameSite=strict',
 		'My JWT': jwtCookie('my-cookie', {
 			email: 'john.doe@example.com',
 			picture: 'https://cdn.auth0.com/avatars/jd.png'

package/mockBrokersCollection.js

@@ -35,14 +35,13 @@ export function init() {
 				collection[method][urlMask].register(file)
 		}
 	}
-	forEachBroker(broker => broker.ensureItHas501())
+	forEachBroker(broker => broker.ensureItHas500())
 }
 
 export const getAll = () => collection
-export const getBroker = (method, urlMask) => collection[method][urlMask]
 export const getBrokerByFilename = file => {
 	const { method, urlMask } = Route.parseFilename(file)
-	return getBroker(method, urlMask)
+	return collection[method][urlMask]
 }
 
 

package/package.json

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

package/sample-mocks/api/user/.GET.500.txt

@@ -0,0 +1,7 @@
+This is a plain text response for (/api/user). 
+
+In this case, it’s for mocking up a 500 - Internal Server Error.
+
+This file could have been empty, or some JSON if it had a `.json` extension.
+
+By the way, on initialization an 500 is auto-generated for routes that don’t have a 500.

package/sample-mocks/api/user/.GET.501.txt

@@ -1,7 +0,0 @@
-This is a plain text response for (/api/user). 
-
-In this case, it’s for mocking up a 501 - Internal Server Error.
-
-This file could have been empty, or some JSON if it had a `.json` extension.
-
-By the way, on initialization an 501 is auto-generated for routes that don’t have a 501.