mockaton 8.2.20 → 8.2.22

package/README.md

@@ -17,20 +17,21 @@ By the way, [this browser
 extension](https://github.com/ericfortis/devtools-ext-tar-http-requests)
 can create a TAR of your requests following that convention.
 
-Nonetheless, 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 `config.proxyFallback = 'http://mybackend'`
+Nonetheless, 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 `config.proxyFallback = 'http://mybackend'`
 
 ## 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.
-  For example, `api/login(locked out user).POST.423.json`
+  - e.g. `api/login(locked out user).POST.423.json`
 
 
 ## Dashboard UI
 
 In the dashboard, you can select a mock variant for a particular
-route, among other options. But there’s also a programmatic API,
+route, among other options. In addition, there’s a programmatic API,
 which is handy for setting up tests  (see **Commander API** below).
 
 <picture>
@@ -64,7 +65,7 @@ node --import=tsx my-mockaton.js
 
 
 ## Running the Demo Example
-This demo uses the [sample-mocks/](./sample-mocks) directory of this repository.
+This demo uses the [sample-mocks/](./sample-mocks) of this repository.
 
 ```sh  
 git clone https://github.com/ericfortis/mockaton.git
@@ -95,9 +96,9 @@ The _Reset_ button is for registering newly added, removed, or renamed mocks.
   - slow to build assets
 
 ### Time Travel
-If you commit the mocks in the repo, when bisecting a bug, you don’t
-have to sync the frontend with many backend repos. Similarly, it
-allows for checking out long-lived branches with old API contracts.
+If you commit the mocks to your repo, it’s straightforward to bisect bugs and
+checking out long-lived branches. In other words, you don’t have to downgrade
+backends to old API contracts or databases.
 
 ### Deterministic Standalone Demo Server
 Perhaps you need to demo your app, but the ideal flow is too complex to
@@ -122,15 +123,6 @@ filename, such as `(demo-part1)`, `(demo-part2)`.
 - Reverse Proxies such as [Burp](https://portswigger.net/burp) are also handy for overriding responses.
 - [Mock Server Worker](https://mswjs.io)
 
----
-## Default Mock for a Route
-You can add the comment: `(default)` to a filename.
-Otherwise, the first file in **alphabetical order** wins.
-
-```
-api/user(default).GET.200.json
-```
-
 ---
 
 ## You can write JSON mocks in JavaScript or TypeScript
@@ -226,6 +218,15 @@ api/foo<b>(my comment)</b>.GET.200.json
 api/foo.GET.200.json
 </pre>
 
+### Default Mock for a Route
+You can add the comment: `(default)`. 
+Otherwise, the first file in **alphabetical order** wins.
+
+<pre>
+api/user<b>(default)</b>.GET.200.json
+</pre>
+
+
 ### Query String Params
 The query string is ignored when routing to it. In other words, it’s only used for
 documenting the URL contract.
@@ -233,13 +234,12 @@ documenting the URL contract.
 api/video<b>?limit=[limit]</b>.GET.200.json
 </pre>
 
-Speaking of which, in Windows, filenames containing "?" are [not
+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.
 
 
-### Index-like route
-For instance, if you have `api/foo/bar` and
-`api/foo`, you have two options:
+### Index-like routes
+If you have `api/foo` and `api/foo/bar`, you have two options:
 
 **Option A:** 
 ```
@@ -272,8 +272,7 @@ Defaults to `/(\.DS_Store|~)$/`
 
 
 ### `delay?: number` 🕓
-The clock icon next to the mock selector is a checkbox for delaying a particular
-response. The delay is globally configurable via `config.delay = 1200` (milliseconds).
+The delay is globally configurable, it defaults to `1200` (milliseconds).
 
 
 ### `proxyFallback?: string`
@@ -309,15 +308,13 @@ config.cookies = {
   })
 }
 ```
-The selected cookie is sent in every response in a `Set-Cookie` header.
+The selected cookie, which is the first one by default, is sent in every
+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.
 
-If you need to send more than one cookie,
-inject them globally in `config.extraHeaders`.
-
-
 
 ### `extraHeaders?: string[]`
 Note it’s a unidimensional array. The header name goes at even indices.
@@ -337,6 +334,8 @@ config.extraMimes = {
   jpe: 'application/jpeg'
 }
 ```
+These media types take precedence over the built-in
+[utils/mime.js](src/utils/mime.js), so you can override them.
 
 
 ### `plugins?: [filenameTester: RegExp, plugin: Plugin][]`
