mockaton 0.9.10 → 0.10.1

package/README.md

@@ -1,13 +1,11 @@
 # Mockaton 
 _Mockaton_ is a mock server for developing and testing frontends.
 
-It scans `Config.mocksDir` for files following a specific directory
-and file name convention, which is similar to the URL paths. For
+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/
-   |-- user/
-       |-- [user-id].GET.200.json
+my-mocks-dir/api/user/[user-id].GET.200.json
 ```
 
 By the way, [this browser
@@ -17,14 +15,21 @@ be used for downloading a TAR of your XHR requests following that convention.
 
 ### Mock Variants
 Each route can have many mocks, which could either be:
-- Different response status code. For example, for testing error responses.
-- Comment on the filename, which is anything within parentheses.
+- Different response __status code__. 
+  - e.g. for testing error responses. BTW, an _Internal Server
+    Error_ mock is autogenerated for routes that have no 500.
+- __Comment__ on the filename, which is anything within parentheses.
+  - e.g. `api/user(my-comment).POST.201.json`
 
 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.
 
+### Proxying Routes
+`Config.proxyFallback` lets you specify a target
+server for serving routes you don’t have mocks for.
+
 
 ## Getting Started
 The best way to learn _Mockaton_ is by checking out this repo and
@@ -34,20 +39,6 @@ exploring its [sample-mocks/](./sample-mocks) directory. Then, run
 ![](./README-dashboard.png)
 
 
-### Mock Variants of Status Code
-The **sample-mocks/** directory has three mock alternatives for serving
-`/api/user/friends`:
-- _200 - OK_
-- _204 - No Content_ with an empty list of friends
-- _500 - Internal Server Error_
-	- BTW, 500 mocks get autogenerated for routes that have no 500’s.
-
-![](./README-dashboard-dropdown.png)
-
-### Mock Variants with Comments
-Comments are anything within parentheses, including them.
-![](./README-mocks-with-comments.png)
-
 ## Delay 🕓
 The clock icon next to the mock selector is a checkbox for delaying a
 particular response. They are handy for testing spinners.
@@ -63,12 +54,11 @@ npm install mockaton
 Create a `my-mockaton.js` file
 ```js
 import { resolve } from 'node:path'
-import { Mockaton } from 'src/Mockaton'
-
+import { Mockaton } from 'mockaton'
 
-Mockaton({ // Config options
-	port: 2345,
-	mocksDir: resolve('my-mocks-dir')
+Mockaton({
+  mocksDir: resolve('my-mocks-dir'),
+	port: 2345
 })
 ```
 
@@ -84,9 +74,10 @@ interface Config {
   host?: string, // 'localhost'
   port?: number // 0 auto-assigned
   delay?: number // 1200 ms
-  cookies?(): object 
+  cookies?: object 
   database?: object // for "Transforms"
   skipOpen?: boolean // Prevents opening the dashboard in a browser
+  proxyFallback?: string // e.g. http://localhost:9999 Target for relaying routes without mocks
   allowedExt?: RegExp // /\.(json|txt|md|mjs)$/ Just for excluding temporary editor files (e.g. JetBrains appends a ~)
 }
 ```
@@ -95,16 +86,16 @@ interface Config {
 ```js
 import { jwtCookie } from 'src/Mockaton'
 
-
 Config.cookies = {
-	'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'
-	})
+  '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'
+  })
 }
 ```
+The key is just a label used in dashboard for selecting the desired cookie.
 
 That `jwtCookie` has a hardcoded header and signature. In other
 words, it’s useful iff you care about its payload in the frontend.
@@ -179,9 +170,9 @@ with `.mjs` will process the mock before serving it.
 
 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
-  Config.database.myCount++
+export default function capitalizeAllText(mockAsText, requestBody, config) {
+  config.database.myCount ??= 0
+  config.database.myCount++
   return mockAsText.toUpperCase()
 }
 ```

package/Tests.js

@@ -3,6 +3,7 @@
 import { tmpdir } from 'node:os'
 import { dirname } from 'node:path'
 import { describe, it } from 'node:test'
+import { createServer } from 'node:http'
 import { equal, deepEqual, match } from 'node:assert/strict'
 import { writeFileSync, mkdtempSync, mkdirSync } from 'node:fs'
 
@@ -98,17 +99,22 @@ writeStatic('index.html', '<h1>Static</h1>')
 writeStatic('assets/app.js', 'const app = 1')
 writeStatic('another-entry/index.html', '<h1>Another</h1>')
 
-
-const server = Mockaton({
-	mocksDir: tmpDir,
-	staticDir: staticTmpDir,
-	skipOpen: true,
-	cookies: {
-		userA: 'CookieA',
-		userB: 'CookieB'
-	}
+let server
+const fallbackServer = createServer((_, response) => {
+	response.end('From_Fallback_Server')
+}).listen(0, 'localhost', function () {
+	server = Mockaton({
+		mocksDir: tmpDir,
+		staticDir: staticTmpDir,
+		skipOpen: true,
+		cookies: {
+			userA: 'CookieA',
+			userB: 'CookieB'
+		},
+		proxyFallback: `http://localhost:${fallbackServer.address().port}`
+	})
+	server.on('listening', runTests)
 })
