MockMock

MockMock is a TypeScript CLI that turns Confluence API documentation into a running mock API server.

It fetches a Confluence page or local HTML export, parses endpoint definitions into a normalized schema, and starts an Express server that returns generated yet stateful mock responses. It is useful when frontend or integration work needs a realistic API before the real backend is ready.

What This Project Does

• Reads API definitions from Confluence pages or exported HTML files
• Extracts endpoints from both table-based ERD pages and code blocks
• Starts an Express server with dynamically registered routes
• Generates realistic response data with @faker-js/faker
• Keeps data in memory so GET, POST, PUT, PATCH, and DELETE behave like a lightweight API
• Optionally proxies unmatched requests to a fallback server
• Lets you simulate latency with startup flags, runtime endpoints, or stdin commands

How It Works

MockMock has four main steps:

1. The CLI in src/cli.ts reads command-line options and environment variables.
2. The fetcher in src/fetcher/confluence.ts loads HTML from:
   • a file:// path
   • a public Confluence page
   • an authenticated Atlassian Confluence page via REST API
3. The parser in src/parser/erd-parser.ts converts the HTML into a MockSchema.
4. The server in src/server/mock-server.ts registers routes and serves responses backed by the in-memory DataStore.

Runtime Behavior

• GET list endpoints return a generated collection if the response template contains an array.
• GET item endpoints return one stored record when a matching item exists.
• POST creates a new in-memory record.
• PUT and PATCH update an existing record by id.
• DELETE removes an existing record and returns 204.
• If no stored collection exists for an endpoint, MockMock falls back to generating data from the response template on demand.

Architecture

mock-mock/
├── src/
│   ├── cli.ts
│   ├── fetcher/
│   │   └── confluence.ts
│   ├── parser/
│   │   ├── erd-parser.ts
│   │   └── schema-types.ts
│   └── server/
│       ├── data-generator.ts
│       ├── data-store.ts
│       └── mock-server.ts
├── example-confluence.html
├── package.json
└── tsconfig.json

Core Modules

• src/cli.ts: entrypoint, option parsing, orchestration
• src/fetcher/confluence.ts: Confluence and local-file fetching
• src/parser/erd-parser.ts: HTML parsing and endpoint extraction
• src/parser/schema-types.ts: shared contract between parser and server
• src/server/data-generator.ts: fake response generation
• src/server/data-store.ts: in-memory collections and CRUD-like behavior
• src/server/mock-server.ts: Express app, route registration, fallback proxy, health/config endpoints

Installation

Install From npm

npm install -g @mhmdalimansour/mock-mock

This installs the package published on npm as @mhmdalimansour/mock-mock and exposes the CLI command mock-mock.

Local Development

npm install

Build the CLI

npm run build

Global Usage

After installing globally, the CLI command is:

mock-mock --url <confluence-url>

Quick Start

1. Run Against the Example HTML

npm run dev -- --url file://C:/absolute/path/to/example-confluence.html --port 4000

On macOS or Linux:

npm run dev -- --url file:///absolute/path/to/example-confluence.html --port 4000

2. Run Against a Confluence Page

npm run dev -- --url https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title --port 4000

3. Test the Server

curl http://localhost:4000/health
curl http://localhost:4000/api/users
curl -X POST http://localhost:4000/api/users -H "Content-Type: application/json" -d "{\"name\":\"John\"}"

CLI Usage

Development Mode

npm run dev -- --url <url>

Run the Built CLI

npm start -- --url <url>

CLI Options

| Option | Description | Default | | --- | --- | --- | | -u, --url <url> | Confluence page URL or file:// HTML path | required | | -p, --port <port> | Port for the mock server | 4000 | | -f, --fallback <url> | Base URL used for truncated-response hydration during parsing and as a proxy target for unmatched runtime requests | none | | --delay <ms> | Response delay in milliseconds | 0 | | -e, --email <email> | Confluence email, overrides env var | none | | -t, --token <token> | Confluence API token, overrides env var | none | | -d, --debug | Save fetched HTML to debug.html and print parsed schema | false |

Example Commands

npm run dev -- --url file:///tmp/exported-page.html --port 4000
npm run dev -- --url https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title --delay 500
npm run dev -- --url https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456/Page+Title --fallback https://api.dev.example.com

Authentication

Private Confluence pages usually require credentials.

Create a .env file or export the following variables:

[email protected]
CONFLUENCE_API_TOKEN=your-api-token

You can also pass them directly:

npm run dev -- --url <url> --email [email protected] --token your-api-token

Fetching Rules

• file://... reads a local HTML file
• Atlassian Cloud URLs with credentials use the Confluence REST API
• Other URLs are fetched as raw HTML
• If Confluence returns a login page instead of the document, MockMock exits with an authentication error

For more setup details, see AUTH_SETUP.md.

Supported Input Formats

MockMock currently supports two Confluence patterns:

• table-based endpoint documentation
• code blocks containing endpoint definitions

Code Block Format

POST /api/categories

Request:
{
  "name": "string"
}

Response:
{
  "id": 1,
  "name": "string"
}

Status: 201

Supported Methods

• Table-based parsing supports GET, POST, PUT, PATCH, and DELETE.
• Plain code-block parsing currently recognizes GET, POST, PUT, PATCH, and DELETE.
• The server runtime supports PATCH once an endpoint is present in the parsed schema.

Notes About Response Templates

• Response objects are used as templates for fake data generation.
• Response arrays are expanded into collections with about 15 to 30 records.
• Wrapped collections such as { "errors": false, "data": [...] } are preserved.
• If a table-based Response Structure contains ....., MockMock treats it as a truncated example, fetches the live payload from --fallback for safe read-only endpoints, then adds any documented fields that are missing from that payload.
• Path parameters in documentation can use {id} and are converted to Express-style params internally.
• Plain code-block parsing is best with object-shaped JSON responses; table-based ERD pages are more flexible.

Server Endpoints

In addition to parsed API routes, MockMock exposes a few built-in endpoints:

| Endpoint | Method | Purpose | | --- | --- | --- | | /health | GET | Shows registered endpoints and current configuration | | /_config/delay | GET | Returns current response delay | | /_config/delay | PUT | Updates response delay at runtime |

You can also change delay from stdin while the server is running:

delay 500
delay

Developer Guide

Scripts

npm install
npm run build
npm run dev -- --url file://C:/absolute/path/to/example-confluence.html
npm start -- --url file://C:/absolute/path/to/example-confluence.html

Tech Stack

• TypeScript
• Commander
• Axios
• Cheerio
• Express
• Faker

Development Flow

1. Update fetching logic in src/fetcher/ if the Confluence source format changes.
2. Update parsing logic in src/parser/ when new ERD/table/code patterns need to be supported.
3. Keep MockEndpoint and MockSchema in src/parser/schema-types.ts as the contract between layers.
4. Update server behavior in src/server/ when changing how routes, state, or fake responses work.
5. Run npm run build to verify TypeScript compilation.

Important Design Choices

• The parser and server communicate through a simple schema contract.
• The server is stateful only in memory; restarting the process resets all data.
• Fake data generation is template-driven, so response structure depends on the documentation input.
• Collections are derived from GET endpoints that expose arrays in the response template.

Project Structure for Contributors

• example-confluence.html: local test fixture
• README.md: main project documentation
• AUTH_SETUP.md: authentication help
• QUICKSTART.md: short setup walkthrough
• CONTRIBUTING.md: contributor notes

Troubleshooting

No endpoints found

• Check that the Confluence page contains supported tables or code blocks.
• Use --debug to save debug.html and inspect the fetched HTML.

Authentication failed

• Verify CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN.
• Confirm the page is accessible to that account.
• For Atlassian Cloud, make sure the URL contains a valid /pages/<id>/ segment.

Unexpected response shape

• Check the response JSON in Confluence.
• Make sure wrapped arrays or nested objects are valid JSON.
• For truncated ..... examples, provide --fallback so MockMock can hydrate the missing structure from the live API.
• Parse-time fallback hydration is limited to read-only endpoints such as GET; non-GET endpoints keep the documented fields only.
• Remember that fake data is inferred from field names and primitive types.

Changes disappear after restart

This is expected. Data is stored only in memory.

Example Output

MockMock CLI

Fetching Confluence page: https://confluence.example.com/pages/123456
Page fetched successfully

Parsing API endpoints...
Found 3 endpoint(s)

Registering endpoints:
  GET    /api/users
  POST   /api/users
  DELETE /api/users/:id

Mock server started successfully
Base URL: http://localhost:4000
Health check: http://localhost:4000/health

License

MIT