@@ -352,7 +351,7 @@ type Plugin = (
 ```
 Plugins are for processing mocks before sending them.
 
-Note: don’t call `response.end()`
+Note: don’t call `response.end()` on them.
 
 <details>
 <summary><b> See Plugin Examples </b></summary>
@@ -366,7 +365,7 @@ import { readFileSync } from 'node:js'
 import { jsToJsonPlugin } from 'mockaton'
 
 config.plugins = [
-  [/\.(js|ts)$/, jsToJsonPlugin], // Default 
+  [/\.(js|ts)$/, jsToJsonPlugin], // Default but you need to add it to your list if you need it
   [/\.yml$/, yamlToJsonPlugin],
   [/foo\.GET\.200\.txt$/, capitalizePlugin], // e.g. GET /api/foo would be capitalized
 ]
@@ -401,7 +400,7 @@ config.corsExposedHeaders = [] // headers you need to access in client-side JS
 
 
 ### `onReady?: (dashboardUrl: string) => void`
-This defaults to trying to open the dashboard in your default browser in macOS and
+This defaults to trying to open the dashboard in your default browser on macOS and
 Windows. For a more cross-platform utility, you could `npm install open` and pass it.
 ```js
 import open from 'open'
@@ -434,7 +433,7 @@ await mockaton.select('api/foo.200.GET.json')
 ```js
 await mockaton.bulkSelectByComment('(demo-a)')
 ```
-Parentheses are optional. You can pass a partial match.
+Parentheses are optional, so you can pass a partial match.
 For example, passing `'demo-'` (without the final `a`), selects the
 first mock in alphabetical order that matches.
 

package/package.json

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

package/src/Dashboard.css

@@ -218,7 +218,6 @@ main {
 .MockSelector {
 	width: 300px;
 	height: 30px;
-	padding: 8px 1px;
 	border: 0;
 	border-left: 3px solid transparent;
 	text-align: right;

package/src/Dashboard.js

@@ -60,8 +60,7 @@ init()
 
 function App(apiResponses) {
 	empty(document.body)
-	createRoot(document.body)
-		.render(DevPanel(apiResponses))
+	document.body.appendChild(DevPanel(apiResponses))
 }
 
 function DevPanel([brokersByMethod, cookies, comments, corsAllowed, fallbackAddress, staticFiles]) {
@@ -404,14 +403,6 @@ function empty(node) {
 // These are simplified React-compatible implementations.
 // IOW, for switching to React, remove the `createRoot`, `createElement`, `useRef`
 
-function createRoot(root) {
-	return {
-		render(app) {
-			root.appendChild(app)
-		}
-	}
-}
-
 function createElement(elem, props = null, ...children) {
 	if (typeof elem === 'function')
 		return elem(props)

package/src/MockDispatcher.js

@@ -3,7 +3,7 @@ import { join } from 'node:path'
 import { proxy } from './ProxyRelay.js'
 import { cookie } from './cookie.js'
 import { Config } from './Config.js'
-import { preprocessPlugins } from './MockDispatcherPlugins.js'
+import { applyPlugins } from './MockDispatcherPlugins.js'
 import * as mockBrokerCollection from './mockBrokersCollection.js'
 import { JsonBodyParserError } from './utils/http-request.js'
 import { sendInternalServerError, sendNotFound, sendBadRequest } from './utils/http-response.js'
@@ -31,7 +31,7 @@ export async function dispatchMock(req, response) {
 
 		const { mime, body } = broker.isTemp500
 			? { mime: '', body: '' }
-			: await preprocessPlugins(join(Config.mocksDir, broker.file), req, response)
+			: await applyPlugins(join(Config.mocksDir, broker.file), req, response)
 
 		response.setHeader('Content-Type', mime)
 		setTimeout(() => response.end(body), broker.delay)

package/src/MockDispatcherPlugins.js

@@ -3,7 +3,7 @@ import { mimeFor } from './utils/mime.js'
 import { Config } from './Config.js'
 
 
-export async function preprocessPlugins(filePath, req, response) {
+export async function applyPlugins(filePath, req, response) {
 	for (const [regex, plugin] of Config.plugins) // TESTME capitalizePlugin
 		if (regex.test(filePath))
 			return await plugin(filePath, req, response)

package/src/Mockaton.js

@@ -13,10 +13,8 @@ import { apiPatchRequests, apiGetRequests } from './Api.js'
 export function Mockaton(options) {
 	setup(options)
 	mockBrokerCollection.init()
-
-	const server = createServer(onRequest)
-	server.listen(Config.port, Config.host, (error) => {
-		const { address, port } = server.address()
+	return createServer(onRequest).listen(Config.port, Config.host, function (error) {
+		const { address, port } = this.address()
 		const url = `http://${address}:${port}`
 		console.log('Listening', url)
 		console.log('Dashboard', url + API.dashboard)
@@ -25,7 +23,6 @@ export function Mockaton(options) {
 		else
 			Config.onReady(url + API.dashboard)
 	})
-	return server
 }
 
 async function onRequest(req, response) {

package/src/Mockaton.test.js

@@ -98,6 +98,7 @@ const fixtures = [
 	],
 
 	// Query String
+	// TODO ignore on Windows (because of ?)
 	[
 		'/api/my-query-string?foo=[foo]&bar=[bar]',
 		'api/my-query-string?foo=[foo]&bar=[bar].GET.200.json',

package/src/utils/fs.js

@@ -1,4 +1,4 @@
-import { join } from 'node:path'
+import path, { join } from 'node:path'
 import { lstatSync, readFileSync, readdirSync } from 'node:fs'
 
 
@@ -9,4 +9,5 @@ export const read = path => readFileSync(path)
 
 /** @returns {Array<string>} paths relative to `dir` */
 export const listFilesRecursively = dir => readdirSync(dir, { recursive: true })
+	.map(f => f.replaceAll(path.sep, path.posix.sep)) // TESTME
 	.filter(f => isFile(join(dir, f)))

package/src/utils/openInBrowser.js

@@ -6,7 +6,7 @@ export function openInBrowser(address) {
 		case 'darwin':
 			exec(`open ${address}`)
 			break
-		case 'win32': // TESTME
+		case 'win32':
 			exec(`start ${address}`)
 			break
 	}