@andydavid-dev/mock-lobster NPM

🦞 Mock Lobster

Mock Lobster is a developer-friendly local testing tool designed for Salesforce integrations, providing a lightweight, zero-configuration environment for testing your Salesforce outbound REST calls and Pub/Sub API integrations without the complexity of setting up remote endpoints.

Why Mock Lobster?

Traditional integration testing often requires setting up and maintaining remote test environments, managing test data, and dealing with network-related issues. Mock Lobster simplifies this process by providing:

A local testing environment that mimics your production endpoints
Real-time inspection of incoming requests for quick debugging
Support for multiple authentication methods to match your production setup
Seamless integration with Salesforce Named Credentials
Zero configuration needed to get started

Features

Dynamic Endpoint Creation: Create test endpoints on demand with unique URLs
Authentication Support:
- OAuth 2.0 (Client Credentials Flow) with automatic token management
- No Authentication for simple testing scenarios
Request Inspection: View detailed information about incoming requests, including headers, body content, and authentication details
Salesforce Integration: Built-in support for Named Credentials configuration
Modern Web Interface: Clean, responsive design with real-time updates
Request History: Maintains a history of recent requests for debugging
Local Development: Runs completely locally, perfect for development and testing
Pub/Sub Testing: Built-in support for testing Salesforce Pub/Sub API integrations
- Real-time event monitoring
- Topic subscription management
- Event replay and history

Prerequisites

Before starting, ensure you have:

Node.js version 14 or higher installed
npm (comes with Node.js)
ngrok (required for Salesforce integration)
- macOS (using Homebrew): brew install ngrok
- Other platforms: Download from https://ngrok.com/download

Quick Start Guide

There are two ways to get started with Mock Lobster: 1. Clone the repository (recommended for development and contributing) 2. Install as an npm package (recommended for using Mock Lobster in your projects)

Option 1: Using Mock Lobster from Source

1. Clone and Install

# Clone the repository
git clone https://github.com/yourusername/mock-lobster.git
cd mock-lobster

# Install dependencies
npm install

2. Start the Development Server

Mock Lobster will try to use port 3003 by default. If that port is unavailable, it will automatically search for the next available port in sequence (3004, 3005, etc.). The selected port will be displayed in the console when the server starts.

# If you want to free port 3003 specifically (Unix/Linux/macOS)
kill $(lsof -t -i:3003)

# Start the development server
npm run dev

You can also specify a custom port:

# Use a specific port
PORT=3456 npm run dev

Option 2: Using Mock Lobster as a CLI Tool

1. Install the Package

# Install globally to use the CLI command
npm install -g @andydavid-dev/mock-lobster

2. Start Mock Lobster

Start Mock Lobster directly from your terminal:

# Start Mock Lobster with default settings (port 3003)
mock-lobster

# Start on a specific port
mock-lobster --port 3456

# Start with a custom static files path
mock-lobster --static-path ./my-static-files

Setting Up ngrok (Required for Both Options)

Mock Lobster runs locally on your machine, but Salesforce requires HTTPS endpoints for all outbound callouts. This is where ngrok comes in - it creates a secure tunnel to your local Mock Lobster instance, making it accessible to Salesforce with a public HTTPS URL.

Why ngrok?

Salesforce enforces HTTPS for security reasons and won't make callouts to http://localhost
ngrok provides a secure HTTPS endpoint that forwards traffic to your local instance
Enables real-time inspection of all HTTP traffic
No need to deploy Mock Lobster to a public server
Perfect for local development and testing

Important Notes About ngrok

