tessl/npm-mm

Mock mate library for mocking functions, HTTP requests, and file system operations in Node.js testing

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

HTTP Request Mocking

Name: tessl/npm-mm
Author: tessl

Comprehensive HTTP and HTTPS request mocking capabilities for testing network-dependent code. Mock complete request/response cycles with custom data, headers, status codes, and error conditions.

Capabilities

Mock HTTP Requests

Mock http.request() and http.get() calls with custom responses.

/**
 * Mock http.request() calls with custom responses
 * @param url - URL pattern to match (string, RegExp, URL, or object)
 * @param data - Response data (string, Buffer, or Readable stream)
 * @param headers - Response headers including optional statusCode
 * @param delay - Response delay in milliseconds (default: 0)
 */
function mockHttpRequest(url: RequestURL, data: ResponseData, headers?: Record<string, any>, delay?: number): void;

type RequestURL = string | RegExp | URL | object;
type ResponseData = string | Buffer | Readable;

Usage Examples:

import http from "node:http";
import { mockHttpRequest } from "mm";

// Mock simple string response
mockHttpRequest("/api/users", "[]", { "content-type": "application/json" });

http.get({ path: "/api/users" }, (res) => {
  console.log(res.statusCode); // => 200 (default)
  console.log(res.headers["content-type"]); // => "application/json"
  
  let body = "";
  res.on("data", chunk => body += chunk);
  res.on("end", () => console.log(body)); // => "[]"
});

// Mock with custom status code
mockHttpRequest("/api/error", "Not Found", { 
  statusCode: 404,
  "content-type": "text/plain"
});

// Mock with Buffer data
mockHttpRequest("/api/binary", Buffer.from("binary data"), {
  "content-type": "application/octet-stream"
});

// Mock with delay simulation
mockHttpRequest("/api/slow", "delayed response", {}, 2000); // 2 second delay

Mock HTTPS Requests

Mock https.request() and https.get() calls with custom responses.

/**
 * Mock https.request() calls with custom responses
 * @param url - URL pattern to match (string, RegExp, URL, or object)
 * @param data - Response data (string, Buffer, or Readable stream)
 * @param headers - Response headers including optional statusCode
 * @param delay - Response delay in milliseconds (default: 0)
 */
function mockHttpsRequest(url: RequestURL, data: ResponseData, headers?: Record<string, any>, delay?: number): void;

Usage Examples:

import https from "node:https";
import { mockHttpsRequest } from "mm";

// Mock HTTPS API response
mockHttpsRequest("/secure/api", '{"secure": true}', {
  "content-type": "application/json",
  "x-security": "encrypted"
});

https.get({ path: "/secure/api" }, (res) => {
  let body = "";
  res.on("data", chunk => body += chunk);
  res.on("end", () => {
    const data = JSON.parse(body);
    console.log(data.secure); // => true
  });
});

URL Pattern Matching

HTTP mocking supports flexible URL pattern matching:

import { mockHttpRequest } from "mm";

// Exact string match
mockHttpRequest("/api/users", "users data");

// RegExp pattern matching
mockHttpRequest(/\/api\/users\/\d+/, '{"id": 123}');

// Object with host and path
mockHttpRequest(
  { url: "/api/data", host: "api.example.com" },
  "host-specific data"
);

// Multiple patterns can be active simultaneously
mockHttpRequest("/api/posts", "posts data");
mockHttpRequest("/api/comments", "comments data");

Response Data Types

Support for various response data formats:

import fs from "node:fs";
import { Readable } from "node:stream";
import { mockHttpRequest } from "mm";

// String responses
mockHttpRequest("/api/text", "plain text response");

// Buffer responses  
mockHttpRequest("/api/binary", Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]));

// Readable stream responses
const stream = fs.createReadStream("large-file.json");
mockHttpRequest("/api/stream", stream);

// Array of data chunks (emitted sequentially)
mockHttpRequest("/api/chunked", [
  "chunk 1",
  "chunk 2", 
  "chunk 3"
]);

Mock HTTP Request Errors

Mock HTTP requests to emit errors during request or response phases.

/**
 * Mock http.request() to emit request or response errors
 * @param url - URL pattern to match
 * @param reqError - Request phase error (optional)
 * @param resError - Response phase error (optional)
 * @param delay - Error delay in milliseconds (default: 0)
 */
function mockHttpRequestError(url: RequestURL, reqError?: MockError, resError?: MockError, delay?: number): void;

type MockError = Error | string;

