mockaton 13.14.0 → 14.0.0

package/README.md

@@ -8,20 +8,22 @@
 
 *No API state should be too difficult to test*
 
-## [Docs ↗](https://mockaton.com) | [Changelog ↗](https://mockaton.com/changelog) | [Skills](skills/mockaton/SKILL.md)
+### [Docs](https://mockaton.com) | [Changelog](https://mockaton.com/changelog) | [Skills](skills/mockaton/SKILL.md) | [Use Cases](https://mockaton.com/use-cases)
 
+## Overview
+
+Mockaton is a local HTTP mock server. With it, you can test API states 
+that are difficult to reproduce from an actual backend.
+
+For example, to quickly trigger an error on an endpoint, click the 500 button. 
+Then, unclick it to test your retry logic.
 
-Simulate API states that are normally ignored. For example, quickly trigger an error on 
-an endpoint by clicking the 500 button. Then, unclick it to test your retry logic.
 Similarly, pick a mock variant from the dropdown, say to respond with a 423 (locked account).
-As another example, click the clock button 🕓 to delay a response so you can test 
-spinners — you’ve seen them in production at the top left, or restart
-their animation midway. 
+
+Or click the clock button 🕓 to delay a response so you can test spinners.
 
 
 ## Dashboard
-Besides the dashboard UI, there’s a [programmatic API](https://mockaton.com/api), 
-which is handy for setting up tests.
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ericfortis/mockaton/refs/heads/main/pixaton-tests/tests/macos/pic-for-readme.vp762x762.light.gold.png">
@@ -29,6 +31,9 @@ which is handy for setting up tests.
   <img alt="Mockaton Dashboard" src="https://raw.githubusercontent.com/ericfortis/mockaton/refs/heads/main/pixaton-tests/tests/macos/pic-for-readme.vp762x762.dark.gold.png">
 </picture>
 
+Besides the dashboard, there’s a [programmatic API](https://mockaton.com/api),
+which is handy for setting up tests.
+
 
 ## Demo (Docker)
 This will spin up Mockaton with the [sample directory](./mockaton-mocks)
@@ -64,7 +69,7 @@ npx skills add ericfortis/mockaton
 
 ## Basic Usage
 ```sh
-mockaton --port 2020 my-mocks-dir
+mockaton  --port 2020  my-mocks-dir
 ```
 
 Mockaton will serve the files on the given directory. It's a file-system based router in which 
@@ -77,7 +82,7 @@ code variants.
 | Route | Filename | Description |
 | -----| -----| ---|
 | /api/company/123 | api/company/[id].GET.200.ts | `[id]` is a dynamic parameter. `.ts`, and `.js` are sent as JSON by default. |
-| /media/avatar.png | media/avatar.png | Statics assets don't need the above extension. |
+| /media/avatar.png | media/avatar.png | Statics assets (GET 200) don’t need the extension convention. |
 | /api/login | api/login(invalid attempt).POST.401.ts | Anything within parenthesis is a comment. They are ignored when routing. You can add many comments, `foo(c0)(c1).png` |
 | /api/login | api/login(default).GET.200.ts | `(default)` is a special comment. Otherwise, the first mock variant in alphabetical order wins.  |
 | /api/login | api/login(locked out user).POST.423.json | `.json` is allowed too. |

package/index.d.ts

@@ -11,7 +11,7 @@ export declare type Plugin = (
 
 export declare interface Config {
 	mocksDir?: string
-	ignore?: RegExp
+	shouldIgnore?: (filepath: string) => boolean
 	watcherEnabled?: boolean
 	watcherDebounceMs?: number
 	readOnly?: boolean
@@ -46,7 +46,6 @@ export declare interface Config {
 	onReady?: (address: string) => void
 
 	hotReload?: boolean // For UI dev purposes only
-	bypassImportCache?: boolean
 }
 
 
@@ -62,6 +61,7 @@ export declare const echoFilePlugin: Plugin
 
 export declare function jwtCookie(cookieName: string, payload: any, path?: string): string
 
+export declare function shouldIgnore(filepath: string): boolean
 export declare function parseJSON(request: IncomingMessage): Promise<any>
 export declare function parseSegments(reqUrl: string, filename: string): Record<string, string>
 export declare function parseQueryParams(reqUrl: string): URLSearchParams
@@ -102,4 +102,4 @@ declare global {
 	}
 }
 
-export type { JsonPromise, ClientMockBroker, ClientBrokersByMethod, State }
+export type { JsonPromise, ClientMockBroker, ClientBrokersByMethod, State }

package/index.js

@@ -5,6 +5,7 @@ export { Mockaton } from './src/server/Mockaton.js'
 export { jwtCookie } from './src/server/utils/jwt.js'
 export { jsToJsonPlugin, echoFilePlugin } from './src/server/MockDispatcherPlugins.js'
 export { parseJSON, BodyReaderError } from './src/server/utils/HttpIncomingMessage.js'
-export { parseSegments, parseQueryParams, parseSplats } from './src/server/UrlParsers.js'
+export { parseSegments, parseQueryParams } from './src/server/UrlParsers.js'
+export { shouldIgnore } from './src/server/stores/config.js'
 
 export const defineConfig = opts => opts

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "13.14.0",
+	"version": "14.0.0",
 	"exports": {
 		".": {
 			"import": "./index.js",

package/skills/mockaton/SKILL.md

@@ -15,7 +15,7 @@ npm install -g mockaton
 
 ## Basic Usage
 ```sh
-mockaton --port 2020 my-mocks-dir
+mockaton  --port 2020  my-mocks-dir
 ```
 
 Mockaton will serve the files on the given directory. It's a file-system based router in which 
@@ -28,7 +28,7 @@ code variants.
 | Route | Filename | Description |
 | -----| -----| ---|
 | /api/company/123 | api/company/[id].GET.200.ts | `[id]` is a dynamic parameter. `.ts`, and `.js` are sent as JSON by default. |
-| /media/avatar.png | media/avatar.png | Statics assets don't need the above extension. |
+| /media/avatar.png | media/avatar.png | Statics assets (GET 200) don’t need the extension convention. |
 | /api/login | api/login(invalid attempt).POST.401.ts | Anything within parenthesis is a comment. They are ignored when routing. You can add many comments, `foo(c0)(c1).png` |
 | /api/login | api/login(default).GET.200.ts | `(default)` is a special comment. Otherwise, the first mock variant in alphabetical order wins.  |
 | /api/login | api/login(locked out user).POST.423.json | `.json` is allowed too. |

package/src/client/dir/dittoSplitPaths.js

@@ -4,13 +4,13 @@
  * @param {string[]} paths - sorted
  */
 export function dittoSplitPaths(paths) {
-	const segments = paths.map(p => p.split('/').filter(Boolean))
+	const pathsSplit = paths.map(p => p.split('/').filter(Boolean))
 	return paths.map((p, i) => {
 		if (i === 0)
 			return ['', p]
 
-		const prev = segments[i - 1]
-		const curr = segments[i]
+		const prev = pathsSplit[i - 1]
+		const curr = pathsSplit[i]
 		const min = Math.min(curr.length, prev.length)
 		let j = 0
 		while (j < min && curr[j] === prev[j])

package/src/client/dir/groupByFolder.js

@@ -28,19 +28,19 @@ function trie(brokers) {
 function dfs(node) {
 	const childBrokers = node.getChildren().flatMap(dfs)
 
-	const brokers = node.brokers.length
-		? [node.brokers[0], ...childBrokers, ...node.brokers.slice(1)]
-		: childBrokers
-
-	if (!brokers.length)
-		return []
+	if (node.brokers.length) {
+		const [b0, ...rest] = node.brokers
+		b0.children.push(...childBrokers, ...rest)
+		return [b0]
+	}
 
-	const [b0, ...rest] = brokers
-	if (node.brokers.length || !b0.children.length) {
+	if (childBrokers.length && !childBrokers[0].children.length) {
+		const [b0, ...rest] = childBrokers
 		b0.children.push(...rest)
 		return [b0]
 	}
-	return brokers
+
+	return childBrokers
 }
 
 class TrieNode {

package/src/server/Api.js

@@ -23,12 +23,12 @@ import * as Watcher from './stores/Watcher.js'
 
 export const CLIENT_ASSETS = join(import.meta.dirname, '../client')
 
-const headReqs = new Map([
+const HEAD = new Map([
 	[API.health, (_, response) => response.ok()]
 ])
 
-const getReqs = new Map([
-	...headReqs.entries(),
+const GET = new Map([
+	...HEAD.entries(),
 
 	[API.root, serveDashboard],
 	[API.state, getState],
@@ -39,7 +39,7 @@ const getReqs = new Map([
 	[API.throws, () => { throw new Error('Test500') }]
 ])
 
-const patchReqs = new Map([
+const PATCH = new Map([
 	[API.cors, setCorsAllowed],
 	[API.reset, reset],
 	[API.cookies, selectCookie],
@@ -68,9 +68,9 @@ export async function handleApiRequest(req, response) {
 	const url = removeQueryStringAndFragment(req.url)
 
 	const handler = (
-		req.method === 'GET' && getReqs.get(url) ||
-		req.method === 'HEAD' && headReqs.get(url) ||
-		req.method === 'PATCH' && patchReqs.get(url))
+		req.method === 'GET' && GET.get(url) ||
+		req.method === 'HEAD' && HEAD.get(url) ||
+		req.method === 'PATCH' && PATCH.get(url))
 	if (handler) {
 		await handler(req, response)
 		return true

package/src/server/MockDispatcher.js

@@ -29,9 +29,8 @@ export async function dispatchMock(req, response) {
 			return
 		}
 
-		response.on('finish', () => {
-			logger.normal('MOCK', req.url, broker.file)
-		})
+		response.on('finish', () =>
+			logger.normal('MOCK', req.url, broker.file))
 
 		if (cookie.getCurrent())
 			response.setHeader('Set-Cookie', cookie.getCurrent())
@@ -39,9 +38,9 @@ export async function dispatchMock(req, response) {
 		const { isStatic } = parseFilename(broker.file)
 
 		if (isStatic && req.headers.range && !broker.autoStatus) {
-			setTimeout(async () => {
-				await response.partialContent(join(config.mocksDir, broker.file))
-			}, Number(broker.delayed && calcDelay()))
+			setTimeout(
+				() => response.partialContent(join(config.mocksDir, broker.file)),
+				Number(broker.delayed && calcDelay()))
 			return
 		}
 

package/src/server/Mockaton.js

@@ -8,6 +8,8 @@ import { ServerResponse } from './utils/HttpServerResponse.js'
 import { setCorsHeaders, isPreflight } from './utils/http-cors.js'
 import { IncomingMessage } from './utils/HttpIncomingMessage.js'
 import { watchDevSPA } from './utils/WatcherDevClient.js'
+import { resolveExtensionless } from './utils/resolveExtensionless.js'
+import { bypassImportCache } from './utils/resolveBypassImportCache.js'
 
 import { API } from '../client/ApiConstants.js'
 import { dispatchMock } from './MockDispatcher.js'
@@ -18,9 +20,6 @@ import { cookie } from './stores/cookies.js'
 import { config, initConfig } from './stores/config.js'
 import { watchMocksDir } from './stores/Watcher.js'
 
-import { resolveExtensionless } from './resolveExtensionless.js'
-import { resolveBypassImportCache } from './resolveBypassImportCache.js'
-
 
 export function Mockaton(options) {
 	return new Promise((resolve, reject) => {
@@ -28,10 +27,8 @@ export function Mockaton(options) {
 		cookie.init(config.cookies)
 		brokers.init()
 
-		registerHooks({ resolve: resolveExtensionless })
-
-		if (config.bypassImportCache)
-			registerHooks({ resolve: resolveBypassImportCache })
+		registerHooks({ resolve: resolveExtensionless(['.ts', '.js']) })
+		registerHooks({ resolve: bypassImportCache(config.mocksDir) })
 
 		if (config.watcherEnabled)
 			watchMocksDir()
@@ -43,10 +40,9 @@ export function Mockaton(options) {
 		server.on('error', reject)
 		server.listen(config.port, config.host, () => {
 			const url = `http://${server.address().address}:${server.address().port}`
-			const dashboardUrl = url + API.root
 			logger.info('Listening', url)
-			logger.info('Dashboard', dashboardUrl)
-			config.onReady(dashboardUrl)
+			logger.info('Dashboard', url + API.root)
+			config.onReady(url + API.root)
 			resolve(server)
 		})
 	})

package/src/server/Mockaton.test.config.js

@@ -1,4 +1,4 @@
-import { jwtCookie } from '../../index.js'
+import { jwtCookie, shouldIgnore } from '../../index.js'
 
 export default {
 	cookies: {
@@ -12,5 +12,6 @@ export default {
 	corsExposedHeaders: ['Content-Encoding'],
 	readOnly: false,
 	watcherEnabled: false, // But we enable it at run-time
-	watcherDebounceMs: 0
+	watcherDebounceMs: 0,
+	shouldIgnore: f => shouldIgnore(f) || f.endsWith('.skip.js'),
 }

package/src/server/Mockaton.test.js

@@ -536,6 +536,14 @@ describe('404', () => {
 		equal(r.status, 404)
 		await fx.delete()
 	})
+
+	test('404s ignored files', async () => {
+		const fx = new Fixture('custom_ignore.GET.200.skip.js')
+		await fx.write()
+		const r = await fx.request()
+		equal(r.status, 404)
+		await fx.delete()
+	})
 })
 
 
@@ -1021,8 +1029,9 @@ describe('Write and Delete Mock', () => {
 
 	test('write and delete (with watcher)', async () => {
 		await api.setWatchMocks(true)
-		const file = 'new-mock.GET.200.txt'
+		await sleep(0) // for macOS
 
+		const file = 'new-mock.GET.200.txt'
 		const nextVerPromise = resolveOnNextSyncVersion()
 		const res = await api.writeMock(file, '')
 		equal(res.status, 200)
@@ -1117,9 +1126,6 @@ describe('Registering Mocks', () => {
 		}
 	}
 
-	function sleep(ms) {
-		return new Promise(resolve => setTimeout(resolve, ms))
-	}
 
 	const fxA = new FixtureExternal('register(default).GET.200.json')
 	const fxB = new FixtureExternal('register(alt).GET.200.json')
@@ -1218,10 +1224,7 @@ describe('Registering Mocks', () => {
 })
 
 
-/** Uses the native `EventSource` to listen for real-time sync-version updates.
- * It resolves when a new version is pushed that differs from `currSyncVer`;
- * when `currSyncVer` is omitted, the first push after the initial connection is
- * used. */
+/** Resolves when a new mock is added, deleted, or renamed. */
 function resolveOnNextSyncVersion(currSyncVer = undefined) {
 	let skipFirst = currSyncVer === undefined
 	return new Promise((resolve, reject) => {
@@ -1243,3 +1246,7 @@ function resolveOnNextSyncVersion(currSyncVer = undefined) {
 		}
 	})
 }
+
+function sleep(ms) {
+	return new Promise(resolve => setTimeout(resolve, ms))
+}

package/src/server/UrlParsers.js

@@ -8,13 +8,6 @@ export function parseQueryParams(url) {
 	return new URL(url, 'http://_').searchParams
 }
 
-/** @deprecated Use parseSegments */
-export function parseSplats(url, filename) {
-	console.info('parseSplats is deprecated in favor of parseSegments')
-	return parseSegments(url, filename)
-}
-
-
 export function parseSegments(url, filename) {
 	const { urlMask } = parseFilename(relative(config.mocksDir, filename))
 

package/src/server/stores/brokers.js

@@ -1,4 +1,4 @@
-import { config, isFileAllowed } from './config.js'
+import { config } from './config.js'
 import { MockBroker } from '../MockBroker.js'
 import { listFilesRecursively } from '../utils/fs.js'
 import { parseFilename } from '../../client/Filename.js'
@@ -33,7 +33,7 @@ export function init() {
 
 /** @returns {boolean} registered */
 export function registerMock(file, isFromWatcher = false) {
-	if (brokerByFilename(file)?.hasMock(file) || !isFileAllowed(file))
+	if (brokerByFilename(file)?.hasMock(file) || config.shouldIgnore(file))
 		return false
 
 	const { method, urlMask } = parseFilename(file)

package/src/server/stores/config.js

@@ -1,4 +1,4 @@
-import { resolve, basename } from 'node:path'
+import { resolve } from 'node:path'
 import { lstatSync } from 'node:fs'
 import { METHODS } from 'node:http'
 
@@ -18,7 +18,7 @@ import { jsToJsonPlugin } from '../MockDispatcherPlugins.js'
  * }} */
 const schema = {
 	mocksDir: [resolve('mockaton-mocks'), p => !lstatSync(p).isDirectory()],
-	ignore: [/(\.DS_Store|~)$/, is(RegExp)],
+	shouldIgnore: [shouldIgnore, is(Function)],
 	readOnly: [true, is(Boolean)],
 	watcherEnabled: [true, is(Boolean)],
 	watcherDebounceMs: [80, isInt(0, 5000)],
@@ -48,7 +48,6 @@ const schema = {
 	corsMaxAge: [0, is(Number)],
 
 	hotReload: [false, is(Boolean)],
-	bypassImportCache: [true, is(Boolean)],
 
 	// Non-serializable
 	plugins: [[[/\.(js|ts)$/, jsToJsonPlugin]], is(Array)],
@@ -78,7 +77,7 @@ export function initConfig(opts) {
 		opts.mocksDir = resolve(opts.mocksDir)
 
 	Object.assign(config, opts)
-	originalOpts = deepCloneExcluding(config, 'plugins', 'onReady')
+	originalOpts = deepCloneExcluding(config, 'plugins', 'onReady', 'shouldIgnore')
 
 	validate(config, ConfigValidator)
 	logger.setLevel(config.logLevel)
@@ -89,7 +88,15 @@ export function reinitConfig() {
 	initConfig(originalOpts)
 }
 
-export const isFileAllowed = f => !config.ignore.test(basename(f))
+export function shouldIgnore(f) {
+	return (
+		f.startsWith('.git/') ||
+		f.startsWith('.idea/') ||
+		f.startsWith('node_modules/') ||
+		f.endsWith('~') ||
+		f.endsWith('.DS_Store')
+	)
+}
 
 export const calcDelay = () => config.delayJitter
 	? config.delay * (1 + Math.random() * config.delayJitter)

package/src/server/utils/HttpServerResponse.js

@@ -1,7 +1,6 @@
 import fs from 'node:fs'
 import http from 'node:http'
 import { pipeline } from 'node:stream/promises'
-
 import { mimeFor } from './mime.js'
 
 

package/src/server/utils/resolveBypassImportCache.js

@@ -0,0 +1,21 @@
+import { realpathSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+export function bypassImportCache(srcPath) {
+	const resolvedSrcPath = pathToFileURL(realpathSync(srcPath)).href
+
+	// We register this `resolve` hook at runtime so it doesn't interfere with non-dynamic imports.
+	return function resolve(specifier, context, nextResolve) {
+		const result = nextResolve(specifier, context)
+		if (result.url.startsWith(resolvedSrcPath)) {
+			const url = new URL(result.url)
+			url.searchParams.set('t', performance.now())
+			return {
+				...result,
+				url: url.href,
+				shortCircuit: true
+			}
+		}
+		return result
+	}
+}

package/src/server/utils/resolveExtensionless.js

@@ -0,0 +1,22 @@
+import { existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+
+export function resolveExtensionless(extensions) {
+	return function resolve(specifier, context, nextResolve) {
+		try {
+			return nextResolve(specifier, context)
+		}
+		catch (error) {
+			// Attempt to resolve imports with appended extension
+			if (error.code === 'ERR_MODULE_NOT_FOUND' && specifier.startsWith('.') && context.parentURL) {
+				const absPath = join(dirname(fileURLToPath(context.parentURL)), specifier)
+				for (const candidate of extensions.map(ext => absPath + ext))
+					if (existsSync(candidate))
+						return resolve(pathToFileURL(candidate).href, context, nextResolve)
+			}
+			throw error
+		}
+	}
+}

package/src/server/resolveBypassImportCache.js

@@ -1,19 +0,0 @@
-import { resolve as _resolve } from 'node:path'
-
-const mockatonSrcRoot = `file://${_resolve(import.meta.dirname, '..')}`
-
-// We register this hook at runtime so it doesn’t interfere with non-dynamic imports. 
-// It cache-busts by appending timestamp query param
-export function resolveBypassImportCache(specifier, context, nextResolve) {
-	const result = nextResolve(specifier, context)
-	if (result.url?.startsWith('file://') && !result.url.startsWith(mockatonSrcRoot)) {
-		const url = new URL(result.url)
-		url.searchParams.set('t', performance.now())
-		return {
-			...result,
-			url: url.href,
-			shortCircuit: true
-		}
-	}
-	return result
-}

package/src/server/resolveExtensionless.js

@@ -1,20 +0,0 @@
-import { existsSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-
-
-export function resolveExtensionless(specifier, context, nextResolve) {
-	try {
-		return nextResolve(specifier, context)
-	}
-	catch (error) {
-		// Attempt to resolve imports as .ts and .js
-		if (error.code === 'ERR_MODULE_NOT_FOUND' && specifier.startsWith('.') && context.parentURL) {
-			const absPath = join(dirname(fileURLToPath(context.parentURL)), specifier)
-			for (const candidate of ['.ts', '.js'].map(ext => absPath + ext))
-				if (existsSync(candidate))
-					return resolveExtensionless(pathToFileURL(candidate).href, context, nextResolve)
-		}
-		throw error
-	}
-}