Free tier URLs change every time you restart ngrok (e.g., https://xxxx-xxxx.ngrok-free.app)
If your ngrok URL changes, you'll need to update your Salesforce configurations
Consider a paid ngrok account for persistent URLs in team environments
The free tier has usage limits but is sufficient for most development needs

Set Up Steps

Install ngrok:

# macOS (using Homebrew)
brew install ngrok

# Other platforms
Download from https://ngrok.com/download

Get your authtoken:
- Sign up at https://ngrok.com (free)
- Find your authtoken in your ngrok dashboard
- You only need to do this once

Configure ngrok:

# One-time setup
ngrok config add-authtoken YOUR_AUTH_TOKEN

Start the tunnel:
```
ngrok http 3003
```
Save your ngrok URL:
- Look for the 'Forwarding' line in the ngrok output
- Save the HTTPS URL (e.g., https://xxxx-xxxx.ngrok-free.app)
- You'll need this URL for Salesforce configuration

Monitoring Traffic

The ngrok inspector automatically launches at http://localhost:4040 and provides:

Real-time traffic monitoring
Request/response inspection
Replay capabilities
Detailed timing information
Network error detection

Keep both the Mock Lobster interface and ngrok inspector open while debugging for complete visibility into your integration.

4. Configure Salesforce

Add Remote Site Setting:
- Navigate to Setup > Security > Remote Site Settings
- Click "New Remote Site"
- Name: MockLobster_Ngrok
- URL: Your ngrok URL
- Check "Active"
- Save
Access Mock Lobster at http://localhost:3003 and create your first endpoint

Monitoring and Debugging

Mock Lobster provides comprehensive tools for monitoring and debugging your integrations:

Real-Time Request Monitoring

The main interface shows all incoming requests in real-time:

Request timestamp and method
Endpoint URL
Authentication status
Response status code
Request and response details

Request Inspection

Click on any request to view detailed information:

Complete request headers
Query parameters
Request body (formatted JSON)
Response headers and body
Timing information

Using the ngrok Inspector

The ngrok inspector (http://localhost:4040) provides additional insights:

Network-level request/response details
Detailed timing information
Request replay capabilities
TLS/SSL verification status

Debugging Tips

Keep both interfaces open while testing:
- Mock Lobster UI for application-level monitoring
- ngrok Inspector for network-level details
Use the filter options to focus on specific endpoints or request types
Check the terminal output when running in development mode (npm run dev) for server-side logs
Common issues to check:
- Correct ngrok URL in Salesforce configuration
- Valid authentication credentials
- Proper request headers and body format
- Network connectivity and TLS/SSL status

Creating and Managing Endpoints

Using the Mock Lobster Interface

Mock Lobster provides a modern, intuitive web interface for creating and managing your test endpoints. Here's how to use it:

Creating Your First Endpoint

Access Mock Lobster at http://localhost:3003
Click the "+" button to create a new endpoint
Configure your endpoint:
- Choose "No Auth" for simple testing
- Choose "OAuth" to set up OAuth 2.0 client credentials flow
Click "Create"

Your new endpoint will appear in the list with its unique URL and configuration details.

Managing Endpoints

The interface provides several features:

Endpoint List: View all your created endpoints with their URLs and auth details
Request History: See all incoming requests in real-time
Request Details: Click on any request to view:
- Headers
- Query parameters
- Request body
- Response details
Filter Options: Filter endpoints by type (All, OAuth, No Auth)
View Options: Toggle between different view layouts

Testing Your Endpoints

Simple Test (No Auth)

The simplest way to start is with an unauthenticated endpoint. Copy this code to Salesforce's Developer Console and execute it in Anonymous Apex:

// Create a descriptive payload
Map<String, Object> requestBody = new Map<String, Object>{
    'message' => 'Hello from Salesforce!',
    'timestamp' => System.now()
};

// Make the callout
Http http = new Http();
HttpRequest request = new HttpRequest();
request.setEndpoint('https://xxxx-xxxx.ngrok-free.app/webhook/your-endpoint-id');
request.setMethod('POST');
request.setHeader('Content-Type', 'application/json');
request.setBody(JSON.serialize(requestBody));

HttpResponse response = http.send(request);
System.debug('Response Status: ' + response.getStatusCode());
System.debug('Response Body: ' + response.getBody());

Authentication Methods

No Authentication

Perfect for initial testing and simple integrations. Create an endpoint and start sending requests immediately.

OAuth 2.0 Configuration

OAuth provides a more secure and flexible authentication method. Follow these steps to configure Salesforce for OAuth integration:

Step 1: Set Up External Credential

Navigate to Setup → Security → External Credentials
Click "New External Credential"
Fill in these details:
- Label: Mock_Lobster_Auth
- Name: Mock_Lobster_Auth
- Authentication Protocol: OAuth 2.0
- Authentication Flow Type: Client Credentials Flow
- Token URL: Your ngrok URL + /oauth2/token (e.g., https://your-ngrok-url/oauth2/token)
- Scope: Leave empty
- Pass client credentials in request body: ✓ Checked (Important for Mock Lobster)
Create a Principal:
- Click "New Principal" after saving the External Credential
- Parameter Name: Mock_Lobster_Principal
- Sequence Number: 1
- Client ID: (from Mock Lobster interface)
- Client Secret: (from Mock Lobster interface)

Step 2: Set Up Named Credential

Navigate to Setup → Security → Named Credentials
Click "New Named Credential"
Fill in these details:
- Label: Mock_Lobster_Integration
- Name: Mock_Lobster_Integration
- URL: Your ngrok URL (e.g., https://your-ngrok-url)
- External Credential: Select Mock_Lobster_Auth
- Generate Authorization Header: ✓ Checked

Step 3: Set Up Permission Set

Navigate to Setup → Users → Permission Sets
Click "New"
Create Permission Set:
- Label: Mock_Lobster_Access
- Name: Mock_Lobster_Access
After saving, click "External Credential Principal Access"
Add access to Mock_Lobster_Auth credential
Assign the Permission Set to your user

Validating Your Setup

After setting up Mock Lobster and configuring Salesforce, you should validate your endpoints using Salesforce's Anonymous Apex. Below are examples for each authentication type.

Testing No Authentication Endpoints

The simplest way to start is with an unauthenticated endpoint. Copy this code to Salesforce's Developer Console and execute it in Anonymous Apex:

// Create a descriptive payload
Map<String, Object> requestBody = new Map<String, Object>{
    'message' => 'Hello Mock Lobster!',
    'timestamp' => DateTime.now().format('yyyy-MM-dd HH:mm:ss'),
    'org' => UserInfo.getOrganizationName()
};

// Initialize HTTP objects
Http http = new Http();
HttpRequest request = new HttpRequest();

// Use your specific ngrok URL and endpoint ID
request.setEndpoint('https://xxxx-xxxx.ngrok-free.app/webhook/your-endpoint-id');
request.setMethod('POST');
request.setHeader('Content-Type', 'application/json');
request.setBody(JSON.serialize(requestBody));

// Log what we're about to send
System.debug('Preparing to send request to Mock Lobster...');
System.debug('Request Body: ' + JSON.serializePretty(requestBody));

try {
    // Send the request and capture the response
    HttpResponse response = http.send(request);
    
    // Log detailed information about what happened
    System.debug('Request completed');
    System.debug('Status Code: ' + response.getStatusCode());
    System.debug('Response Body: ' + response.getBody());
    
    // Provide meaningful feedback
    if (response.getStatusCode() == 200) {
        System.debug('SUCCESS: Mock Lobster received and processed the request');
    } else {
        System.debug('WARNING: Unexpected response from Mock Lobster');
        System.debug('Full Response Details: ' + response);
    }
} catch (Exception e) {
    System.debug('ERROR: Failed to communicate with Mock Lobster');
    System.debug('Error Type: ' + e.getTypeName());
    System.debug('Error Message: ' + e.getMessage());
}

Testing OAuth Endpoints

OAuth endpoints require more setup but provide better security. First ensure you've completed the OAuth setup steps, then use this code:

// Create a descriptive payload
Map<String, Object> payload = new Map<String, Object>{
    'message' => 'Testing OAuth integration',
    'timestamp' => DateTime.now().format('yyyy-MM-dd HH:mm:ss'),
    'org' => UserInfo.getOrganizationName()
};

// Initialize HTTP objects
Http http = new Http();
HttpRequest request = new HttpRequest();

// Use the Named Credential format for the endpoint
// Format: callout:NamedCredentialName/webhook/endpointID
request.setEndpoint('callout:Mock_Lobster_Integration/webhook/your-endpoint-id');

// Set up the request
request.setMethod('POST');
request.setHeader('Content-Type', 'application/json');
request.setBody(JSON.serialize(payload));

try {
    HttpResponse response = http.send(request);
    
    System.debug('Request completed');
    System.debug('Status Code: ' + response.getStatusCode());
    System.debug('Response Body: ' + response.getBody());
    
    if (response.getStatusCode() == 200) {
        System.debug('SUCCESS: Request processed by Mock Lobster');
    } else {
        System.debug('WARNING: Unexpected status code');
        System.debug('Response Headers: ' + response.getHeaderKeys());
    }
} catch (Exception e) {
    System.debug('ERROR: Failed to send request');
    System.debug('Error Message: ' + e.getMessage());
}

Common Debug Log Messages

Success Scenario

Request completed
Status Code: 200
Response Body: {"message":"Request received successfully","requestId":"..."}
SUCCESS: Request processed by Mock Lobster

OAuth Error

WARNING: Unexpected status code
Status Code: 401
Response Body: {"error":"invalid_token","error_description":"Invalid or expired token"}

Permission Error

ERROR: Failed to send request
Error Message: User does not have access to external credential principal

Verifying Requests in Mock Lobster

After sending either type of request:

Check the Mock Lobster interface:
- Click "View Requests" on your endpoint
- Verify the request was received
- Check that all headers and payload data are correct
Check the ngrok inspector (http://localhost:4040):
- Look for your request in the traffic log
- For OAuth requests, verify token requests and usage
- Check for any SSL/TLS issues

If you encounter issues:

Verify your ngrok URL is current (it changes in free tier)
Confirm Remote Site Settings are up to date
For OAuth, verify Named Credential configuration
Check server logs for any errors

Debug Tools

Mock Lobster provides two debugging interfaces:

Debug Interfaces

Mock Lobster provides two complementary interfaces for debugging your integrations:

Mock Lobster Interface (http://localhost:3003)

Shows configured endpoints and their settings
Displays received requests with parsed data
Provides authentication configuration details
Offers a high-level view of your integration

ngrok Inspector (http://localhost:4040/inspect/http)

The inspection interface provides real-time inspection of all HTTP traffic flowing through your ngrok tunnel, which is invaluable for debugging. You can:

View complete request and response details
Inspect headers, query parameters, and body content
Replay requests with modifications for testing
Monitor connection latency and timing
Export request/response pairs for documentation
Debug authentication issues by examining token flows

When debugging integration issues, it's helpful to arrange these interfaces side by side in your browser. The ngrok inspector shows you exactly what's being sent over the wire, while the Mock Lobster interface shows you how that data is being processed and interpreted.

Debugging OAuth Flows

OAuth integrations can be particularly complex to debug. Here's how to use both interfaces effectively:

In the ngrok inspector:
- Look for the initial token request (POST to /oauth2/token)
- Verify the client credentials are being sent correctly
- Check the token response format
- Follow subsequent requests using the token
- Monitor token expiration and renewal
In the Mock Lobster interface:
- Confirm endpoint configuration is correct
- Verify OAuth credentials are recognized
- Check if requests are being authenticated
- Monitor for authentication errors

Testing Pub/Sub Integration

Mock Lobster provides built-in support for testing Salesforce Pub/Sub API integrations. Here's how to use it:

Setting Up Pub/Sub Testing

Navigate to the Pub/Sub tab in the Mock Lobster UI
Click "Connect" and enter your Salesforce Pub/Sub credentials:
- Username
- Instance URL
- Client ID
- Client Secret

Subscribe to Topics

Once connected, enter the topic name you want to subscribe to
Click "Subscribe" to start receiving events
All received events will be displayed in real-time in the events panel

Monitoring Events

View event payloads and metadata in real-time
Events are preserved across page refreshes
Filter and search through received events
Clear event history as needed

Example Apex Code

Here's an example of publishing an event from Salesforce that Mock Lobster can receive:

// Create a descriptive event payload
Map<String, Object> eventData = new Map<String, Object>{
    'message' => 'Test Event',
    'timestamp' => DateTime.now().format('yyyy-MM-dd HH:mm:ss'),
    'org' => UserInfo.getOrganizationName()
};

// Publish the event
EventBus.publish(new Custom_Event__e(
    Payload__c = JSON.serialize(eventData)
));

Troubleshooting Pub/Sub

If you encounter issues: 1. Verify your credentials are correct 2. Ensure the topic exists in your Salesforce org 3. Check that your user has the necessary permissions 4. Verify the event schema matches your expectations

Troubleshooting

Common Issues

Port Selection
- Default port is 3003
- Automatically finds next available port if 3003 is in use
- Port selection sequence: 3003, 3004, 3005, ...
- Selected port is shown in console on startup
- Override with PORT environment variable

Port Conflicts (EADDRINUSE)

# Option 1: Free the specific port
kill $(lsof -t -i:3003)

# Option 2: Use different port
PORT=3456 npm run dev

# Option 3: Let Mock Lobster find an available port automatically
npm run dev

Salesforce Connection Issues
- Verify Remote Site Setting matches ngrok URL exactly
- Ensure ngrok URL uses HTTPS
- Check if ngrok URL has changed (free tier)
Authentication Failures
- Verify credentials match Mock Lobster configuration
- Check OAuth token endpoint URL
- Confirm Named Credential setup

Server Logging

Mock Lobster includes built-in logging to help monitor and troubleshoot your API testing:

HTTP Request Logging

All incoming HTTP requests are automatically logged using Morgan middleware
Logs include request method, path, status code, and response time

Example log format:

GET /api/endpoints 200 2.676 ms
POST /webhook/endpoint-1 200 0.878 ms
GET /error 500 1.190 ms

Configuration

Logging can be enabled/disabled through server options:

const server = new Server({
    enableLogging: true,  // Enable detailed request logging
    logFormat: 'combined' // Use combined log format
});

What's Logged

Server Events
- Server startup and configuration
- Port binding and listening status
- Shutdown events
Request Details
- HTTP method and URL
- Response status codes
- Request processing time
- Error conditions
OAuth Operations
- Token generation events
- Authentication failures
- Client validation results
PubSub Events
- Connection status
- Subscription events
- Stream errors

Viewing Logs

When running in development mode (npm run dev), logs appear in your terminal

Test logs can be captured using:

npm run test:coverage:detailed > test-logs.txt

Remember: For detailed request/response inspection beyond server logs, use the ngrok inspector at http://localhost:4040.

Development

Project Structure

mock-lobster/
├── src/                    # Source code
│   ├── server.js          # Main application entry point
│   ├── endpoint-service.js # Endpoint handling and management
│   └── oauth-service.js    # OAuth authentication logic
├── public/                 # Static assets
│   ├── app.html           # Main application interface
│   ├── styles/            # CSS stylesheets
│   └── scripts/           # Frontend JavaScript
└── package.json           # Project configuration

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make changes and test (npm test)
Commit changes (git commit -m 'Add amazing feature')
Create Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Why "Mock Lobster"?

In the vast ocean of API testing tools, Mock Lobster stands out with its distinctive approach to handling integration challenges. Just as a lobster's powerful claws help it navigate and manipulate its environment with precision, Mock Lobster helps developers grasp and manage their integration testing needs with ease. And yes, it's absolutely a B-52's reference! 🎸

Made with 🦞 by developers who love good tools and better puns

salesforce api testing mock oauth integration rest webhook

body-parser chalk express jsonwebtoken morgan salesforce-pubsub-api-client uuid

1 year ago

1 year ago

1 year ago

1 year ago