Documentation

- English User Manual: Detailed guide on features, syntax, and usage.
- 中文用户手册: 功能、语法及使用指南。

What is PocketMocker?

PocketMocker is an in-page HTTP controller for frontend development.

In simple terms, it lets you decide what your API responses should be—without touching the backend or setting up a mock server.

It provides a visual control panel directly in your browser to intercept, override, and manipulate HTTP responses, helping you build robust UIs faster by seeing changes instantly.

---

Why PocketMocker?

$3

Stop writing mock code. Intercept requests automatically, generate smart data, import API docs with one click.

$3

* Timing: Simulate network latency, race conditions
* Status: Force 500 errors, 401 unauthorized, empty responses
* Payload: Test edge cases and exception scenarios

$3

Edit responses directly in your browser and see UI updates instantly. No tool switching, stay in the flow.

---

Real-World Use Cases

$3

Toggle between Success, Error (500/404), or Empty Data states in one click. verify how your UI handles loading spinners or error toasts without changing a single line of code.

$3

Need to test a long username? A missing avatar? Or a specific price format? Just edit the response JSON directly in the panel and see the UI update instantly.

$3

Simulate network delays (latency), timeout errors, or unauthorized (401) responses to ensure your application handles exceptions gracefully.

https://github.com/user-attachments/assets/e7501191-7ef1-4bd4-bd21-6500585fe4ad

Installation

``bash
npm install pocket-mocker --save-dev


or

yarn add pocket-mocker -D

or

pnpm add pocket-mocker -D
`

---

Quick Start

$3

Perfect for individual development or quick experimentation. Simply import and start in your project's entry file:

`javascript
import { pocketMock } from 'pocket-mocker';

// Only start in development environment
if (process.env.NODE_ENV === 'development') {
pocketMock();
}
`

After starting your project, you'll see the PocketMock floating panel in the bottom-right corner.

$3

Ideal for production-level projects. The Vite plugin integrates with the file system, saving Mock rules to config files for team sharing.

1. Import and start in your project's entry file:

`javascript
import { pocketMock } from 'pocket-mocker';

if (process.env.NODE_ENV === 'development') {
pocketMock();
}
`

2. Configure vite.config.ts

`typescript
import { defineConfig } from 'vite';
import pocketMockPlugin from 'pocket-mocker/vite-plugin';