-server.on('listening', runTests)
 
 async function runTests() {
 	await testItRendersDashboard()
@@ -157,7 +163,9 @@ async function runTests() {
 	await testTransforms()
 	await testStaticFileServing()
 	await testInvalidFilenamesAreIgnored()
+	await testRouteWithoutMocksRelaysGetsProxied()
 	server.close()
+	fallbackServer.close()
 }
 
 async function reset() {
@@ -350,6 +358,12 @@ async function testInvalidFilenamesAreIgnored() {
 	})
 }
 
+async function testRouteWithoutMocksRelaysGetsProxied() {
+	await it('Fallback relay', async () => {
+		const res = await request('/non-existing-mock')
+		equal(await res.text(), 'From_Fallback_Server')
+	})
+}
 
 // Utils
 

package/index.d.ts

@@ -6,11 +6,10 @@ interface Config {
 	host?: string,
 	port?: number
 	delay?: number
-
-	cookies?(): object
-
+	cookies?: object
 	database?: object
 	skipOpen?: boolean
+	proxyFallback?: string
 	allowedExt?: RegExp
 }
 

package/package.json

@@ -2,13 +2,13 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing frontend clients",
 	"type": "module",
-	"version": "0.9.10",
+	"version": "0.10.1",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
 	"repository": "https://github.com/ericfortis/mockaton",
 	"scripts": {
 		"test": "./Tests.js",
-		"demo": "_usage_example.js"
+		"demo": "./_usage_example.js"
 	}
 }

package/src/Config.js

@@ -11,6 +11,7 @@ export const Config = {
 	cookies: {}, // defaults to the first kv
 	database: {},
 	skipOpen: false,
+	proxyFallback: '', // e.g. http://localhost:9999
 	allowedExt: /\.(json|txt|md|mjs)$/ // Just for excluding temporary editor files (e.g. JetBrains appends a ~)
 }
 
@@ -25,6 +26,7 @@ export function setup(options) {
 		cookies: is(Object),
 		database: is(Object),
 		skipOpen: is(Boolean),
+		proxyFallback: is(String),
 		allowedExt: is(RegExp)
 	})
 }

package/src/MockDispatcher.js

@@ -2,6 +2,7 @@ import { join } from 'node:path'
 import { readFileSync } from 'node:fs'
 
 import { DF } from './ApiConstants.js'
+import { proxy } from './ProxyRelay.js'
 import { cookie } from './cookie.js'
 import { Config } from './Config.js'
 import { mimeFor } from './utils/mime.js'
@@ -19,10 +20,13 @@ export async function dispatchMock(req, response) {
 
 	const broker = mockBrokerCollection.getBrokerForUrl(req.method, req.url)
 	if (!broker) {
-		sendNotFound(response)
+		if (Config.proxyFallback)
+			await proxy(req, response)
+		else
+			sendNotFound(response) // TESTME
 		return
 	}
-	
+
 	try {
 		const { file, status, delay, currentTransform } = broker
 		console.log('\n', req.url, '→\n ', file)

package/src/ProxyRelay.js

@@ -0,0 +1,11 @@
+import { Config } from './Config.js'
+
+
+export async function proxy(req, response) {
+	const proxyResponse = await fetch(Config.proxyFallback + req.url, {
+		method: req.method,
+		headers: req.headers
+	})
+	response.writeHead(proxyResponse.status, proxyResponse.headers)
+	response.end(await proxyResponse.text())
+}