IDE Extension Guide

This guide walks you through installing, configuring, and using the MockForge VS Code extension to enhance your development workflow with inline mock previews, config validation, and seamless playground integration.

Overview

The MockForge VS Code extension brings the power of MockForge directly into your editor, providing:

Peek Mock Response: Hover over API endpoints to see mock responses inline
Config Validation: Real-time validation of mockforge.yaml files with inline errors
Mocks Explorer: Visual tree view of all mocks with real-time updates
Playground Integration: Quick access to MockForge Playground from hover tooltips
Mock Management: Create, edit, enable/disable, and delete mocks from VS Code

Installation

From VS Code Marketplace

Open VS Code
Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Search for “MockForge”
Click Install

Or install via command line:

code --install-extension saasy-solutions.mockforge-vscode

From VSIX File

If you have a .vsix file:

code --install-extension mockforge-vscode-0.1.0.vsix

Verify Installation

After installation, you should see:

MockForge icon in the Activity Bar (left sidebar)
MockForge commands available in Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

Configuration

Basic Setup

Configure the extension in VS Code settings:

Open Settings (Ctrl+, / Cmd+,)
Search for “mockforge”
Configure the following:

{
  "mockforge.serverUrl": "http://localhost:3000",
  "mockforge.autoConnect": true,
  "mockforge.showNotifications": true,
  "mockforge.inlinePreview.enabled": true
}

Settings:

mockforge.serverUrl: MockForge server URL (default: http://localhost:3000)
mockforge.autoConnect: Automatically connect on startup (default: true)
mockforge.showNotifications: Show notifications for mock changes (default: true)
mockforge.inlinePreview.enabled: Enable inline preview of mock responses (default: true)

Workspace Settings

For project-specific configuration, add to .vscode/settings.json:

{
  "mockforge.serverUrl": "http://localhost:3000",
  "mockforge.autoConnect": true
}

Feature 1: Peek Mock Response

The peek response feature shows mock responses when you hover over API endpoint references in your code.

How It Works

Hover over an endpoint in your code (JavaScript, TypeScript, or YAML)
See the mock response in a tooltip with headers and body
Click “Open in Playground” to test the endpoint interactively

Supported Patterns

The extension detects endpoints in various patterns:

JavaScript/TypeScript:

// fetch() calls
const response = await fetch('/api/users');

// axios calls
const data = await axios.get('/api/products');

// http client calls
const result = await http.get('/api/orders');

YAML Config Files:

# mockforge.yaml
responses:
  - path: /api/users
    method: GET

Example Usage

Before (without extension):

You write: fetch('/api/users')
You have no idea what the response looks like
You need to run the app or check documentation

After (with extension):

You write: fetch('/api/users')
You hover over the endpoint

You see:

{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]"
    }
  ]
}

You click “Open in Playground” to test it

Configuration

Enable/disable peek response:

{
  "mockforge.inlinePreview.enabled": true
}

Troubleshooting

Preview not showing:

Ensure MockForge server is running
Check that mockforge.inlinePreview.enabled is true
Verify the endpoint path matches a configured mock
Check VS Code output panel for errors

Preview shows “No mock configured”:

The endpoint doesn’t have a mock configured
Click “Open in Playground” to create one
Or add a mock in mockforge.yaml

Feature 2: Config Validation

Get real-time validation for your mockforge.yaml files with inline error reporting.

How It Works

Open mockforge.yaml in VS Code
See inline errors for invalid configuration
Get helpful messages for missing fields, type mismatches, and invalid values
Auto-detect schema type based on file name and location

Supported Config Types

The extension validates:

Main config: mockforge.yaml, mockforge.yml, mockforge.json
Blueprint config: blueprint.yaml
Reality config: Files in reality/ directory or reality*.yaml
Persona config: Files in personas/ directory

Example Validation

Invalid Configuration:

# mockforge.yaml
reality:
  level: invalid_level  # ❌ Error shown here

Error Message:

Invalid reality level: invalid_level. Valid values: static, light, moderate, high, chaos

Valid Configuration:

# mockforge.yaml
reality:
  level: moderate  # ✅ No errors

Schema Generation

The extension can auto-generate schemas:

Run schema generation:
```
mockforge schema generate
```
Schemas are saved to schemas/ directory
Extension auto-detects schemas in:
- schemas/ directory
- .mockforge/ directory
- Project root

Validation Features

Real-time validation: Errors appear as you type
Accurate positions: Line and column numbers for errors
Helpful messages: Clear descriptions of what’s wrong
Auto-detection: Automatically detects schema type
Multiple schemas: Supports all MockForge config types

Troubleshooting

Validation not working:

Ensure you have a mockforge.yaml file open
Check that schemas are available:
- Look for schemas/ directory
- Or run mockforge schema generate
Check VS Code output panel for validation errors

Schema not found:

Run mockforge schema generate to create schemas
Or manually place schemas in schemas/ directory

Feature 3: Mocks Explorer

Visual tree view of all your mocks with real-time WebSocket updates.

Accessing Mocks Explorer

Click MockForge icon in Activity Bar (left sidebar)
Open “Mocks Explorer” view
Browse all mocks in a tree view

Features

Color-coded by HTTP method: GET (blue), POST (green), PUT (orange), DELETE (red)
Real-time updates: Changes sync automatically via WebSocket
Context menu actions:
- Edit Mock
- Delete Mock
- Toggle Mock (enable/disable)
- View Details

Using Mocks Explorer

View Mocks:

Open Mocks Explorer
Click on a mock to see details
Expand folders to see grouped mocks

Edit Mock:

Right-click on a mock
Select “Edit Mock”
Modify JSON configuration
Save to update

