mockaton 8.12.8 → 8.12.10

package/README.md

@@ -2,16 +2,20 @@
 
 ![NPM Version](https://img.shields.io/npm/v/mockaton)
 ![NPM Version](https://img.shields.io/npm/l/mockaton)
+[![Test](https://github.com/ericfortis/mockaton/actions/workflows/test.yml/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/test.yml)
+[![CodeQL](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/ericfortis/mockaton/actions/workflows/github-code-scanning/codeql)
 
 An HTTP mock server for simulating APIs with minimal setup
 — ideal for triggering difficult to reproduce backend states.
 
 
 ## Overview
-With Mockaton, you don’t need to write code for wiring up your mocks. Instead, a
-given directory is scanned for filenames following a convention similar to the URLs.
+With Mockaton, you don’t need to write code for wiring up your
+mocks. Instead, a given directory is scanned for filenames
+following a convention similar to the URLs. 
+
+For example, for [/api/user/123](#), the mock filename could be:
 
-For example, for <code>/<b>api/user</b>/1234</code> the filename would be:
 <pre>
 <code>my-mocks-dir/<b>api/user</b>/[user-id].GET.200.json</code>
 </pre>
@@ -20,15 +24,14 @@ For example, for <code>/<b>api/user</b>/1234</code> the filename would be:
 ## Dashboard
 
 On the dashboard you can select a mock variant for a particular route, delaying responses,
-or triggering an autogenerated `500` (Internal Server Error), among other features.
-
+or triggering an autogenerated `500` error, among other features.
 Nonetheless, there’s a programmatic API, which is handy
 for setting up tests (see **Commander&nbsp;API** section).
 
 <picture>
-  <source media="(prefers-color-scheme: light)" srcset="./pixaton-tests/pic-for-readme.vp840x800.light.gold.png">
-  <source media="(prefers-color-scheme: dark)" srcset="./pixaton-tests/pic-for-readme.vp840x800.dark.gold.png">
-  <img alt="Mockaton Dashboard" src="./pixaton-tests/pic-for-readme.vp840x800.light.gold.png">
+  <source media="(prefers-color-scheme: light)" srcset="pixaton-tests/macos/pic-for-readme.vp840x800.light.gold.png">
+  <source media="(prefers-color-scheme: dark)" srcset="pixaton-tests/macos/pic-for-readme.vp840x800.dark.gold.png">
+  <img alt="Mockaton Dashboard" src="pixaton-tests/macos/pic-for-readme.vp840x800.light.gold.png">
 </picture>
 
 
@@ -60,12 +63,12 @@ api/videos.GET.<b>500</b>.txt               # Internal Server Error
 <br/>
 
 ## Fallback to Your Backend
-No need to mock everything. Mockaton can forward requests to your backend for routes
+No need to mock everything. You can forward requests to your backend for routes
 you don’t have mocks for, or routes that have the ☁️ **Cloud Checkbox** checked.
 
 
 ### Scraping mocks from your backend
-If you check **Save Mocks**, Mockaton will collect the responses that hit your backend.
+By checking ✅ **Save Mocks**, you can collect the responses that hit your backend.
 They will be saved in your `config.mocksDir` following the filename convention.
 
 
@@ -73,12 +76,10 @@ They will be saved in your `config.mocksDir` following the filename convention.
 
 
 ## Basic Usage
-Mockaton is a Node.js program with no build or runtime NPM dependencies.
-
-`tsx` is only needed if you want to write mocks in TypeScript.
+Mockaton is a Node.js program.
 
 ```sh
-npm install mockaton tsx --save-dev
+npm install mockaton --save-dev
 ```
 
 Create a `my-mockaton.js` file
@@ -94,7 +95,7 @@ Mockaton({
 ```
 
 ```sh
-node --import=tsx my-mockaton.js
+node my-mockaton.js
 ```
 
 <br/>
@@ -111,15 +112,16 @@ cd mockaton/demo-app-vite
 npm install 
 
 npm run mockaton
-npm run start
-# BTW, that directory has scripts for running Mockaton and Vite 
-# with one command in two terminals.
+npm run start # in another terminal
+
+# BTW, that directory has scripts for running both 
+# servers with one command in two terminals.
 ```
 
 
 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" />
+<img src="./demo-app-vite/pixaton-tests/pic-for-readme.vp740x880.light.gold.png" alt="Mockaton Demo App Screenshot" width="740" />
 
 <br/>
 
@@ -167,7 +169,7 @@ For example, `api/foo.GET.200.js`
 **Option A:** An Object, Array, or String is sent as JSON.
 
 ```js
-export default [{ foo: 'bar' }]
+export default { foo: 'bar' }
 ```
 
 **Option B:** Function
@@ -205,7 +207,7 @@ export default async function insertColor(request, response) {
 }
 ```
 
-`api/colors(assorted)(default).GET.200.ts`
+`api/colors.GET.200.js`
 ```js
 import colorsFixture from './colors.json' with { type: 'json' }
 
@@ -364,17 +366,16 @@ or that you manually picked with the ☁️ **Cloud Checkbox**.
 
 ### `collectProxied?: boolean`
 Defaults to `false`. With this flag you can save mocks that hit
-your proxy fallback to `config.mocksDir`. If there are UUIDv4 in the
-URL, the filename will have `[id]` in their place. For example,
+your proxy fallback to `config.mocksDir`. If the URL has v4 UUIDs, 
+the filename will have `[id]` in their place. For example:
 
-```
-/api/user/d14e09c8-d970-4b07-be42-b2f4ee22f0a6/likes =>
-  my-mocks-dir/api/user/[id]/likes.GET.200.json
-```
+<pre>
+<b>/api/user/</b>d14e09c8-d970-4b07-be42-b2f4ee22f0a6<b>/likes</b> =>
+  my-mocks-dir<b>/api/user/</b>[id]<b>/likes</b>.GET.200.json
+</pre>
 
-Your existing mocks won’t be overwritten. That is, the routes you manually
-selected for using your backend with the ☁️ **Cloud Checkbox**, will have
-a unique filename comment.
+Your existing mocks won’t be overwritten. In other words, responses of routes with
+the ☁️ **Cloud Checkbox** selected will be saved with unique filename-comments.
 
 
 <details>
@@ -386,14 +387,14 @@ header was not sent by your backend.
 
 <p>
 An <code>.unknown</code> extension means the <code>Content-Type</code> is not in
-Mockaton’s predefined list. For that, you can add it to <code>config.extraMimes</code>
+the predefined list. For that, you can add it to <code>config.extraMimes</code>
 </p>
 </details>
 
 
 ### `formatCollectedJSON?: boolean`
-Defaults to `true`. Saves the mock with the formatting output
-of `JSON.stringify(data, null, '  ')` (two spaces indentation).
+Defaults to `true`. Saves the mock with two spaces indentation &mdash; 
+the formatting output of `JSON.stringify(data, null, '  ')`
 
 
 <br/>
@@ -410,14 +411,16 @@ config.cookies = {
   'My JWT': jwtCookie('my-cookie', {
     name: 'John Doe',
     picture: 'https://cdn.auth0.com/avatars/jd.png'
-  })
+  }),
+  'None': ''
 }
 ```
-The selected cookie, which is the first one by default, 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 (as long as its value is not an empty string). The object key is just
+a label for UI display purposes, and also for selecting a cookie via the Commander API.
 
-If you need to send more cookies, you can either inject them globally
-in `config.extraHeaders`, or in function `.js` or `.ts` mock.
+If you need to send more than one cookie, you can inject them globally 
+in `config.extraHeaders`, or individually in a function `.js` or `.ts` mock.
 
 By the way, the `jwtCookie` helper has a hardcoded header and signature.
 In other words, it’s useful only if you care about its payload.
@@ -478,8 +481,8 @@ import { jsToJsonPlugin } from 'mockaton'
 
 config.plugins = [
   
-  // Although `jsToJsonPlugin` is set by default, you need to add it to your list if you need it.
-  // In other words, your plugins array overwrites the default list. This way you can remove it.
+  // Although `jsToJsonPlugin` is set by default, you need to include it if you need it.
+  // IOW, your plugins array overwrites the default list. This way you can remove it.
   [/\.(js|ts)$/, jsToJsonPlugin], 
   
   [/\.yml$/, yamlToJsonPlugin],
@@ -506,6 +509,10 @@ function capitalizePlugin(filePath) {
 
 ### `corsAllowed?: boolean`
 Defaults to `true`. When `true`, these are the default options:
+
+<details>
+<summary>CORS Options</summary>
+
 ```js
 config.corsOrigins = ['*']
 config.corsMethods = require('node:http').METHODS
@@ -514,13 +521,14 @@ config.corsCredentials = true
 config.corsMaxAge = 0 // seconds to cache the preflight req
 config.corsExposedHeaders = [] // headers you need to access in client-side JS
 ```
+</details>
 
 <br/>
 
 ### `onReady?: (dashboardUrl: string) => void`
 By default, it will open the dashboard in your default browser on macOS and
 Windows. But for a more cross-platform utility you could `npm install open` and
-Mockaton will use that implementation instead.
+that implementation will be automatically used instead.
 
 If you don’t want to open a browser, pass a noop:
 ```js
@@ -552,9 +560,9 @@ await mockaton.select('api/foo.200.GET.json')
 ```js
 await mockaton.bulkSelectByComment('(demo-a)')
 ```
-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.
+Parentheses are optional, so you can pass a partial match. For example,
+passing `'demo-'` (without the final `a`) works too. On routes
+with many partial matches, their first mock in alphabetical order wins.
 
 <br/>
 

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "HTTP Mock Server",
 	"type": "module",
-	"version": "8.12.8",
+	"version": "8.12.10",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",
@@ -19,13 +19,12 @@
 		"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\"",
 		"outdated": "npm outdated --parseable | awk -F: '{ printf \"npm i %-30s ;# %s\\n\", $4, $2 }'"
 	},
 	"optionalDependencies": {
 		"open": "^10.0.0",
-		"pixaton": ">=1.0.2",
+		"pixaton": ">=1.1.1",
 		"puppeteer": ">=24.1.1"
 	}
 }

package/src/Commander.js

@@ -1,7 +1,7 @@
 import { API, DF, LONG_POLL_SERVER_TIMEOUT } from './ApiConstants.js'
 
 
-// Client for controlling Mockaton via its HTTP API
+/** Client for controlling Mockaton via its HTTP API */
 export class Commander {
 	#addr = ''
 	constructor(addr) {

package/src/Dashboard.css

@@ -288,6 +288,7 @@ select {
 	border-radius: var(--radius);
 	color: var(--colorAccent);
 	text-decoration: none;
+	word-break: break-word;
 
 	&:hover {
 		background: var(--colorHover);