Usage Examples:

import http from "node:http";
import { mockHttpRequestError } from "mm";

// Mock request error (connection failure)
mockHttpRequestError("/api/fail", "Connection refused");

const req = http.request({ path: "/api/fail" }, (res) => {
  // This callback won't be called
});

req.on("error", (err) => {
  console.log(err.name); // => "MockHttpRequestError"
  console.log(err.message); // => "Connection refused"
});

req.end();

// Mock response error (after successful connection)
mockHttpRequestError("/api/response-fail", null, "Response timeout");

const req2 = http.request({ path: "/api/response-fail" }, (res) => {
  // Response received but will error
  res.on("error", (err) => {
    console.log(err.name); // => "MockHttpResponseError"
    console.log(err.message); // => "Response timeout"
  });
});

req2.end();

Mock HTTPS Request Errors

Mock HTTPS requests to emit errors during request or response phases.

/**
 * Mock https.request() to emit request or response errors
 * @param url - URL pattern to match
 * @param reqError - Request phase error (optional)
 * @param resError - Response phase error (optional)
 * @param delay - Error delay in milliseconds (default: 0)
 */
function mockHttpsRequestError(url: RequestURL, reqError?: MockError, resError?: MockError, delay?: number): void;

Usage Examples:

import https from "node:https";
import { mockHttpsRequestError } from "mm";

// Mock SSL/TLS error
mockHttpsRequestError("/secure/api", "SSL certificate error");

// Mock response parsing error
mockHttpsRequestError("/secure/data", null, "Invalid JSON response");

Namespace Access

HTTP mocking functions are available through namespaced objects:

// HTTP namespace object
const http: {
  request: typeof mockHttpRequest;
  requestError: typeof mockHttpRequestError;
};

// HTTPS namespace object  
const https: {
  request: typeof mockHttpsRequest;
  requestError: typeof mockHttpsRequestError;
};

Usage Examples:

import mm from "mm";

// Via namespace
mm.http.request("/api/data", "mock data");
mm.https.request("/secure/api", "secure data");

// Via named imports
import { http, https } from "mm";
http.request("/api/users", "users data");
https.requestError("/secure/fail", "Security error");

Advanced Patterns

Multiple Response Chunks

Simulate streaming responses with multiple data chunks:

import { mockHttpRequest } from "mm";

mockHttpRequest("/api/stream", [
  '{"users": [',
  '{"id": 1, "name": "Alice"},',
  '{"id": 2, "name": "Bob"}',
  ']}'
]);

// Response will emit 'data' events for each chunk

Custom Response Headers

Control response headers including status codes:

import { mockHttpRequest } from "mm";

mockHttpRequest("/api/custom", "response data", {
  statusCode: 201,
  "content-type": "application/json",
  "x-custom-header": "custom-value",
  "cache-control": "no-cache",
  "etag": '"123456"'
});

Request Interception

mm automatically intercepts matching requests and falls back to real requests for non-matching URLs:

import { mockHttpRequest } from "mm";

// Only requests to /api/mock will be intercepted
mockHttpRequest("/api/mock", "mocked");

// Requests to other paths will use real HTTP
// http.get("/api/real") -> makes actual network request
// http.get("/api/mock") -> returns "mocked"

Error Timing

Control when errors occur with delay parameters:

import { mockHttpRequestError } from "mm";

// Immediate error
mockHttpRequestError("/api/immediate", "Immediate failure", null, 0);

// Delayed error (simulates timeout)
mockHttpRequestError("/api/timeout", "Request timeout", null, 5000);

// Response error after delay
mockHttpRequestError("/api/slow-fail", null, "Slow response error", 3000);

Request Mocking Lifecycle

Request Interception: mm intercepts calls to http.request() and https.request()
URL Matching: Compares request options against registered URL patterns
Response Generation: Creates mock response object with specified data and headers
Event Emission: Emits appropriate events (response, data, end, error)
Fallback: Non-matching requests pass through to original HTTP functions

Types

// URL matching types
type RequestURL = string | RegExp | URL | object;

// Response data types
type ResponseData = string | Buffer | Readable;

// Error types for HTTP mocking
type MockError = Error | string;

// HTTP namespace interfaces
interface HttpMockNamespace {
  request: typeof mockHttpRequest;
  requestError: typeof mockHttpRequestError;
}

interface HttpsMockNamespace {
  request: typeof mockHttpsRequest;
  requestError: typeof mockHttpsRequestError;
}