Intercept Wave for IntelliJ IDEA

English | 简体中文

Plugin Introduction

Intercept Wave is a powerful IntelliJ IDEA plugin that integrates proxy and interception capabilities similar to Nginx and Charles, designed specifically for local development environments. It can intelligently intercept HTTP requests and WebSocket (ws:///wss://) messages, either returning custom mock data or acting as a proxy server/bridge to forward real traffic to the original server.

✨ Multi-Service Proxy

• 📑 Tab-based Interface: Manage multiple proxy configuration groups in separate tabs
• 🚀 Multiple Proxy Groups: Run multiple mock services simultaneously, each on its own port
• 🏗️ Microservices Ready: Perfect for microservices architecture (e.g., user service on port 8888, order service on port 8889)
• 🔄 Quick Switching: Easily switch and manage different service configurations via tabs
• 🌍 Multi-Environment: Effortlessly manage dev, test, staging, and other environments

Core Capabilities

Smart Interception & Proxy:

• 🎯 Configure intercept prefix (e.g., /api) to precisely target specific request paths
• 🔄 With Mock Config: Returns preset mock data for offline development
• 🌐 Without Mock Config: Acts as a proxy server, forwarding requests with complete HTTP headers to get real data
• 🔀 Smart path matching with prefix stripping support
• 📡 WebSocket Mock & Bridge: Create WS groups that listen on local ws:// ports (optionally wss:// with a PKCS#12 keystore), bridge to upstream ws:///wss:// servers, and support both automatic and manual message pushing.

Developer-Friendly Features:

• 👥 Target Users: Frontend Engineers, QA Engineers, Full-Stack Developers
• 🎨 Visual configuration UI, no manual config file editing needed
• 💾 Persistent configuration with project-level isolation
• 🌐 Automatic CORS handling
• ⏱️ Network delay simulation support
• 🔧 Custom response status codes and headers
• 🍪 Global cookie support for authenticated APIs

Typical Use Cases

1. Microservices Development: Mock multiple microservices simultaneously (user service, order service, payment service, etc.)
2. Independent Frontend Development: Continue development with mock data when backend APIs are not ready
3. API Testing: Quickly switch between different response data to test edge cases
4. Multi-Environment Debugging: Configure and manage dev, test, staging environments at once
5. Local Debugging: Use mock for some APIs while proxying others to test servers
6. Network Simulation: Simulate slow networks or API timeout scenarios
7. Cross-Origin Development: Automatically add CORS headers to solve frontend development CORS issues

Features Overview

Intercept Wave provides the following core functionalities:

• API Interception: Intercept specific APIs and return configured mock data
• Proxy Forwarding: Automatically forward unconfigured APIs to the original server
• WebSocket Mock & Push: Start local WS mock/proxy services, forward to upstream ws:///wss:// endpoints, and define push rules (periodic/timeline) or send messages manually from the tool window.
• CORS Support: Automatically add CORS headers to resolve cross-origin issues
• Request Preservation: Preserve original request headers and User-Agent
• Delay Simulation: Simulate network delays for testing slow network environments
• Status Code Testing: Configure different status codes to test error handling logic
• Prefix Filtering: Support prefix filtering to simplify API access paths
• Global Cookie: Configure global cookies for APIs requiring authentication

What's New in v3.0

• Config version now aligns with the plugin major.minor (e.g., 3.0). Existing v2.x configs load seamlessly and are saved with "version": "3.0" automatically — no manual migration needed.
• Mock JSON normalization and minification: mockData accepts single quotes, comments, unquoted keys, and trailing commas, and is saved as compact JSON. Use "Format JSON" to pretty print when editing.

Installation

Using IDE Built-in Plugin System

Settings/Preferences > Plugins > Marketplace > Search for "Intercept Wave" > Install

Using JetBrains Marketplace

Visit JetBrains Marketplace and click the Install to ... button.

Or download the latest release and install it manually: Settings/Preferences > Plugins > ⚙️ > Install plugin from disk...

Manual Installation

Download the latest release from GitHub Releases and install manually: Settings/Preferences > Plugins > ⚙️ > Install plugin from disk...

Quick Start

1. Open Tool Window

1. Open your project in IntelliJ IDEA
2. Click the "Intercept Wave" icon in the left toolbar
3. The tool window displays all configured proxy groups as tabs

2. Manage Configuration Groups

The tool window provides global operations at the top:

• Start All: Start all enabled configuration groups
• Stop All: Stop all running services
• Configuration: Open the configuration dialog to manage all configuration groups

Tab Explanation

• Each tab represents a configuration group (e.g., "User Service", "Order Service")
• Displays service name, port number, and enabled status
• Click a tab to switch to the corresponding service control panel
• Plus Tab: Click to quickly open the configuration dialog and add a new configuration group

Individual Service Control

Each tab panel displays:

• ☑/☐ Enabled Status: Shows whether this configuration group is enabled
• 🟢/⚫ Running Status: Running / Stopped
• 🔗 Access URL: Service access URL when running
• Start Service / Stop Service: Control individual service start/stop
• Current Configuration: Displays port, protocol, upstream address, and details such as HTTP mock APIs or WS push rules.

3. Configure Proxy Groups

Click the "Configuration" button to open the configuration dialog:

Configuration Group Management (Multi-Tab Interface)

• Each tab represents a configuration group
• Tab display format: Configuration Group Name (:Port)
• Add Configuration Group: Add a new configuration group
• Delete Current Configuration Group: Delete the currently selected configuration group (at least one must remain)
• Move Left / Move Right: Adjust the display order of configuration groups

Configuration Group Settings

Each configuration group contains the following settings:

Basic Configuration:

• Protocol: HTTP or WS. HTTP groups handle HTTP APIs; WS groups handle WebSocket connections.
• Configuration Group Name: Custom name (e.g., "User Service", "Order Service")
• Port Number: The port this service listens on (e.g., 8888, 8889)
• Strip Prefix: When enabled, matching removes the configured prefix when computing match paths (applies to both HTTP and WS groups).
• Enable This Configuration Group: When checked, this configuration group will be included in "Start All"

Mock API Configuration

1. Click the "Add API" button

2. Fill in the following information:

   • API Path: e.g., /api/user/info or /user/info (depends on whether prefix stripping is enabled)
   • HTTP Method: ALL, GET, POST, PUT, DELETE, PATCH
   • Status Code: HTTP response status code (default: 200)
   • Delay (ms): Simulate network delay (default: 0)
   • Mock Data: Response data in JSON format
   • Enabled: Whether to enable this mock configuration
   • Use Global Cookie: When enabled, the response includes the configured global cookie

3. Click the "Format JSON" button to format mock data

4. Click "OK" to save configuration

HTTP Settings (Protocol = HTTP)

HTTP configuration groups provide additional HTTP-specific settings:

• Intercept Prefix: API path prefix to intercept (default: /api)
• Base URL: Base URL of the original server (e.g., http://localhost:8080)
• Global Cookie: Configure global cookie value (e.g., sessionId=abc123; userId=456)

WebSocket Group Settings (Protocol = WS)

WS configuration groups share the same basic settings (name, port, strip prefix, enabled), and add WS-specific options:

• Upstream WebSocket URL: Upstream ws:// or wss:// address (for example, ws://localhost:8080/ws/chat). Required for WS groups.
• WS Prefix (optional): Path prefix for WebSocket matching. When Strip Prefix is enabled and WS prefix is non-empty, that prefix is removed before matching push rules. When empty, WS paths are matched as-is (no inheritance from the HTTP intercept prefix).
• Manual Push Panel: Toggle whether the tool window shows a WS manual push panel for this group.
• WS Push Rules: A table of rules used for automatic and manual pushes:
  • Match by path pattern (supports */** like HTTP mocks) and optional JSON event key/value.
  • Choose direction: in (upstream → client), out (client → upstream), or both.
  • Set mode: off, periodic (send every N seconds, optional onOpenFire on connect), or timeline (send a sequence at specific milliseconds, optional loop).
  • Provide message content, which is used for auto-push and as the default template when manually sending.
  • Optionally intercept matching messages instead of forwarding them.

Path Matching Rules (Wildcards)

Support wildcards in path for flexible matching (behavior of stripPrefix and interceptPrefix remains unchanged):

• Single-segment *: matches exactly one path segment (no slash)
  • Example: /a/b/* matches /a/b/123, not /a/b/123/456
• Multi-segment **: matches multiple segments (can include slashes)
  • Example: /a/b/** matches /a/b/123 and /a/b/123/456
• Middle-segment wildcard: support * at middle positions
  • Example: /order/*/submit matches /order/123/submit

Priority (high → low):

• Exact path > wildcard with fewer * > method-specific (non-ALL) > longer pattern

Notes:

• Matching only applies to the path (query string is ignored)
• /a/b/** does not match /a/b itself. Add an extra exact rule /a/b if needed

4. Start Services

There are two ways to start services:

Method 1: Start All Services

• Click the "Start All" button at the top of the tool window
• Automatically starts all enabled configuration groups

Method 2: Start Individual Service

• Switch to the corresponding tab
• Click the "Start Service" button in that tab
• Only starts the currently selected service

After successful service startup:

• Status displays as "● Running"
• Access URL is displayed (e.g., http://localhost:8888)
• Run tool window displays real-time logs

Use Cases

Case 1: Microservices Development

Mock multiple microservices simultaneously, each service running on an independent port:

Configuration Group 1 - User Service (Port 8888):

// Frontend code accessing user service
fetch('http://localhost:8888/api/user/info')
  .then(res => res.json())
  .then(data => console.log(data));

Configuration Group 2 - Order Service (Port 8889):

// Frontend code accessing order service
fetch('http://localhost:8889/order-api/orders')
  .then(res => res.json())
  .then(data => console.log(data));

Configuration Group 3 - Payment Service (Port 8890):

// Frontend code accessing payment service
fetch('http://localhost:8890/pay-api/checkout')
  .then(res => res.json())
  .then(data => console.log(data));

All services can run simultaneously without interference. Click the "Start All" button to start all services at once!

Case 2: Mock Specific API

// Frontend code
fetch('http://localhost:8888/api/user/info')
  .then(res => res.json())
  .then(data => console.log(data));

Configuration:

• Path: /api/user/info
• Method: GET
• Mock Data:

{
  "code": 0,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]"
  },
  "message": "success"
}

Case 3: Forward Unconfigured APIs

// This API has no mock configuration, will be automatically forwarded to the original server
fetch('http://localhost:8888/api/posts')
  .then(res => res.json())
  .then(data => console.log(data));

If the original API address is configured as http://api.example.com, the actual request will be: http://api.example.com/api/posts

Case 4: Simulate Authenticated APIs

1. Set cookie in global configuration: sessionId=abc123; userId=456
2. Check "Use Global Cookie" in mock API configuration
3. Mock API response will automatically include Set-Cookie response header

Case 5: Simulate Network Delay

Set delay time in mock configuration (e.g., 1000ms) to simulate slow network environment.

Case 6: Test Different Response Status Codes

Configure different status codes (404, 500, etc.) to test frontend error handling logic.

Configuration File

All configurations are saved in the .intercept-wave folder in the project root directory:

.intercept-wave/
└── config.json           # Global configuration and multiple configuration groups

config.json Example

{
  "version": "3.0",
  "proxyGroups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "User Service",
      "port": 8888,
      "interceptPrefix": "/api",
      "baseUrl": "http://localhost:8080",
      "stripPrefix": true,
      "globalCookie": "sessionId=abc123",
      "enabled": true,
      "mockApis": [
        {
          "path": "/user/info",
          "enabled": true,
          "mockData": "{\"code\":0,\"data\":{\"name\":\"John Doe\"}}",
          "method": "GET",
          "statusCode": 200,
          "useCookie": true,
          "delay": 0
        }
      ]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Order Service",
      "port": 8889,
      "interceptPrefix": "/order-api",
      "baseUrl": "http://localhost:8081",
      "stripPrefix": true,
      "globalCookie": "",
      "enabled": true,
      "mockApis": [
        {
          "path": "/orders",
          "enabled": true,
          "mockData": "{\"code\":0,\"data\":[]}",
          "method": "GET",
          "statusCode": 200,
          "useCookie": false,
          "delay": 0
        }
      ]
    }
  ]
}

Advanced Features

Global Cookie Configuration

Set cookie value in global configuration, multiple cookies separated by semicolons:

sessionId=abc123; userId=456; token=xyz789

Then check "Use Global Cookie" for mock APIs that need cookies, and the response will automatically include Set-Cookie header.

CORS Support

Mock server automatically adds the following CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Proxy Mode

Unconfigured mock APIs will be automatically forwarded to the original server, preserving:

• Original request headers
• User-Agent
• Request body (for POST/PUT, etc.)
• Cookies (if any)

Welcome Page

Accessing the mock server root path (http://localhost:8888/) returns server status and configuration information:

{
  "status": "running",
  "message": "Intercept Wave Mock Server is running",
  "server": {
    "port": 8888,
    "baseUrl": "http://localhost:8080",
    "interceptPrefix": "/api"
  },
  "mockApis": {
    "total": 3,
    "enabled": 2
  },
  "apis": [
    {"path": "/api/user/info", "method": "GET", "enabled": true},
    {"path": "/api/posts", "method": "ALL", "enabled": true}
  ]
}

Important Notes

1. Port Occupation: Ensure the configured port is not occupied by other programs
2. Configuration Changes: If the server is running when configuration is modified, it will automatically stop
3. Project Closure: Mock server will automatically stop when the project is closed
4. Security: This tool is only for local development environment, do not use in production

FAQ

Q: What to do if the server fails to start?

A: Check if the port is occupied, you can change the port number in the configuration.

Q: Why is my API not being mocked?

A: Make sure the API path matches exactly and the mock configuration is enabled.

Q: How to view request logs?

A: When you start the mock server, the "Intercept Wave Mock Server" tab will automatically appear in the Run tool window at the bottom of IDEA, displaying real-time color-coded logs for all requests, including timestamps, request methods, paths, and whether the response was mocked or proxied.

Q: Does it support HTTPS?

A: The current version only supports HTTP, HTTPS support is planned.

Q: How does global cookie work?

A: Set cookie value in global configuration, then check "Use Global Cookie" in mock API configuration. The response will include the cookie via Set-Cookie response header.

Testing & Coverage

Run Unit Tests

• Run all tests: ./gradlew test
• UI tests (Robot): ./gradlew testUi (requires a running IDE instance configured by the plugin)

Notes:

• Platform tests run in a single forked JVM and are headless-configured.
• UI tests are split into a separate task and use the robot-server plugin.

Integration Tests (Docker upstream)

These tests require the upstream service container running (default http://localhost:9000):

• Start container:
  • cd docker
  • docker compose -f docker-compose.upstream.yml up -d upstream

Running by category (marked with @Category(IntegrationTest)):

• Run only integration tests:
  • ./gradlew test -DincludeTags=org.zhongmiao.interceptwave.tags.IntegrationTest -Diw.upstream.http=http://localhost:9000
• Exclude integration tests (unit tests only):
  • ./gradlew test -DexcludeTags=org.zhongmiao.interceptwave.tags.IntegrationTest
• Default behavior:
  • Without include/exclude, all tests run; if the container is not running, integration tests auto-skip after availability probe.

Override upstream base URL:

• System property: -Diw.upstream.http=http://localhost:9000
• Environment variable: IW_UPSTREAM_HTTP=http://localhost:9000

Coverage Reports (Kover)

• XML: ./gradlew koverXmlReport → build/reports/kover/report.xml
• HTML: ./gradlew koverHtmlReport → build/reports/kover/html/index.html

Excluded from coverage:

• UI packages: org.zhongmiao.interceptwave.ui, org.zhongmiao.interceptwave.toolWindow
• Adapter packages: org.zhongmiao.interceptwave.listeners, org.zhongmiao.interceptwave.startup, org.zhongmiao.interceptwave.events
• UI-facing service: org.zhongmiao.interceptwave.services.ConsoleService

Project Structure (Gradle)

project/
├── build.gradle.kts        # Core build: plugins, dependencies, IntelliJ config
├── gradle/
│   ├── changelog.gradle.kts # Changelog plugin config
│   ├── kover.gradle.kts     # Coverage config and exclusions
│   ├── test.gradle.kts      # Unit test task configuration
│   └── ui-test.gradle.kts   # UI test and robot server configuration
├── gradle.properties        # Version, platform, plugin coordinates
└── settings.gradle.kts      # Gradle settings

Rationale:

• Keep build.gradle.kts concise and focused on core plugin setup.
• Isolate test/UI/coverage/changelog logic to reduce merge conflicts and improve readability.

Repository Layout

For a brief Gradle layout, see the previous section. For the full repository layout (with module/package responsibilities), see:

• CONTRIBUTING.md: Project Structure
• CONTRIBUTING_zh.md: 项目结构

Development Roadmap

• HTTPS/WSS support
• WebSocket mock support
• Request log viewer (available in Run tool window)
• Import/export configuration
• Mock data template library
• Custom request headers support

Feedback & Contribution

If you have any questions or suggestions, feel free to submit an Issue or Pull Request!

License

This project is based on the IntelliJ Platform Plugin Template.