v0.4.4

Changelog

• c0cd422 Added accumulator to track comparisions of each key when comparing objects

v0.4.3

Changelog

• 06d83d0 Restore body after read so downstream consumers can access it again

v0.4.2

Changelog

• 3a81a10 Added check to service initialization
• 3230b4c Added watcher for non macOS systems
• 6cc04c9 Adjust example cmd and directory structure
• d2a7fff Minor json correction in static mock doc
• f7096cf Removed fsevents (macOS specific watcher)
• 55d84f6 Working example for static mocking
• 1ff9075 feat: Added watcher to static mock definitions so that wiretap restart isn't required

v0.4.1

Changelog

• a8a157f Fixed #150
• 876b119 bumped to latest go

v0.4.0

Static Mocking in Wiretap

(https://pb33f.io/wiretap/mock-responses/#static-mocking)

Contributed by @akash4393

Table of Contents

• Overview
• How to Enable Static Mocking
• Mock Definitions
  • Request Definition
  • Response Definition
• Response Generation Using Request Data
• Directory Structure
• Example
• Notes

Overview

This feature allows static mocking of APIs in the Wiretap service by defining mock definitions in JSON files. It enables the server to match incoming requests against predefined mock definitions and return corresponding mock responses. If no match is found, the request is forwarded to the Wiretap's httpRequestHandler for further processing.

How to Enable Static Mocking

To enable static mocking, you need to set the --static-mock-dir argument to a directory path when starting Wiretap, or configure it in the Wiretap configuration file.

Example:

wiretap --static-mock-dir /path/to/mocks

When this path is set, Wiretap will expect mock definitions and response body JSON files in the following structure:

• /path/to/mocks/mock-definitions/ — Contains the mock definition JSON files.
• /path/to/mocks/body-jsons/ — Contains the response body JSON files.

The static mock service will start and load all the mock definitions found in /path/to/mocks/mock-definitions.

Mock Definitions

Mock definitions are JSON objects or arrays of objects that define the request and response structure. Each JSON object should contain the following keys:

• request — Specifies the conditions for the request.
• respose — Specifies the response that should be returned when the request matches the conditions.

Request Definition

The request definition is parsed into the following Go type:

type StaticMockDefinitionRequest struct {
	Method      string          `json:"method,omitempty"`
	UrlPath     string          `json:"urlPath,omitempty"`
	Host        string          `json:"host,omitempty"`
	Header      *map[string]any `json:"header,omitempty"`
	Body        interface{}     `json:"body,omitempty"`
	QueryParams *map[string]any `json:"queryParams,omitempty"`
}

Each field can use either a string or a regex string to match the actual request. For example, the header, body, and queryParams fields can contain regex patterns to match the incoming request.

Example Request Definition:

{
	"method": "GET",
	"urlPath": "/test",
	"header": {
		"Content-Type": "application.*"
	},
	"queryParams": {
		"test": "ok",
		"arr": ["1", "2"]
	},
	"body": {
		"test": "o.*"
	}
}

Response Definition

The response definition is parsed into the following Go type:

type StaticMockDefinitionResponse struct {
	Header           map[string]any `json:"header,omitempty"`
	StatusCode       int            `json:"statusCode,omitempty"`
	Body             string         `json:"body,omitempty"`
	BodyJsonFilename string         `json:"bodyJsonFilename,omitempty"`
}

• BodyJsonFilename: The name of a file in the body-jsons folder, which contains the response body JSON. If this is specified, Wiretap will return the content of that file instead of using the body field.

Example Response Definition with Inline Body:

{
	"statusCode": 200,
	"header": {
		"something-header": "test-ok"
	},
	"body": "{\"test\": \"${queryParams.arr.[1]}\"}"
}

In this example, the response body uses a reference to the request's query parameters.

Example Response Definition with Body from File:

{
	"statusCode": 200,
	"header": {
		"something-header": "test-ok"
	},
	"bodyJsonFilename": "test.json"
}

In this example, Wiretap will look for a file named test.json in the body-jsons folder and return its content as the response body.

Response Generation Using Request Data

The response body can dynamically generate values based on the request. This is done by using the request's fields (such as queryParams, body, etc.) in the response body.

For example:

{
	"statusCode": 200,
	"header": {
		"something-header": "test-ok"
	},
	"body": "{\"test\": \"${queryParams.arr.[1]}\"}"
}

In this case, the response body will include the second element from the arr query parameter in the incoming request. The ${} syntax is used to refer to the request's fields.

Directory Structure

The --static-mock-dir should point to a directory that contains the following subdirectories and files:

/path/to/mocks/
  ├── mock-definitions/
  │     ├── mock1.json
  │     ├── mock2.json
  │     └── ...
  └── body-jsons/
        ├── test.json
        └── ...

• mock-definitions/: Contains the mock request and response definitions.
• body-jsons/: Contains the actual response body JSON files referenced by the mock definitions.

Example

1. Directory Structure:

/mocks/
  ├── mock-definitions/
  │     ├── get-test-mock.json
  └── body-jsons/
        ├── test.json

2. get-test-mock.json:

{
  "request": {
    "method": "GET",
    "urlPath": "/test",
    "header": {
      "Content-Type": "application.*"
    },
    "queryParams": {
      "test": "ok",
      "arr": ["1", "2"]
    },
    "body": {
      "test": "o.*"
    }
  },
  "response": {
    "statusCode": 200,
    "header": {
      "something-header": "test-ok"
    },
    "bodyJsonFilename": "test.json",
  }
}

3. test.json:

{
  "test": "${queryParams.arr.[1]}"
}

With this configuration, when Wiretap receives a GET request to /test, it will respond with the content of test.json.

Notes

• If no mock definition is found that matches an incoming request, Wiretap will forward the request to the wiretap's request handler and let it return a response.
• The mock definitions can contain either a single object or an array of objects. In the case of an array, each object represents a separate mock definition.

Changelog

• aaac100 Added missing features needed for static mocking
• 6eec968 Basic use-cases for response body complete
• ca77a85 Cleaned up readme
• 1d082b4 Defined regexps as vars in package
• ba38352 Docs cleanup and defined constants
• eb3b8e3 Removed __debug file
• 5ac26eb Updated error handling and added readme
• 9089849 Updated gitignore to ignore debug files
• 89f7c86 WIP: Added new static mock service and basic logic for routing static mock requests

v0.3.0

Changelog

• de7b40f Update and rename LICENSE.md to LICENSE
• 24acd3e feat: added path level mockMode & path level hardValidation
• 8d89429 fix: mock_engine_test.go had out of date test
• 259a1a6 fix: spec needs to be provided for mockModeList to work

v0.2.2

Changelog

• 4f7bc5d Add .nvmrc for folks doing local dev that have multiple versions of node on their host
• 1ca6f78 Even leaner - running image ~36 MB footprint w/ alpine linux and wiretap binary
• a050935 fix up path
• 0a59369 let dockerfile support multi platform builds, change publish action to pulish muti-platform builds

v0.2.1

Changelog

• 1f83821 fix: also consider Accept header in addition to Content-Type when making decisions on media type

v0.2.0

Upgraded license to BUSL 1.1 and upgraded all dependencies.

Changelog

• 9c88a63 updated validator message
• 2dc1acd upgrade build for go 1.23
• a7b3522 v0.2.0

v0.1.20

Changelog

• f1c4224 Addressed issue #132