mockaton 6.4.0 → 6.4.3

package/README.md

@@ -8,9 +8,31 @@ example, the following file will be served for `/api/user/1234`
 my-mocks-dir/api/user/[user-id].GET.200.json
 ```
 
-By the way, [this browser
-extension](https://github.com/ericfortis/devtools-ext-tar-http-requests) can
-be used for downloading a TAR of your XHR requests following that convention.
+[This browser extension](https://github.com/ericfortis/devtools-ext-tar-http-requests)
+can be used for downloading a TAR of your XHR requests following that convention.
+
+## What do I use Mockaton for?
+- I’m a frontend dev, so I don’t have to spin up and maintain hefty or complex backends.
+- For a deterministic and comprehensive state. Having all the possible
+  state variants at once lets me visually spot inadvertent bugs right away.
+- Testing empty responses.
+- Testing spinners by delaying responses.
+- Triggering errors such as Bad Request and Internal Server Error.
+- Triggering notifications and alerts.
+- As check-in the mocks in the repo, when bisecting a bug, I don’t
+  have to sync the frontend with many backend repos.
+  - Similarly, I can check out long-lived branches that have old API contracts.
+- Prototyping before the backend API is developed.
+- As API documentation.
+- Setting up tests.
+
+## Alternatives
+- 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.
+- [Storybook](https://storybook.js.org)
+
+### Caveats
+- Syncing the mocks. The browser extension mentioned above helps.
 
 
 ## Getting Started
@@ -45,22 +67,23 @@ node my-mockaton.js
 ```ts
 interface Config {
   mocksDir: string
-  ignore?: RegExp // defaults to /(\.DS_Store|~)$/
+  ignore?: RegExp // Defaults to /(\.DS_Store|~)$/
 
-  staticDir?: string
+  staticDir?: string // These files don’t use the mock-filename convention
 
-  host?: string, // defaults to 'localhost'
-  port?: number // defaults to 0, which means auto-assigned
+  host?: string, // Defaults to 'localhost'
+  port?: number // Defaults to 0, which means auto-assigned
   proxyFallback?: string // e.g. http://localhost:9999 Target for relaying routes without mocks
 
-  delay?: number // defaults to 1200 (ms)
+  delay?: number // Defaults to 1200 (ms)
   cookies?: { [label: string]: string }
   extraMimes?: { [fileExt: string]: string }
   extraHeaders?: []
 
-  onReady?: (dashboardUrl: string) => void // defaults to trying to open macOS default browser. pass a noop to prevent opening the dashboard
+  onReady?: (dashboardUrl: string) => void // Defaults to trying to open macOS and Win default browser.
 }
 ```
+There’s a Config section below with more details.
 
 ---
 
@@ -78,7 +101,6 @@ You can add the comment: `(default)` to a filename.
 Otherwise, the first file in **alphabetical order** wins.
 
 ```
-api/user(some comment).GET.200.json
 api/user(default).GET.200.json
 ```
 
@@ -174,6 +196,16 @@ api/foo.GET.200.json
 api/foo/.GET.200.json
 ```
 
+---
+## `Config.staticDir`
+These files don’t use the mock filename convention. They take precedence
+over mocks. Also, they get served on the same address, so no CORS issues.
+
+Use Case 1: If you have a bunch of static assets you don’t want to add `.GET.200.ext`
+
+Use Case 2: For a standalone demo server. For example,
+build your frontend bundle, and serve it from Mockaton.
+
 
 ## `Config.cookies`
 The selected cookie is sent in every response in the `Set-Cookie` header.
