mockaton 8.12.0 → 8.12.2

package/README.md

@@ -3,10 +3,10 @@
 ![NPM Version](https://img.shields.io/npm/v/mockaton)
 ![NPM Version](https://img.shields.io/npm/l/mockaton)
 
-Mockaton is an HTTP mock server for enhancing the development and testing experience.
-
-## Convention over Code
+An HTTP mock server for simulating APIs with minimal setup
+— ideal for testing edge cases and prototyping UIs.
 
+## Convention Over Code
 With Mockaton you don’t need to write code for wiring mocks. Instead, it scans a
 given directory for filenames following a convention similar to the URLs.
 
@@ -31,12 +31,14 @@ for setting up tests. See **Commander API** section.
 </picture>
 
 
+<br/>
+<br/>
+
 ## Multiple Mock Variants
-Each route can have different mocks. There’s two options for doing that:
+Each route can have different mocks. There are two options for doing that:
 
 ### Adding comments to the filename
-Comments are anything within parentheses,
-including them. A filename can have many comments.
+Comments are anything within parentheses, including them.
 
 <pre>
 api/login<b>(locked out user)</b>.POST.423.json
@@ -44,8 +46,8 @@ api/login<b>(invalid login attempt)</b>.POST.401.json
 </pre>
 
 ### Different response status code
-For instance, using a `4xx` or `5xx` status code for triggering error
-responses. Or a `2xx` such as `204` (No Content) for testing empty collections.
+For instance, you can use a `4xx` or `5xx` status code for triggering error
+responses, or a `2xx` such as `204` (No Content) for testing empty collections.
 
 <pre>
 api/videos(empty list).GET.<b>204</b>.json
@@ -54,16 +56,19 @@ api/videos.GET.<b>500</b>.txt
 </pre>
 
 
+<br/>
 
-## Fallback to your Backend
-No need to mock everything. Mockaton can request from your backend the routes
+## Fallback to Your Backend
+No need to mock everything. Mockaton can forward requests to your backend for routes
 you don’t have mocks for, or routes that have the ☁️ **Cloud Checkbox** checked.
 
 
-### Scrapping Mocks from your Backend
+### Scraping mocks from your backend
 If you check **Save Mocks**, Mockaton will collect the responses that hit your backend.
-They will be saved on your `config.mocksDir` following the filename convention.
+They will be saved in your `config.mocksDir` following the filename convention.
+
 
+<br/>
 
 
 ## Basic Usage
@@ -91,11 +96,12 @@ Mockaton({
 node --import=tsx my-mockaton.js
 ```
 
+<br/>
 
 ## Demo App (Vite)
 
 This is a minimal React + Vite + Mockaton app. It’s a list of
-colors, which contains all of their possible states. For example,
+colors containing all of their possible states. For example,
 permutations for out-of-stock, new-arrival, and discontinued.
 
 ```sh  
@@ -114,6 +120,7 @@ The app looks like this:
 
 <img src="./demo-app-vite/pixaton-tests/pic-for-readme.vp500x800.light.gold.png" alt="Mockaton Demo App Screenshot" width="500" />
 
+<br/>
 
 ## Use Cases
 ### Testing
@@ -121,34 +128,35 @@ The app looks like this:
 - Spinners by delaying responses
 - Errors such as _Bad Request_ and _Internal Server Error_
 - Setting up UI tests
+- Mocking third-party APIs
 - Polled resources (for triggering their different states)
   - alerts
   - notifications
   - slow to build resources
-- Mocking third-party APIs
 
-### Time Travel
-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.
+### Time travel
+If you commit the mocks to your repo, it’s straightforward to
+bisect bugs and check out long-lived branches, so you don’t
+have to downgrade backends to old API contracts or databases.
+
+### Simulating complex backend states
+Sometimes, the ideal flow you need is too difficult to reproduce from your actual backend.
+For this, you can **Bulk Select** mocks by comments to simulate the complete states
+you want. For example, by adding `(demo-part1)`, `(demo-part2)` to the filenames.
 
-### Deterministic Standalone Demo Server
-Perhaps you need to demo your app, but the ideal flow is too complex to
-simulate from the actual backend. In this case, compile your frontend app and
-put its built assets in `config.staticDir`. Then, on the dashboard
-**Bulk Select** mocks to simulate the complete states you want to demo.
-For bulk-selecting, you just need to add a comment to the mock
-filename, such as `(demo-part1)`, `(demo-part2)`.
+Similarly, you can deploy a **Standalone Demo Server** by compiling the frontend app and
+putting its built assets in `config.staticDir`. And simulate the flow by Bulk Selecting mocks.
 
 
+<br/>
+
 ## Motivation
-- Avoids spinning up and maintaining hefty backends when developing UIs.
-- For a deterministic, comprehensive, and consistent backend state. For example, having
+- Avoids spinning up and updating hefty backends when developing UIs.
+- Allows for a deterministic, comprehensive, and consistent backend state. For example, having
   a collection with all the possible state variants helps for spotting inadvertent bugs.
-- Sometimes frontend progress is blocked waiting for some backend API. Similarly,
-  it’s often delayed due to missing data or inconvenient contracts. Therefore,
-  many meetings can be saved by prototyping frontend features with mocks, and
-  then showing those contracts to the backend team.
+- Sometimes frontend progress is blocked by waiting for backend APIs.
+
+<br/>
 
 ## Alternatives
 - Chrome DevTools allows for [overriding responses](https://developer.chrome.com/docs/devtools/overrides)
@@ -158,7 +166,8 @@ filename, such as `(demo-part1)`, `(demo-part2)`.
 - [Fetch Mock](https://github.com/wheresrhys/fetch-mock)
 - [Mentoss](https://github.com/humanwhocodes/mentoss)
 
----
+
+<br/>
 
 ## You can write JSON mocks in JavaScript or TypeScript
 For example, `api/foo.GET.200.js`
@@ -179,7 +188,7 @@ export default (request, response) =>
   JSON.stringify({ foo: 'bar' })
 ```
 
-Think of these functions as HTTP handlers, so you can
+Think of these functions as HTTP handlers that allow you to
 intercept requests. For example, for writing to a database.
 
 <details>
@@ -221,7 +230,7 @@ export default function listColors() {
 **What if I need to serve a static .js?**
 Put it in your `config.staticDir` without the mock filename convention.
 
----
+<br/>
 
 ## Mock Filename Convention
 
@@ -256,7 +265,7 @@ want a `Content-Type` header in the response.
 </p>
 </details>
 
-### Dynamic Parameters
+### Dynamic parameters
 Anything within square brackets is always matched. For example, for this route
 `/api/company/1234/user/5678`
 <pre>
@@ -265,14 +274,16 @@ api/company/<b>[id]</b>/user/<b>[uid]</b>.GET.200.json
 
 ### Comments
 Comments are anything within parentheses, including them.
-They are ignored for URL purposes, so they have no effect
+They are ignored for routing purposes, so they have no effect
 on the URL mask. For example, these two are for `/api/foo`
 <pre>
 api/foo<b>(my comment)</b>.GET.200.json
 api/foo.GET.200.json
 </pre>
 
-### Default Mock for a Route
+A filename can have many comments.
+
+### Default mock for a route
 You can add the comment: `(default)`. 
 Otherwise, the first file in **alphabetical order** wins.
 
@@ -281,7 +292,7 @@ api/user<b>(default)</b>.GET.200.json
 </pre>
 
 
-### Query String Params
+### Query string params
 The query string is ignored when routing to it. In other words, it’s only used for
 documenting the URL contract.
 <pre>
@@ -307,7 +318,8 @@ api/foo/.GET.200.json
 api/foo/bar.GET.200.json
 ```
 
----
+<br/>
+
 ## Config
 ### `mocksDir: string`
 This is the only required field. The directory must exist.
@@ -354,7 +366,7 @@ a unique filename comment.
 
 
 <details>
-  <summary>Extension Details</summary>
+  <summary>Extension details</summary>
 <p>
 An <code>.empty</code> extension means the <code>Content-Type</code>
 header was not sent by your backend.
@@ -378,12 +390,12 @@ of `JSON.stringify(data, null, '  ')` (two spaces indentation).
   build your frontend bundle, and serve it from Mockaton.
 
 Files under `config.staticDir` don’t use the filename convention, and
-they take precedence over `GET` mocks in `config.mocksDir`.
+they take precedence over corresponding `GET` mocks in `config.mocksDir`.
 For example, if you have two files for `GET /foo/bar.jpg`
 
 <pre>
 my-static-dir<b>/foo/bar.jpg</b>
- my-mocks-dir<b>/foo/bar.jpg</b>.GET.200.jpg // Unreacheable
+ my-mocks-dir<b>/foo/bar.jpg</b>.GET.200.jpg // Unreachable
 </pre>
 
 
@@ -412,7 +424,7 @@ In other words, it’s useful only if you care about its payload.
 
 
 ### `extraHeaders?: string[]`
-Note it’s a unidimensional array. The header name goes at even indices.
+Note: it’s a one-dimensional array. The header name goes at even indices.
 
 ```js
 config.extraHeaders = [
@@ -451,7 +463,7 @@ the file from disk and compute the MIME from the extension.
 Note: don’t call `response.end()` on any plugin.
 
 <details>
-<summary><b> See Plugin Examples </b></summary>
+<summary><b> See plugin examples </b></summary>
 
 ```shell
 npm install yaml
@@ -512,7 +524,7 @@ config.onReady = () => {}
 
 At any rate, you can trigger any command besides opening a browser.
 
----
+<br/>
 
 ## Commander API
 `Commander` is a client for Mockaton’s HTTP API.
@@ -536,12 +548,12 @@ 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.
 
-### Set Route is Delayed Flag
+### Set route is delayed flag
 ```js
 await mockaton.setRouteIsDelayed('GET', '/api/foo', true)
 ```
 
-### Set Route is Proxied
+### Set route is proxied
 ```js
 await mockaton.setRouteIsProxied('GET', '/api/foo', true)
 ```
@@ -552,13 +564,13 @@ In `config.cookies`, each key is the label used for selecting it.
 await mockaton.selectCookie('My Normal User')
 ```
 
-### Set Fallback Proxy
+### Set fallback proxy
 ```js
 await mockaton.setProxyFallback('http://example.com')
 ```
 Pass an empty string to disable it.
 
-### Set Save Proxied Mocks
+### Set save proxied mocks
 ```js
 await mockaton.setCollectProxied(true)
 ```
@@ -569,7 +581,3 @@ default, but the `proxyFallback`, `colledProxied`, and `corsAllowed` are not aff
 ```js
 await mockaton.reset()
 ```
-
-<div style="display: flex; align-items: center; gap: 20px">
-  <img src="fixtures-mocks/api/user/avatar.GET.200.png" width="170"/>
-</div>

package/package.json

@@ -2,13 +2,14 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing APIs",
 	"type": "module",
-	"version": "8.12.0",
+	"version": "8.12.2",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
 	"repository": "https://github.com/ericfortis/mockaton",
 	"scripts": {
 		"test": "node --test \"src/**/*.test.js\"",
+		"coverage": "node --test --test-reporter=lcov --test-reporter-destination=.coverage/lcov.info --experimental-test-coverage \"src/**/*.test.js\"",
 		"start": "node dev-mockaton.js",
 		"start:ts": "node --import=tsx dev-mockaton.js",
 		"pixaton": "node --test --import=./pixaton-tests/_setup.js --experimental-test-isolation=none \"pixaton-tests/**/*.test.js\"",

package/src/Mockaton.js

@@ -20,14 +20,15 @@ export function Mockaton(options) {
 	watchMocksDir()
 
 	return createServer(onRequest).listen(config.port, config.host, function (error) {
+		if (error) {
+			console.error(error)
+			return
+		}
 		const { address, port } = this.address()
 		const url = `http://${address}:${port}`
 		console.log('Listening', url)
 		console.log('Dashboard', url + API.dashboard)
-		if (error)
-			console.error(error)
-		else
-			config.onReady(url + API.dashboard)
+		config.onReady(url + API.dashboard)
 	})
 }
 

package/src/ProxyRelay.js

@@ -43,7 +43,7 @@ export async function proxy(req, response, delay) {
 		let data = body
 		if (config.formatCollectedJSON && ext === 'json') // TESTME
 			try {
-				data = JSON.string(JSON.parse(body), null, '  ')
+				data = JSON.stringify(JSON.parse(body), null, '  ')
 			}
 			catch {}
 		write(join(config.mocksDir, filename), data)

package/src/StaticDispatcher.js

@@ -20,7 +20,7 @@ export async function dispatchStatic(req, response) {
 		await sendPartialContent(response, req.headers.range, file)
 	else {
 		response.setHeader('Content-Type', mimeFor(file))
-		response.end(readFileSync(file, 'utf8'))
+		response.end(readFileSync(file))
 	}
 }
 
@@ -57,7 +57,3 @@ async function sendPartialContent(response, range, file) {
 		})
 	}
 }
-
-
-
-