Toggle Mock:

Right-click on a mock
Select “Toggle Mock”
Mock is enabled/disabled

Delete Mock:

Right-click on a mock
Select “Delete Mock”
Confirm deletion

Feature 4: Playground Integration

Quick access to MockForge Playground from hover tooltips and commands.

Hover over an endpoint in your code
See the tooltip with mock response
Click “Open in Playground” link
Playground opens in browser with endpoint pre-filled

From Command Palette

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Type “MockForge: Open Playground”
Enter endpoint details (method and path)
Playground opens in browser

Playground URL Format

The extension constructs URLs like:

http://localhost:3000/admin/#/playground?method=GET&path=/api/users

For standalone admin UI:

http://localhost:9080/#/playground?method=GET&path=/api/users

Feature 5: Server Control

Monitor your MockForge server status and statistics.

Accessing Server Control

Click MockForge icon in Activity Bar
Open “Server Control” view
View server statistics

Information Displayed

Connection status: Connected / Disconnected
Server version: MockForge version
Server port: Port number
Uptime: How long server has been running
Request count: Total requests processed
Active mocks: Number of active mocks

Quick Actions

Start Server: Start MockForge server
Stop Server: Stop MockForge server
Restart Server: Restart MockForge server

Complete Workflow Example

Let’s walk through a complete workflow using all features:

1. Install Extension

code --install-extension saasy-solutions.mockforge-vscode

2. Start MockForge Server

mockforge serve

3. Configure Extension

Add to .vscode/settings.json:

{
  "mockforge.serverUrl": "http://localhost:3000",
  "mockforge.autoConnect": true,
  "mockforge.inlinePreview.enabled": true
}

4. Create Mock Config

Create mockforge.yaml:

http:
  port: 3000

responses:
  - path: /api/users
    method: GET
    body:
      users:
        - id: 1
          name: "John Doe"
          email: "[email protected]"
        - id: 2
          name: "Jane Smith"
          email: "[email protected]"

5. Use Peek Response

In your code:

// Hover over this endpoint to see the mock response
const response = await fetch('/api/users');

Hover tooltip shows:

{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "[email protected]"
    }
  ]
}

6. Open in Playground

Click “Open in Playground” in the hover tooltip to test the endpoint interactively.

7. Validate Config

Edit mockforge.yaml and see real-time validation:

reality:
  level: moderate  # ✅ Valid

reality:
  level: invalid  # ❌ Error: Invalid reality level

8. Manage Mocks

Open Mocks Explorer
View all mocks
Edit, delete, or toggle mocks
See real-time updates

Advanced Usage

Custom Server URL

For different environments:

{
  "mockforge.serverUrl": "http://localhost:3001"
}

Disable Auto-Connect

If you want to connect manually:

{
  "mockforge.autoConnect": false
}

Disable Notifications

To reduce notification noise:

{
  "mockforge.showNotifications": false
}

Disable Peek Response

If you don’t want inline previews:

{
  "mockforge.inlinePreview.enabled": false
}

Troubleshooting

Extension Not Connecting

Symptoms:

Mocks Explorer shows “Disconnected”
Peek response doesn’t work
Server Control shows disconnected

Solutions:

Check that MockForge server is running
Verify mockforge.serverUrl setting is correct
Check VS Code output panel for connection errors
Try restarting the extension: Command Palette → “MockForge: Restart Extension”

Validation Not Working

Symptoms:

No inline errors in mockforge.yaml
Validation errors not showing

Solutions:

Ensure you have a mockforge.yaml file open
Check that schemas are available:
- Look for schemas/ directory
- Or run mockforge schema generate
Check VS Code output panel for validation errors
Try reloading the window: Command Palette → “Developer: Reload Window”

Peek Response Not Showing

Symptoms:

Hovering over endpoints doesn’t show tooltip
Tooltip shows “No mock configured”

Solutions:

Ensure mockforge.inlinePreview.enabled is true
Check that MockForge server is connected
Verify the endpoint path matches a configured mock
Try hovering over different endpoint patterns
Check VS Code output panel for errors

Schema Not Found

Symptoms:

Validation says “Schema not available”
Auto-detection fails

Solutions:

Run mockforge schema generate to create schemas
Ensure schemas are in schemas/ directory
Check that schema file names match expected patterns
Verify schema JSON is valid

Keyboard Shortcuts

The extension doesn’t define custom keyboard shortcuts by default, but you can add them:

{
  "key": "ctrl+shift+m",
  "command": "mockforge.refreshMocks"
}

Commands

All extension commands are available via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

MockForge: Refresh Mocks - Refresh mocks list
MockForge: Create Mock - Create a new mock
MockForge: Open Playground - Open playground in browser
MockForge: Show Logs - Show extension logs
MockForge: Restart Extension - Restart the extension

Best Practices

1. Keep Server Running

For best experience, keep MockForge server running while developing.

2. Generate Schemas

Run mockforge schema generate to enable config validation.

3. Use Workspace Settings

Configure extension per-project in .vscode/settings.json.

4. Enable Auto-Connect

Set mockforge.autoConnect: true for seamless workflow.

5. Check Output Panel

If something doesn’t work, check VS Code output panel for errors.

IDE Integration Guide - Detailed feature reference
VS Code Extension README - Extension documentation
Configuration Files - Config file format
Getting Started - MockForge basics

Next Steps

Install the extension and configure it
Start MockForge server and connect
Try peek response by hovering over endpoints
Validate your config by editing mockforge.yaml
Explore Mocks Explorer to manage your mocks
Use Playground to test endpoints interactively

MockForge Documentation