export default defineConfig({
plugins: [
pocketMockPlugin()
]
});
`

3. Start Development

Run npm run dev. PocketMock automatically detects the plugin environment and switches to Server Mode.

---

Advanced Features

$3

PocketMock supports powerful URL patterns to mock complex APIs:

- Path Parameters: /api/users/:id → matches /api/users/123, /api/users/john
- Wildcards: /api/* → matches /api/users, /api/users/123/posts
- Mixed Patterns: /api/:version/users/*/profile → matches /api/v1/users/123/profile

Access captured parameters in mock functions:
`javascript
(req) => {
const { id, version } = req.params;
const { include } = req.query;
return { id: parseInt(id), version, includeAuthor: include === 'true' };
}
`

$3

PocketMock includes a powerful Smart Mock Generator that allows you to create realistic test data with simple template syntax.

#### Quick Example

`javascript
{
"user": { // → Generate user data
"id": "@guid", // → "550e8400-e29b-41d4-a716-446655440000"
"name": "@name", // → "John"
"username": "@username", // → "brightpanda"
"email": "@email", // → "john.smith@example.com"
"avatar": "@image(100x100)", // → "https://via.placeholder.com/100x100"
"age": "@integer(18,60)", // → 25
"role": "@pick(admin,user)", // → "admin"
"ip": "@ip", // → "192.168.1.1"
"ipv6": "@ip(v6)" // → "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}
}
`

#### Common Generators

| Syntax | Function | Example |
|--------|----------|---------|
| @guid | Unique ID | "f47ac..." |
| @name | Random Name | "John" |
| @username | Random Username | "cool_coder" |
| @email | Email Address | "user@example.com" |
| @ip | Random IP (v4/v6) | @ip → 192.168.1.1 |
| @integer(min,max) | Random Integer | @integer(1,100) → 42 |
| @pick(A,B,C) | Random Choice | @pick(apple,banana) → "apple" |
| @image(100x100) | Placeholder Image | "https://via.placeholder.com/100x100" |

#### More Features

📖 View Complete Generator List

| Category | Syntax | Description |
|----------|--------|-------------|
| Basic Types |
| @float(min,max,decimals) | Random Float | @float(0,1,2) → 0.57 |
| @boolean | Random Boolean | true |
| @string(length) | Random String | @string(8) → "aX9bK2pQ" |
| Personal |
| @username(separator, randomDigits, maxLength, dictType) | Username | @username("-", 2, 20) |
| @phone(countryCode) | Phone Number | @phone(+1) |
| Network |
| @ip(version) | IP Address | @ip(v6/v4/6/4) → IPv(x), @ip → IPv4 |
| Date/Time |
| @date(start,end) | Random Date | @date(2023-01-01,2024-12-31) |
| Other |
| @color | Random Color | "#a3f4c2" |
| @text(wordCount) | Random Text | Generate text with specified word count |
| @address(countries) | Address Object | @address(US,UK) |
| @company(industries) | Company Object | @company(Tech,Finance) |
| @url(tlds) | Random URL | @url(com,io) |

Array Syntax:
`javascript
{
"users|5": { // Generate 5 users
"id": "@guid",
"name": "@name"
},
"scores|3-5": "@integer(60,100)" // Generate 3 to 5 scores
}
`


$3

You are not limited to static JSON. You can write JavaScript functions to generate responses dynamically based on request!

`javascript
(req) => {
// Dynamic response based on Query parameters
if (req.query.id === '1') {
return { id: 1, name: 'Admin', role: 'admin' };
}

// Dynamic response based on Body content
if (req.body?.type === 'error') {
return {
status: 400,
body: { message: 'Invalid Parameter' }
};
}

// Default response
return { id: 2, name: 'Guest' };
}
`

$3

Seamlessly integrate with your existing API workflow.

- Import: Import mock rules directly from Postman Collection (v2.1) and OpenAPI 3.0 (Swagger) files.
- Smart conversion automatically maps fields like user_id to @guid.
- Export: Export any mock rule to Postman JSON format directly from the rule editor, making it easy to share or test in other tools.

$3

The built-in Network panel logs all network requests (both mocked and real) in real-time, providing powerful debugging capabilities:

- View Details: Click logs to view full Request/Response Body.
- Context Menu: Right-click on any log to:
- Copy URL/Response: Quickly copy data to clipboard.
- Copy as cURL: Generate a cURL command to reproduce the request in terminal.
- Add to Mock Rules: Instantly convert a real request into a mock rule.
- Filter: Filter logs by URL, Method, or Mock status.

---

Technical Architecture

- Monkey Patching: Intercepts requests by overriding window.fetch and extending XMLHttpRequest prototype chain.
- Shadow DOM: Encapsulates debugging UI in Shadow Root for complete style sandboxing.
- Vite Library Mode: Uses Vite's library mode with css: 'injected'` strategy to inline all CSS into JS for single-file import experience.

---

Roadmap

Check out our Roadmap to see what's next for PocketMocker and how you can contribute to its future!

---

Contributing & Contact

We welcome all contributions to PocketMocker! Whether it's reporting bugs, suggesting new features, improving documentation, or submitting code, your help is greatly appreciated.

Please read our Contribution Guidelines for details on how to get started.

$3

If you have any questions, suggestions, or would like to connect, feel free to reach out:

- Twitter (X): https://x.com/tiancha79267301
- WeChat

---

License

MIT © tianchangNorth

---