@@ -219,6 +251,33 @@ Config.extraMimes = {
 }
 ```
 
+## `Config.onReady`
+This is a callback `(dashboardAddress: string) => void`, which defaults to
+trying to open the dashboard in your default browser in macOS and Windows.
+
+If you don’t want to open a browser, pass a noop, such as
+```js
+Config.onReady = () => {}
+```
+
+On Linux, you could pass:
+```js
+import { exec } from 'node:child_process'
+
+
+Config.onReady = function openInBrowser(address) {
+  exec(`xdg-open ${address}`)
+}
+```
+
+Or, for more cross-platform utility, you could `npm install open` and pass it.
+```js
+import open from 'open'
+
+
+Config.onReady = open
+```
+
 ---
 
 ## API

package/package.json

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

package/sample-mocks/api/user/{videos(entirely unverified).GET.200.json → videos(default).GET.200.json}

@@ -1,5 +1,5 @@
 {
-	"_": "This file has a comment: `(entirely unverified)`. i.e. the route is /api/user/videos",
+	"_": "This file has a comment: `(default)`. Which makes the file with comment: (all variants) not to win",
 	"videos": [
 		{
 			"url": "https://example.com/1",

package/src/ApiConstants.js

@@ -15,5 +15,5 @@ export const DF = { // Dashboard Fields (XHR)
 	file: 'file'
 }
 
-export const DEFAULT_500_COMMENT = '(Mockaton Temp 500)'
+export const DEFAULT_500_COMMENT = '(Mockaton 500)'
 export const DEFAULT_MOCK_COMMENT = '(default)'

package/src/Config.js

@@ -21,6 +21,7 @@ export const Config = Object.seal({
 	onReady: openInBrowser
 })
 
+
 export function setup(options) {
 	Object.assign(Config, options)
 	validate(Config, {

package/src/Filename.js

@@ -4,7 +4,6 @@ const httpMethods = [
 	'POST', 'PUT', 'TRACE'
 ]
 
-
 const reComments = /\(.*?\)/g // Anything within parentheses
 
 export const extractComments = filename =>
@@ -20,21 +19,18 @@ export function filenameIsValid(file) {
 		console.error(error, file)
 	return !error
 }
-
 function validateFilename(file) {
 	const tokens = file.replace(reComments, '').split('.')
 	if (tokens.length < 4)
 		return 'Invalid Filename Convention'
-
 	const { status, method } = parseFilename(file)
-
 	if (!responseStatusIsValid(status))
 		return `Invalid HTTP Response Status: "${status}"`
-
 	if (!httpMethods.includes(method))
 		return `Unrecognized HTTP Method: "${method}"`
 }
 
+
 export function parseFilename(file) {
 	const tokens = file.replace(reComments, '').split('.')
 	return {
@@ -44,6 +40,7 @@ export function parseFilename(file) {
 	}
 }
 
+
 function removeTrailingSlash(url = '') {
 	return url
 		.replace(/\/$/, '')

package/src/MockBroker.js

@@ -7,23 +7,18 @@ import { includesComment, extractComments, parseFilename } from './Filename.js'
 // that can be served for the route, the currently selected file, and its delay.
 export class MockBroker {
 	#urlRegex
-
 	constructor(file) {
 		const { urlMask } = parseFilename(file)
 		this.#urlRegex = new RegExp('^' + disregardVariables(removeQueryStringAndFragment(urlMask)) + '/*$')
-
 		this.mocks = []
 		this.currentMock = {
 			file: '',
 			delay: 0
 		}
-
 		this.register(file)
 	}
 
-	register(file) {
-		this.mocks.push(file)
-	}
+	register(file) { this.mocks.push(file) }
 
 	// Appending a '/' so URLs ending with variables don't match
 	// URLs that have a path after that variable. For example,
@@ -39,9 +34,16 @@ 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) }
 
 	selectDefaultFile() {
-		this.updateFile(this.#findMockWithDefaultComment() || this.mocks[0])
+		const userSpecifiedDefault = this.#findMockWithDefaultComment()
+		if (userSpecifiedDefault) // Sort for dashboard list TESTME
+			this.mocks = [
+				userSpecifiedDefault,
+				...this.mocks.filter(m => m !== userSpecifiedDefault)
+			]
+		this.updateFile(userSpecifiedDefault || this.mocks[0])
 	}
 	#findMockWithDefaultComment() {
 		for (const f of this.mocks)
@@ -49,17 +51,9 @@ export class MockBroker {
 				return f
 	}
 
-	mockExists(file) {
-		return this.mocks.includes(file)
-	}
-
-	updateFile(filename) {
-		this.currentMock.file = filename
-	}
-
-	updateDelay(delayed) {
-		this.currentMock.delay = Number(delayed) * Config.delay
-	}
+	mockExists(file) { return this.mocks.includes(file) }
+	updateFile(filename) { this.currentMock.file = filename }
+	updateDelay(delayed) { this.currentMock.delay = Number(delayed) * Config.delay }
 
 	setByMatchingComment(comment) {
 		for (const file of this.mocks)
@@ -88,9 +82,6 @@ export class MockBroker {
 		const file = urlMask.replace(/^\//, '') // Removes leading slash TESTME
 		this.register(`${file}${DEFAULT_500_COMMENT}.${method}.500.txt`)
 	}
-	get isTemp500() {
-		return includesComment(this.file, DEFAULT_500_COMMENT)
-	}
 }
 
 // Stars out (for regex) all the paths that are in square brackets