How to Mock Services
Mocker is an in-cluster solution for creating mock API services in three simple steps:
Prerequisites
Before using Mocker, you must install the Terminal Client on your machine and the Skyramp Worker in the environment where you want to mock services.
1. Create a Mock
To create a mock configuration, you have two options:
Write a Mock from Scratch
Use the init mock
command to create a template mock description. This template file will require user input to supply information about the services and endpoints you would like to mock.
Follow the protocol sub-commands below to generate a mock template based on your API protocol: gRPC, REST, JSON-RPC HTTP, or JSON-RPC WebSocket.
skyramp init mock grpc <mock name>
skyramp init mock rest <mock name>
skyramp init mock jsonrpc-http <mock name>
skyramp init mock jsonrpc-ws <mock name>
Generate a Mock from User Input
Use the generate
command to generate a mock configuration designed to use out-of-the-box, with less user-configuration required.
Follow the protocol sub-commands below to generate configurations based on your API protocol: gRPC, REST, JSON-RPC HTTP, or JSON-RPC WebSocket.
skyramp mocker generate grpc \
--api-schema <path to .proto file> \
--alias <name of Docker alias to mock> \
--port <port number for the service> \
--service <proto service name>
skyramp mocker generate rest \
--api-schema <path to OpenAPI schema file or URL (OpenAPI 3.x only)> \
--alias <name of Docker alias to mock> \
--port <port number for the service> \
--tag <optional OpenAPI tag to filter on> \
--paths <optional REST paths to filter on>
skyramp mocker generate rest \
--sample-response <path to response value (JSON blob or JavaScript function)> \
--alias <name of Docker alias to mock> \
--port <port number for the service> \
--endpoint-path <the REST path that upgrades HTTP to a WebSocket>
skyramp mocker generate jsonrpc-http \
--sample-response <path to response value (JSON blob or JavaScript function)> \
--alias <name of Docker alias to mock> \
--port <port number for the service> \
--endpoint-path <the REST path that upgrades HTTP to a WebSocket> \
--method <JSON-RPC method to utilize>
skyramp mocker generate jsonrpc-ws \
--sample-response <path to response value (JSON blob or JavaScript function)> \
--alias <name of Docker alias to mock> \
--port <port number for the service> \
--endpoint-path <the REST path that upgrades HTTP to a WebSocket> \
--method <JSON-RPC method to utilize>
After running the skyramp mocker generate
command, the following actions will be performed:
- A mock configuration file will be created in the
mocks
folder for the specified service or alias. - A response configuration file will be created in the
responses
folder for each method defined in the service. - If the endpoint definition does not already exist, it will create an endpoint configuration file in the
endpoints
folder.
You can edit the generated .yaml
files as explained in the next section.
Tip
We recommend running thegenerate
command in your source code repository so mocks are versioned and shareable across your team.
2. Configure the Mock
The mock description created with the init mock
command serves as a template for a mock. It prompts you to fill in the necessary information to configure specific details such as the endpoint, response, and overall mock configuration.
On the other hand, the mock description generated using the mocker generate
command is designed to be ready-to-use out-of-the-box. Despite its immediate usability, you still retain the flexibility to add or modify configuration details. This allows you to customize and enhance your mocks according to your specific requirements.
Below are examples of endpoint, response, and mock configurations:
Endpoint Configuration
Endpoint configuration files can be found in the endpoints
folder. Here’s an example of an endpoint configuration for a gRPC service:
version: v1
services:
- name: routeguide
port: 50051
alias: routeguide
protocol: grpc
endpoints:
- name: routeguide_jMBp
methods:
- name: GetFeature
- name: ListFeatures
- name: RecordRoute
- name: RouteChat
defined:
path: ./pb/route_guide.proto
name: RouteGuide
serviceName: routeguide
The generated endpoint configuration contains networking-level service details, including its name, port, alias, and protocol. Additionally, it includes metadata related to various endpoints that a service can have, including the methods it supports and the associated proto file.
Response Configuration
To configure responses, edit the response configuration files in the responses
folder. Here’s an example of a response configuration for a gRPC service:
version: v1
responses:
- name: GetFeature
blob: |-
{
"location": {
"latitude": 0,
"longitude": 0
},
"name": "default-string"
}
endpointName: routeguide_jMBp
methodName: GetFeature
- name: ListFeatures
blob: |-
{
"location": {
"latitude": 0,
"longitude": 0
},
"name": "default-string"
}
endpointName: routeguide_jMBp
methodName: ListFeatures
# More response configurations...
In this example, response behavior is defined for a specific method of the service, specifying the endpoint and method name as defined in the endpoint configuration. You can customize the response payload using a static JSON blob. For advanced capabilities like specifying dynamic responses, refer to the Mock Description page.
Mock Configuration
To configure the overall mock behavior, edit the mock configuration file in the mocks
folder. Here’s an example of a mock configuration for a gRPC service:
version: v1
mock:
description: routeguide
responses:
- responseName: GetFeature
- responseName: ListFeatures
- responseName: RecordRoute
- responseName: RouteChat
In this example, you configure the top-level mock’s behavior, including setting a description and specifying the responses to mock as defined in the response configuration. For advanced configurations such as specifying loss percentage, delays, and proxies, refer to the Mock Description page.
3. Apply the Mock to the Worker Container
To apply the mock configurations located in the mocks
folder to the worker, use the apply
command:
skyramp mocker apply \
-a <ip:port of the Skyramp worker>
Note
- Mocker does not automatically update the mocks when the responses are updated in the mock configuration file. You will need to run the
apply
command again in case your mock values change. - When mocking a gRPC service, the mock needs to be reapplied if the proto definition changes.
That’s it! All calls to the mocked service/s are now routed to Mocker, and it responds with the default values specified in the mock description.
Learn more about what you can configure in your mock description in Mock Description page.