How to Mock Services

Learn how to use Mocker to create mock API services.

Mocker is an in-cluster solution for creating mock API services in three simple steps:

Create a mock
- Write a mock from scratch or
- Generate a mock from user input
Configure the mock
Apply the configuration to the worker container

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 Kubernetes service 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 Kubernetes service 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 Kubernetes service 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 Kubernetes service 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 Kubernetes service 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 the generate 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 \
    -n <Kubernetes namespace where the Skyramp worker resides>

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.