This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Skyramp Docs for Kubernetes

Welcome to the Skyramp Docs for Kubernetes!

Is this your first time visiting? Start at the Intro to learn the basics.

To jump right into using Skyramp quickly, check out the Install and Tutorial pages under Get Started to guide you on your journey.

If you are interested in discovering the many ways Skyramp can work for you, explore the Use Cases.

You can also learn more about our tools:

Finally, for a deep dive into the nitty gritty like Architecture, CLI Commands, supported Libraries, and more, head to the Reference section.

We are glad you made it here. Get ready to embark on this learning adventure with Skyramp.

1 - Intro

Learn about the key concepts to be successful with Skyramp

What is Skyramp?

Skyramp is a super flexible way to do distributed testing of modular apps. It’s a toolkit for making sure your microservices work well together and don’t break in production.

Who can make the most of Skyramp?

If you’re a developer or an automation engineer drowning in microservices that need to play nicely together, Skyramp is for you, both when you’re hands-on-keyboard and when you’re running automated tests.

Why should I care about Skyramp?

Think about it this way: with distributed applications you can’t just rely on unit tests and end-to-end tests anymore. The combinatorial complexity is just too high. Distributed integration and performance testing of key parts of your application is the way forward. But how do you bring up just a part of your application? How can you isolate the microservices that you want to test? How do you easily trigger tests and get meaningful results that are easy to parse? Skyramp’s TestKit offers easy answers to these questions.

Where can I use Skyramp?

The Skyramp clients meet you in your workflow whether you use the terminal, VSCode, or another IDE. Similarly, the Skyramp libraries can be used to create distributed tests that augment your current test suite. Right now, the only requirements are Docker (for the container runtime) and Kubernetes (for orchestration).

When should I use Skyramp?

Use Skyramp for functional integration and performance testing in these situations:

  • Inner Dev Loop - That’s when you’re building and fixing your microservices. Skyramp can help you test things as you go, so you catch problems early.
  • Pipeline - When your code’s ready to push, Skyramp can jump into your automated testing pipeline and make sure everything still works like a charm.

How does Skyramp make testing easier?

Skyramp provides a TestKit with helpful tools inside:

  • Deployer - When you want to get your system under test up and running, Deployer helps you bring up just the services you care about and speeds up iteration through features like hot code reload.
  • Mocker - Think of it as a master of disguise for your services. It pretends to be other services so you can easily isolate services for testing.
  • Tester - Tester runs your tests and neatly organizes the results while making it easy to reach hard-to-get-to endpoints in your cluster.

So, are you ready to put Skyramp to the test? Check out the Use Cases page for ideas! You can also jump right in and Install the Client.

Continue to Get Started »

2 - Get Started

Learn how to get started with Skyramp

Skyramp works on the following operating systems and requires a container runtime:

Operating Systems

Min Version
Mac OS X 11.0
Ubuntu 18.04
CentOS 8.04
Fedora 36.0
Windows Subsystem for Linux (WSL) 1

Container Runtime and Cluster Support

Installing Skyramp is easy. All you need is Docker for the container runtime and Kubernetes for cluster orchestration.

Follow the links below to continue.

2.1 - Install Client

Learn how to download and install the Skyramp terminal client

For testing in the inner dev loop, you can use Skyramp through either our VSCode Extension or our terminal client. This page walks you through installing the terminal client.

For automated testing in CI/CD pipelines, please see the available Skyramp libraries.

Install the Terminal Client

As long as your machine has internet connectivity, you can easily install Skyramp with the following command:

bash -c "$(curl -fsSL https://skyramp.dev/installer.sh)"

Follow the step-by-step instructions in the terminal to complete installation.

Check Installation

Check your installation of Skyramp by running the following command:

skyramp version

For reference, here are all the CLI Commands available.

Uninstalling the Terminal client

If for any reason you want to uninstall Skyramp, run:

/bin/bash -c "$(curl -fsSL https://skyramp.dev/uninstaller.sh)"

Continue to the Walkthrough » for setting up a cloud-native application to try out Skyramp.

2.2 - Install Worker

Learn how to install the Skyramp Worker in your environment

The Skyramp Worker acts as the essential foundation for both Mocker, enabling service mocking capabilities, and Tester, facilitating the execution of in-cluster tests.

Prerequisites

If you don’t have Helm installed, refer to Helm’s documentation to get started. Then, follow these two steps to run the Skyramp Worker in Kubernetes using Helm:

1. Install Worker Using Helm

  1. Add Skyramp Helm Repo: To access Skyramp’s charts, add the Helm repository: 
    helm repo add skyramp https://letsramp.github.io/helm/
  2. Update Repositories: To ensure you have the latest chart versions, run the following: 
    helm repo update
  3. Install Worker Chart: To deploy the Skyramp Worker application to your Kubernetes cluster, use the following command: 
    KUBECONFIG=/path/to/kubeconfig helm install -n <namespace> <release-name> skyramp/worker
    • Replace /path/to/kubeconfig with the path to your Kubernetes configuration file (kubeconfig).
    • Replace <namespace> with the Kubernetes namespace where you want to deploy the Skyramp Worker chart. A namespace is a logical grouping of resources within your cluster. You can choose an existing namespace or create a new one.
    • Replace <release-name> with a name for this Helm release. A release is a unique instance of a Helm chart installation. You can choose any meaningful name for this release.

2. Register the Kubernetes Cluster with the Client

To interact with the Worker, you need to register your cluster with the Skyramp Terminal Client:

skyramp cluster register <path to kubeconfig file>

Installing Worker with Python Modules (Optional)

If you need to include additional Python modules in your Skyramp Worker for running dynamic requests and responses, you can follow these steps to build a custom Worker image with the required modules and then deploy it using Kubernetes.

Building the Worker Image with Python Modules

  1. Create a Dockerfile in your project directory or modify the existing one if you have it.

    FROM --platform=linux/amd64 public.ecr.aws/j1n2c2p2/rampup/worker:latest
COPY requirements.txt /
RUN pip3 install -r /requirements.txt

    This Dockerfile uses the base Skyramp Worker image and copies your requirements.txt file into it, then installs the Python modules specified in requirements.txt. Make sure to replace requirements.txt with the actual name of your requirements file.

  2. Build the custom Worker image using the docker build command. Replace <image-name> with a suitable name for your custom image and <image-tag> with the desired tag:

    docker build -t <image-name>:<image-tag> .

Using the Custom Worker Image

Now that you have built the custom Worker image with your Python modules, you need to push it to a container registry that is accessible to your cluster nodes. Then, you can deploy the Skyramp Worker with the custom image using the following helm install command, overriding the image configuration directly:

KUBECONFIG=/path/to/kubeconfig helm install -n <namespace> <release-name> skyramp/worker --set image.repository=<your-registry>/<image-name>,image.tag=<image-tag>

Continue to How to Mock Services » to learn how to generate and apply service mocks, or to How to Test Services » to learn how to write and start functional and load tests.

2.3 - Tutorial

A tutorial for developers getting started with Skyramp for Kubernetes

This tutorial is designed for developers who are just starting with Skyramp and want to grasp the fundamental concepts of testing and mocking from scratch. Think of it as the “Hello World” for testing and mocking microservices with Skyramp. By the end of this tutorial, you’ll be equipped with the knowledge to seamlessly integrate Skyramp into your own environment.

Note: this tutorial requires a development machine with a terminal client to execute the necessary commands. Skyramp supports Mac, Windows, and Linux environments.

Prerequisites

Before we dive into the tutorial itself, make sure you have the following prerequisites in place on your development machine:

1. Install Docker - Follow these instructions.

You can verify the Docker installation with docker -v:

$ docker -v
Docker version 24.0.6, build ed223bc

2. Install the Skyramp CLI - Follow these instructions.

You can verify the installation with skyramp version:

$ skyramp version
Skyramp Version:     v0.4.59
Git Commit:          59aed3a
Go Version:          go1.19.2
Default Worker Repo: public.ecr.aws/j1n2c2p2/rampup/worker
Default Worker Tag:  v0.4.59

3. Install Helm - Follow these instructions.

You can verify the Helm installation with helm version:

$ helm version
version.BuildInfo{Version:"v3.13.3", GitCommit:"c8b948945e52abba22ff885446a1486cb5fd3474", GitTreeState:"clean", GoVersion:"go1.21.5"}

4. Install kubectl - Follow these instructions.

You can verify the kubectl installation with kubectl version --client:

$ kubectl version --client
Client Version: v1.29.0
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3

Section 1: Setting Up a Test Environment

The first step for testing and mocking microservices is to set up a test environment. In this section, we will step through using Kubernetes to run a simple service that we can test with Skyramp.

1. Open a terminal client and create a directory on your development machine that will contain the tutorial project. We will use tutorial as our project directory name. In this case, execute these commands:

mkdir tutorial; cd tutorial

2. Next, let’s create a Kubernetes cluster using the Skyramp CLI. You can always register your own Kubernetes cluster with Skyramp, but we’ll create one for the purposes of this tutorial. Simply execute this command in a terminal client:

skyramp cluster create -l

You will see output similar to this:

Creating local cluster     [##############################################################] 100 %
Successfully created local cluster.
Starting/restarting Resolver     [###########################################################] 100 %
Resolver manages DNS changes needed to access the cluster and needs sudo access.
Password:

Provide the password and then set the KUBECONFIG environment variable in the terminal:

export KUBECONFIG=$HOME/.skyramp/kind-cluster.kubeconfig

3. In order install services from Skyramp’s Helm charts, add and update the Skyramp Helm repository using the helm repo command as shown below:

helm repo add skyramp https://letsramp.github.io/helm/; helm repo update

Then, install the echo service into the Kubernetes cluster using helm install:

helm install echo skyramp/echo -n default

The echo service is a simple service that we will use for testing in this tutorial, and can ultimately be substituted by your own services you want to test.

You should see output similar to this:

NAME: echo
LAST DEPLOYED: Thu Jan 11 08:48:55 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
  export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=echo,app.kubernetes.io/instance=echo" -o jsonpath="{.items[0].metadata.name}")
  export CONTAINER_PORT=$(kubectl get pod --namespace default $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
  echo "Visit http://127.0.0.1:8080 to use your application"
  kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT

4. Use kubectl to verify that the echo service was deployed to the cluster and is up and running.

kubectl get pods -n default

You should see output similar to below. Wait to proceed until you see “1/1” in the “READY” column for the service.

NAME                              READY   STATUS    RESTARTS   AGE
echo-cfd9d4bd9-t5vqq              1/1     Running   0          68s

5. Finally, we recommend creating a skyramp subfolder in your project directory to keep all of your Skyramp-related files in an organized location. Of course, this is entirely configurable to your specific needs. For the tutorial, initialize the Skyramp project folder structure with this command:

skyramp init skyramp

This will create a directory called skyramp with several folders underneath. Change the directory to skyramp and list the subdirectories:

cd skyramp; ls

You should now see the following subdirectories for storing your important configuration files:

endpoints mocks responses scenarios targets tests

The skyramp init command can also be used to generate configuration files as templates for tests, mocks, and targets. For more information, check out the Skyramp CLI docs.

Great job! The initial setup for the test environment is now complete.

Section 2: Testing Services with Skyramp’s Tester

Testing is essential to ensure the reliability of your applications. Skyramp simplifies the testing process by providing tools to validate the behavior of your distributed services. In this section, we’ll create a simple test scenario for the echo service.

1. Under the endpoints folder, create a file called echo-endpoint.yaml with these contents:

version: v1
services:
  - name: echo
    alias: echo
    port: 12346
    protocol: rest
endpoints:
  - name: echo-get
    path: /echo/{ msg }
    methods:
      - name: GET
        type: GET
    serviceName: echo

2. Under the scenarios folder, create a file called echo-scenario.yaml with these contents:

version: v1
scenarios:
  - name: echo_test
    steps:
      - requestName: echo_get
      - asserts: requests.echo_get.res.message == "ping pong"
requests:
  - name: echo_get
    endpointName: echo-get
    methodName: GET
    params:
      - name: msg
        in: path
        value: "ping"
    headers:
      key: value

This test scenario will call the echo-get endpoint and pass the value “ping”. The assert will then validate that value returned from the service is “ping pong”.

3. Under the tests folder, create a file called echo-test.yaml with these contents:

version: v1
test:
  name: echo test
  testPattern: 
    - scenarioName: echo_test

4. Notice how the 3 files above relate to each other by endpointName and scenarioName. You should now have this file structure in your project directory:

With the test files in place, let’s run our test scenario using skyramp tester from the command line:

skyramp tester start echo-test -n default

Note: the first time you run the test, the Skyramp Worker will be provisioned and installed to the cluster.

Expected output:

Starting tests
Tester finished
Test echo test------
 [Status: finished] [Started at: 2024-01-11 08:51:26 PST] [End: 2024-01-11 08:51:26 PST] [Duration: 0s]
  - pattern0.echo_test
    [Status: finished] [Started at: 2024-01-11 08:51:26 PST] [Duration: 0.0083s]
  - pattern0.echo_test.0.echo_get
    [Status: finished] [Started at: 2024-01-11 08:51:26 PST] [Duration: 0.0033s]
    Request : {"Path":"http://echo:12346/echo/ping","Method":"GET","Headers":{"key":"***sanitized***"}}
    Response: {"StatusCode":200,"Payload":"{\"message\":\"ping pong\"}"}
  - pattern0.echo_test.1.assert
    [Status: finished] [Started at: N/A]
    Assert: requests.echo_get.res.message == "ping pong"
    Passed: true

Nice work! You’ve successfully created and run a basic test for the echo service using Skyramp. Skyramp can support many types of test scenarios across multiple microservices running in a test environment. From this starting point, you can continue to explore the various ways to enhance the reliability of your applications through testing with Skyramp.

Resources to explore further:

Section 3: Mocking Services with Skyramp’s Mocker

Mocking is a crucial aspect of testing where we can simulate certain functionality to isolate and test specific components without relying on the actual implementation. Skyramp provides a rich framework for mocking within Kubernetes environments.

1. From the terminal, execute the following to uninstall the running echo service:

helm uninstall echo -n default

Expected output:

release "echo" uninstalled

2. If we run our test scenario again, we see that the service we want to test is not running. So, the output below showing an error with “no such host” is expected.

skyramp tester start echo-test -n default

Expected output:

Starting tests
Tester failed
Test echo test------
 [Status: failed] [Started at: 2024-01-11 09:05:29 PST]
  Error: failed to resolve echo: lookup echo on 10.96.0.10:53: no such host
  - pattern0.echo_test
    [Status: initializing] [Started at: N/A]

3. Let’s proceed by mocking this missing service, which is the echo service. Under the responses folder, create a file called echo-response.yaml with these contents:

version: v1
responses:
  - name: echo_get
    endpointName: echo-get
    methodName: GET
    blob: |
      {
        "message": "ping pong"
      }

4. Under the mocks folder, create a file called echo-mock.yaml with these contents:

version: v1
mock:
  description: echo mock
  responses:
    - responseName: echo_get

Now your project structure should look like this:

5. We can apply our new mock using skyramp mocker from the command line:

skyramp mocker apply echo-mock -n default

Expected output:

Applying mock config     [##############################################################] 100 %
Successfully applied mock configurations.

6. Run the test scenario again with the mock in place:

skyramp tester start echo-test -n default

We see our test scenario executes and finishes with a passing result:

Starting tests
Tester finished
Test echo test------
 [Status: finished] [Started at: 2024-01-11 08:54:53 PST] [End: 2024-01-11 08:54:53 PST] [Duration: 0s]
  - pattern0.echo_test
    [Status: finished] [Started at: 2024-01-11 08:54:53 PST] [Duration: 0.0015s]
  - pattern0.echo_test.0.echo_get
    [Status: finished] [Started at: 2024-01-11 08:54:53 PST] [Duration: 0.0011s]
    Request : {"Path":"http://echo:12346/echo/ping","Method":"GET","Headers":{"key":"***sanitized***"}}
    Response: {"StatusCode":200,"Payload":"{\"message\":\"ping pong\"}"}
  - pattern0.echo_test.1.assert
    [Status: finished] [Started at: N/A]
    Assert: requests.echo_get.res.message == "ping pong"
    Passed: true

Congratulations! You’ve successfully set up a basic mock using Skyramp.

Resources to explore further:

Section 4: Adapting Skyramp to Your Environment

Now that you’ve grasped the basics of testing and mocking with Skyramp, you can adapt these concepts to your specific environment.

Integrating Skyramp with Your Kubernetes Services

1. Identify the services in your Kubernetes environment that can benefit from testing and mocking.

2. Incorporate testing scenarios like the one in Section 2 to validate the functionality of your services.

3. Follow a similar process to what you’ve learned in Section 3 to create mock descriptions for service dependencies as needed.

Customizing Skyramp Configurations

1. Explore Skyramp’s configuration options to tailor the testing process to your specific needs. Skyramp supports multiple protocols and environment setups.

2. Use skyramp init to create description file templates as a base to work from. These templates provide the many configuration parameters available to you.

Resources to explore further:

3 - Use Cases

Learn about the primary use cases for Skyramp

Skyramp makes it easy to do distributed testing of your modular apps under real-world conditions. The components of the Skyramp TestKit addresses the different challenges of going beyond basic unit testing. Let’s look at some of the use cases where Skyramp can help:

Deployer

Deploy Only What You Need

Bringing up the whole application for testing when you’ve only touched a couple of services loses time. Deployer makes it super easy to deploy only what you need to test.

Hot Code Reload

Deployer makes it easy to iteratively develop or debug your code through our hot code reload feature, saving valuable time compared to tools like Skaffold or Kapp.

Mocker

Outside Help Not Required

External dependencies like Salesforce, Hubspot, Slack etc. are an important part of most modern applications. But it can be cost prohibitive or even impossible to run tests involving these integrations. Mocker can mimic these external services to deliver better test coverage.

Inside Help Not Required

There can also be internal dependencies that you need to mock to isolate the services you wish to test. This could be to speed up development iteration, or because although the API contract has been defined, the internal dependency is still under development.

Testing Offline

Sometimes, you might want to test without being online. Mocker can help you do that. You can check if your app behaves well even when it can’t connect to the internet or other outside services.

Testing Fast

Using Skyramp to pretend that things are in place can make your testing faster. It’s quicker because you don’t have to set up all the complicated external apps each time you test.

Tester

No Proxy, No Gateway, No Problem

When deploying to a cluster, it can be tricky to reach endpoints in the cluster. Tester automates everything you need to not worry about that anymore.

Testing Lots of Traffic

Skyramp can help you check how much traffic your app can handle, so you’ll know your app won’t break under normal demand, and you’ll also know how much it can take during surges.

Share Tests and Results

Unlike tests that are written and trashed again and again, Skyramp tests are easy to share, understand, re-use and modify by everyone. This ensures that tests are battle-tested, and makes testing with Skyramp easier for everyone. Also, through our dashboard we make it easy to share test results with your team for collaborative problem solving.

4 - Deployer

Render and deploy Helm charts through simple target descriptions

What is Deployer?

Deployer streamlines Kubernetes resource deployment for developers by providing a straightforward toolset. It empowers developers to deploy specific subsets of services seamlessly within the inner development loop. Key features of Deployer include:

  1. Swift deployment of Helm Charts in Kubernetes environments.
  2. Precise control over Kubernetes resource deployment.
  3. Flexible management of Helm sub-charts during deployment.

Leveraging Deployer optimizes the inner development loop, resulting in quicker and more efficient deployment of Kubernetes resources.

4.1 - How to Deploy Services

Learn how to use Deployer to deploy selected subsets of services within the inner development loop, including enabling the optional Hot Code Reload feature.

Deployer gives you a toolset for deploying Kubernetes resources. You can get started by following these three steps:

  1. Create a deployment target description.
  2. Bring up the target.
  3. Manage your deployment.

Prerequisites

Before using Deployer, you must install the Terminal Client on your machine and set up a Kubernetes cluster you want to deploy to using Skyramp.

1. Create a Deployment Target Description

  1. Create a folder called targets at the root of your microservice repository. This folder will store your target description files.
  2. Inside the targets folder, create a target description file (e.g. helm-demo.yaml) to describe the target you want to deploy.
  3. Customize the target description file to match your deployment needs.

Example:

namespace: helm-namespace
containers:
  - type: helm
    releaseName: my-release
    path: charts/test1
    valuesPath: files/values.yaml
    values:
      server:
        enabled: true
        service:
          port: 10000
      service:
        port: 5000
        type: ClusterIP
    includes:
      - Deployment/my-release-test1 
      - Job/* # include all jobs
      - server/* # include subchart server with all subresources

Modify the values according to your specific deployment requirements. The target description file includes:

  • The namespace field, which defines the target Kubernetes namespace.
  • The containers section, where you configure the deployment settings, including the release name (releaseName), the path to your Helm charts (path), an optional values file path (valuesPath), and additional values to override (values).
  • The includes field (alternatively, excludes), which specifies the resources to include in the deployment. You can specify specific resources or use the * wildcard to include matching resources.

Learn more about what you can configure in your target description in Target Description ».

Enable Debugging with Hot Code Reload (Optional)

Deployer supports a powerful debugging feature known as Hot Code Reload. This feature allows you to debug your services in real-time without the need for re-deployments. You can attach your debugger, step through code, and make changes while your service is running.

A visual walkthrough of the Hot Code Reload feature is available in this video:

To enable Hot Code Reload, include a debug section in your target description file under containers.

Example:

debug:
  - containerName: Deployment/my-service
    runtimeType: go
    command: myservice
    debugPort: 33333
    mountPaths:
      - /workspaces/myproject/src/myservice

With this debug section, you can enable Hot Code Reload for debugging purposes. Here’s a breakdown of the parameters you can configure in the debug section:

  • containerName: The name of the container to use in debug mode.
  • runtimeType: The runtime type of your service, such as go, node, or python.
  • command: The application entry point that will run in a loop, relative to the first path specified in mountPaths.
  • debugPort: The local port of the running service to debug.
  • mountPaths: Path(s) mounted to the remote container.

With Hot Code Reload, any code changes you make will immediately take effect, streamlining your debugging process.

2. Bring Up the Target

Run the up command to deploy the target, replacing helm-demo with your target name:

skyramp deployer up helm-demo

Deployer will read the target description file and launch the deployment process. It will handle the deployment of Helm charts using the configurations from your target description. Deployer will create or update the necessary Kubernetes resources, removing the need for manual management.

3. Manage Your Deployment

View the Status of Deployments

Once you have run deployer up on a target, you can view the status of the deployment by running the status command:

skyramp deployer status

This will output the status of the deployment in a digestible table format.

Tear Down the Target

After testing or when you’re done with the deployment, you can bring down the target using the down command:

skyramp deployer down helm-demo

Deployer will clean up all the resources deployed using the skyramp deployer up command.

That’s it! With these steps, you can quickly start using Deployer to simplify the deployment of your Kubernetes resources.

4.2 - Target Description

Learn more about specific features and configurations of the target description.

The How to Deploy Services section covers the steps for deploying services to your cluster with Deployer and managing your deployment. This section provides additional details about the target description file used with Deployer.

Target Description File

The target description file is a crucial component of the Deployer tool, containing the configuration parameters required to deploy your system-under-test efficiently. This file should be placed under the targets folder at the root of your microservice repository. You can name it with a .yaml extension, such as my-deployment.yaml. With this file, you can define and control how your services are deployed and configured within your Kubernetes cluster.

Specifying the Namespace and Containers

A target description file must include a namespace parameter representing the Kubernetes namespace for the cluster. Additionally, it should have a containers section that defines the specific deployment settings. All the parameters described in this document are specified under the containers section.

Example:

namespace: helm-namespace
containers:
  - type: helm
    releaseName: my-release
    path: charts/test1

Defining Helm Values

You can provide a path to the values.yaml file for your Helm chart using valuesPath. Additional values to override or extend the configuration from the values.yaml file can be added to the values section. Both valuesPath and values should be placed under containers.

Example:

    valuesPath: files/values.yaml
    values:
      server:
        enabled: true
        service:
          port: 10000
      service:
        port: 5000
        type: ClusterIP

Including and Excluding Services

You have the option to explicitly include or exclude specific services in the deployment by specifying them in the includes or excludes section under containers.

Example:

includes:
  - Deployment/my-service
  - Service/my-service
  - Job/* # include all jobs
  - server/* # include subchart server with all subresources
  - /* # include all resources in root chart
excludes:
  - Deployment/excluded-service

5 - Mocker

Replace service dependencies with lightweight static and dynamic mocks.

About Mocker

Mocker is an in-cluster solution for creating mock API services. Mocker can be used via the VSCode Extension, the Skyramp CLI, or the various supported language libraries.

Mocker allows you to have fine-grained control over the dependencies you want to mock and comes with the following features:

  1. Ability to mock gRPC, REST, JSON-RPC WebSocket, and JSON-RPC HTTP endpoints.
  2. Automatic creation of mock configurations from API files.
  3. Dynamic routing of calls from live to mocked services.
  4. Powerful gRPC mocking including the ability to proxy gRPC calls, and support for client streaming, server streaming, and bidirectional streaming.
  5. Support for mock values generated via generative AI.
  6. Ability to configure response latencies to test and debug real-world scenarios.
  7. Out of the box support for returning error codes to test error cases.

How Mocker Works

Mocker consists of 3 parts:

  1. A container that is deployed inside your Kubernetes cluster. It contains the core logic for implementing mocks and handles networking for the mocks.
  2. A mock configuration file that captures the signatures for the endpoints you want to mock and corresponding static mock responses. It is automatically generated from one of: an OpenAPI API spec (either by file path or URL reference), a protocol buffer API spec, or a JSON-RPC response file. Mock values can be easily edited as needed.
  3. Optional Javascript runtime support to enable dynamic mocking for complex test cases.

5.1 - 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:

  1. Create a mock
  2. Configure the mock
  3. 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.

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>

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.

5.2 - Mock Description

Learn about the specific features and configurations of the Skyramp mock description.

Introduction

The mock description in Skyramp allows you to create lightweight static and dynamic mocks to simulate service dependencies. It comprises three primary components:

  1. Mock Configuration: This file, residing in the mocks folder, defines the overall behavior of the mock. It empowers you to configure proxying, delays, errors, and more, facilitating comprehensive testing of your application.

  2. Response Configuration: Located in the responses folder, these files define response behavior for specific methods, allowing you to configure payloads and dynamic responses.

  3. Endpoint Configuration: Found in the endpoints folder, these files specify details related to the service’s networking aspects, supporting gRPC, REST, JSON-RPC WebSocket, and JSON-RPC HTTP endpoints.

To get started, follow the steps outlined in the How to Mock Services page. This guide will teach you how to dynamically generate a mock description by providing service-level information. Alternatively, if you prefer to create a mock definition from scratch, you can create .yaml files in the mocks, responses, and endpoints directories of your project (e.g., my-mock.yaml, my-response.yaml, and my-endpoint.yaml) and configure the necessary information by following the guidelines below.

Mock Configuration

The mock configuration serves as the central component of the mock definition and defines the overall mock behavior.

Example Mock Configuration:

version: v1
mock:
    description: routeguide
    responses:
        - responseName: ListFeatures
        - responseName: RecordRoute
        - responseName: RouteChat
          lossPercentage: 50
          delayConfig:
              minDelay: 1000
              maxDelay: 2000
    proxies:
        - endpointName: routeguide_jMBp
          methodName: GetFeature

In this example:

  • description: Provides a description of your mock configuration.
  • responses: Allows you to specify responses for various gRPC methods.
  • proxies: Enables gRPC proxying for specific endpoints and methods.

This example showcases advanced mock capabilities, including:

  • gRPC Proxying: Routing mock data to specific endpoints and methods.
  • Delays and Errors: Simulating network conditions by introducing delays and error percentages.

gRPC Proxying

Skyramp provides the capability to act as a proxy for gRPC services, selectively mocking certain methods while forwarding the rest to the live service. To enable this feature, you can specify the endpoint and methods to be proxied in the proxies section of the mock configuration.

Example Mock Configuration:

version: v1
mock:
    description: routeguide
    responses:
        - responseName: ListFeatures
        - responseName: RecordRoute
        - responseName: RouteChat
    proxies:
        - endpointName: routeguide_jMBp
          methodName: GetFeature

In this gRPC configuration example, requests to the GetFeature method are directed to the live service, while all other requests to the routeguide service are mocked.

Note: If a gRPC method is defined in the ‘.proto’ file but not listed in the mock description, Skyramp implicitly forwards the corresponding request(s) to the live service. This flexibility allows you to control the behavior of specific gRPC methods in your mock configurations.

Delays and Errors

In your mock configuration, you can introduce delays and error configurations using the following properties:

  • lossPercentage: Specifies the percentage of requests that will result in an error response.
  • delayConfig: Defines the delay configuration for the mock response, including the minimum (minDelay) and maximum (maxDelay) delay in milliseconds.

Note: When minDelay and maxDelay share the same value, the delay is static. However, if these values differ, Skyramp will apply a random delay within the specified range, with a maximum delay of 10,000 milliseconds (10 seconds).

Example Mock Configuration:

version: v1
mock:
    description: routeguide
    responses:
        - responseName: GetFeature
        - responseName: ListFeatures
        - responseName: RecordRoute
        - responseName: RouteChat
          lossPercentage: 50
          delayConfig:
              minDelay: 1000 # in ms
              maxDelay: 2000 # in ms

In the provided example, the RouteChat mock response will experience a random delay between 1,000 and 2,000 milliseconds before being returned. Additionally, around 50% of requests will result in an error response.

You have the flexibility to specify delays and errors at two levels: for a specific method or for the entire endpoint. The previous example demonstrates how to configure delays and errors for a specific response. To apply the same delay and error settings to all responses, define the lossPercentage and delayConfig in the mock section:

Example Mock Configuration:

version: v1
mock:
    description: routeguide
    responses:
        - responseName: GetFeature
        - responseName: ListFeatures
        - responseName: RecordRoute
        - responseName: RouteChat
    lossPercentage: 50
    delayConfig:
        minDelay: 1000 # in ms
        maxDelay: 2000 # in ms

In this scenario, all responses will encounter a delay between 1,000 and 2,000 milliseconds, and approximately 50% of requests will result in an error response.

Response Configuration

The response configuration file defines the response behavior for a specific method of the service.

Example Response Configuration:

version: v1
responses:
    # Unary RPC
    - name: GetFeature
      blob: |-
        {
          "name": "fake",
          "location": {
            "latitude": 400,
            "longitude": 600
          }
        }          
      endpointName: routeguide_jMBp
      methodName: GetFeature
    # Server Streaming RPC
    - name: ListFeatures
      javascript: |
        function handler(req) {
          const values = [];
          for (let i = 0; i < 5; i) {
            values[i] = {
              name: "random" + i,
              location: {


                longitude: i * 100,
                latitude: i * 100
              }
            };
          }

          return {
            values: values
          };
        }          
      endpointName: routeguide_jMBp
      methodName: ListFeatures
    # Client Streaming RPC
    - name: RecordRoute
      javascript: |
        function handler(req) {
          var l = req.values.length;

          return {
            value: {
              pointCount: l,
              featureCount: l,
              distance: l * 100,
              elapsedTime: 0
            }
          };
        }        
      endpointName: routeguide_jMBp
      methodName: RecordRoute
    # Bidirectional Streaming RPC
    - name: RouteChat
      javascript: |-
        const msgs = [];

        function handler(req) {
          msgs.push(req.value);

          return {
            values: msgs
          };
        }        
      endpointName: routeguide_jMBp
      methodName: RouteChat

In this example, you can see support for mocking various gRPC methods, including Unary RPC, Server Streaming RPC, Client Streaming RPC, and Bidirectional Streaming RPC. It also demonstrates the use of dynamic responses for more complex testing scenarios.

Dynamic Responses

Dynamic responses offer flexibility in customizing response generation logic and simulating complex response configurations. You can use different attributes to specify dynamic response behavior, such as javascript, javascriptPath, python, or pythonPath. Each attribute allows you to define custom response handling logic and return a JSON representation of the response value.

JavaScript Dynamic Response

  1. Using the javascript Attribute

    To create JavaScript-based dynamic responses, employ the javascript attribute for a response in your response configuration. Define a function called handler that takes any necessary parameters. Implement your custom JavaScript logic within the handler function and return a JSON object representing the response value.

    Example Response Configuration:

    version: v1
responses:
    - name: RecordRoute
      javascript: |
        function handler(req) {
          var l = req.values.length;

          return {
            value: {
              pointCount: l,
              featureCount: l,
              distance: l * 100,
              elapsedTime: 0
            }
          };
        }        
      endpointName: routeguide_jMBp
      methodName: RecordRoute
    # More response configurations...

  2. Using the javascriptPath Attribute

    Alternatively, you can use the javascriptPath attribute to specify the path to an external JavaScript script file containing your custom response handling logic.

    Example Response Configuration:

    version: v1
responses:
    - name: RecordRoute
      javascriptPath: scripts/recordRoute.js
      endpointName: routeguide_jMBp
      methodName: RecordRoute
    # More response configurations...

    The external JavaScript script file recordRoute.js defines a handler function to process incoming requests and generate appropriate responses.

Python Dynamic Response

Note: If your dynamic Python response relies on additional Python modules, refer to the Installing Worker with Python Modules section to learn how to build the custom Skyramp Worker image.

  1. Using the python Attribute

    You can use the python attribute within the responseValues section of your response definition. This attribute allows you to define a function called handler that takes any necessary parameters, representing the incoming request or context. Within the handler function, you can implement your custom Python logic and return a JSON representation of the response value using SkyrampValue.

    Example Response Configuration:

    version: v1
responses:
    - name: RecordRoute
      python: |
        def handler(req):
          l = req.values.length;

          return SkyrampValue(
            value = {
              "pointCount": l,
              "featureCount": l,
              "distance": l * 100,
              "elapsedTime": 0
            }
          )
        }        
      endpointName: routeguide_jMBp
      methodName: RecordRoute
    # More response configurations...

  2. Using the pythonPath Attribute

    Alternatively, you can use the pythonPath attribute to specify the path to an external Python script file containing your custom response handling logic.

    Example Response Configuration:

    version: v1
responses:
    - name: RecordRoute
      pythonPath: scripts/record_route.py
      endpointName: routeguide_jMBp
      methodName: RecordRoute
    # More response configurations...

    The external Python script file record_route.py defines a handler function to process the request or context and generate the response.

These dynamic response options allow you to tailor the responses generated by your mock server based on specific conditions or logic needed for testing.

AI-Generated Default Values

Skyramp integrates with OpenAI to provide AI-generated default values for response configurations. This optional feature can be enabled by invoking skyramp mocker generate with the --openai option.

To use this option:

  1. Create an OpenAI developer account by following the OpenAI documentation if you don’t have one already.

  2. Set the OPENAI_API_KEY environment variable by running the following command in your terminal:

export OPENAI_API_KEY=<YOUR_API_KEY>

Note: You can set this environment variable temporarily for the current terminal session. For permanent setup, add the export command to your shell’s profile file (e.g., .bashrc, .bash_profile, .zshrc, etc.).

  1. Run the skyramp mocker generate command with the --openai option, as shown below:
skyramp mocker generate grpc \
  --api-schema routeguide.proto \
  --alias routeguide \
  --port 50051 \
  --service RouteGuide \
  --openai

Skyramp limits AI-generated default values to a maximum of three response value JSON blobs per session to prevent excessive use of OpenAI tokens for large schema files. AI-generated defaults will be available for a maximum of three responses, while the remaining responses will have Skyramp-generated defaults.

Please note that the limits may change based on usage and feedback.

Endpoint Configuration

The endpoint configuration file defines networking-level service details for an endpoint.

Example Endpoint Configuration:

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

For configuring the endpoint file, we have a few key attributes:

  • services: This section lists the services available in your project. In this example, there is one service named routeguide.

  • endpoints: Under the endpoints section, you define individual endpoints, specifying the available methods, the service definition path, and the service name. In the example, we have an endpoint named routeguide_jMBp for the RouteGuide service.

  • methods: Within each endpoint, you list the available methods. In this case, we have methods like GetFeature, ListFeatures, RecordRoute, and RouteChat. This helps specify the details of each method and how it should behave.

  • defined: Here, you specify the service definition file’s path and the service name. The service definition file (route_guide.proto) outlines the structure of the service and its methods.

By configuring endpoints, you define the available services and methods within your project, facilitating mocking services in your distributed application. We recommend dynamically generating a mock by providing service-level information.

TLS Support

Please note that mocking is not supported for endpoints using TLS. Endpoints using HTTPS should be replaced with HTTP.

6 - Tester

Write and run functional and load tests using a simple declarative description

What is Tester?

Tester is a solution that simplifies the process of both writing and running tests for complicated distributed apps. Tester can be used via the VSCode Extension, the Skyramp CLI, or the various supported language libraries.

Some of the features of Tester include:

  1. The simplicity of specifying API requests in a test. These can be static or dynamically generated via a script.
  2. Overriding mock configurations (such as the responses configured for a mock).
  3. Validation for responses received from the system under test.
  4. The ability to chain request and response values throughout the life of a test.
  5. Load testing.
  6. Report generation based on the results of a test.
  7. Metrics collection from the system under test (CPU and memory).

In conjunction with Deployer and Mocker, Tester can be used to run powerful integration and load tests on a subset of your application thereby increasing confidence and saving developers from flaky end-to-end tests.

How Tester Works

Tester consists of 3 parts:

  1. The core logic for running tests that lives in the Skyramp worker.
  2. A test description that captures the instructions for running the test (what is called, where the call is made to, how the response should look, etc.).
  3. Javascript support for specifying pre-execution steps, post-execution steps, or for creating inputs for load tests.

Once the Skyramp worker is up and running, a user can use the VSCode extension, the Skyramp CLI, or a language library to generate and manage distributed functional integration and performance tests. Once a user is ready to run the tests, they can use one of the previous methods to send tests to the Skyramp worker, which will trigger the tests to begin. Once the test is completed, the user will be able to view corresponding test results.

6.1 - How to Test Services

Learn how to use Tester to write and run tests for distributed applications.

Tester simplifies writing and running tests for complicated distributed apps in four simple steps:

  1. Create a test
  2. Configure the test
  3. Run the test
  4. Analyze test results

Prerequisites

Before using Tester, you must install the Terminal Client on your machine and the Skyramp Worker in the environment where you want to run tests.

1. Create a Test

To create a test configuration, you have two options:

Write a Test from Scratch

Use the init test command to create a template test description. This template file will require user input to supply information about the services and endpoints you would like to test.

Follow the protocol sub-commands below to generate a test template based on your API protocol: gRPC or REST.

  skyramp init test grpc <test name>
  
  skyramp init test rest <test name>

Generate a Test from User Input

Use the generate command to generate a default test configuration to use and start with. These tests will work out-of-the-box but are intended to be a starting point for more complicated testing logic in different applications.

Follow the protocol sub-commands below to generate configurations based on your API protocol: gRPC or REST.

  skyramp tester generate grpc \
    --api-schema <path to .proto file> \
    --alias <name of Kubernetes service to test> \
    --port <port number for the service> \
    --service <name of proto service>
  
  skyramp tester generate rest \
    --api-schema <path to OpenAPI schema file or URL (URL support for OpenAPI 3.x only)> \
    --alias <name of Kubernetes service to test> \
    --port <port number for the service> \
    --tag <optional OpenAPI tag to filter on> \
    --paths <optional REST paths to filter on>  \
    --crud-scenarios <enable generating CRUD (Create, Read, Update, Delete) scenarios for REST endpoints>

This command performs the following actions:

  • Creates a test configuration file in the tests folder for the specified service or alias.
  • Creates a scenario configuration file in the scenarios folder for each method defined in the service.
  • If the endpoint definition does not already exist, it creates an endpoint configuration file in the endpoints folder.

You can edit the generated .yaml files as explained in the next section.

2. Configure the Test

The test description created with the init test command serves as a template for a test. It prompts you to fill in the necessary information to configure specific details such as the endpoint, scenario, and overall test configuration.

On the other hand, the test description generated using the tester 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 tests according to your specific requirements.

Below are examples of endpoint, scenario, and test 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 contains metadata related to various endpoints that a service can have, including the methods it supports and the associated proto file.

Scenario Configuration

To configure scenarios, edit the scenario configuration file in the scenarios folder. Here’s an example of a scenario configuration for a gRPC service:

version: v1
requests:
    - name: GetFeature_18GO
      blob: |-
        {
          "latitude": 0,
          "longitude": 0
        }        
      endpointName: routeguide_jMBp
      methodName: GetFeature
    - name: ListFeatures_5P9V
      blob: |-
        {
          "hi": {
            "latitude": 0,
            "longitude": 0
          },
          "lo": {
            "latitude": 0,
            "longitude": 0
          }
        }        
      endpointName: routeguide_jMBp
      methodName: ListFeatures
    # More request configurations...

In this example, you define request behavior for a specific method of the service and specify the endpoint and method name as defined in the endpoint configuration. You can customize the request payload using a static JSON blob. To create more complex requests, you can add advanced capabilities such as defining dynamic requests and adding overrides and parameters.

The scenario file generated using tester generate by default only lists the aforementioned requests. To add advanced capabilities like assertions and chaining, you can create additional scenario files in the scenarios folder. These files can reference the generated requests and provide more complex test scenarios.

You can read about all advanced capabilities in the Test Description page.

Test Configuration

To configure the overall test behavior, edit the test configuration file in the tests folder. Here’s an example of a test configuration for a gRPC service:

version: v1
test:
    name: routeguide
    testPattern:
        - requestName: GetFeature_18GO
          startAt: 1
        - requestName: ListFeatures_5P9V
          startAt: 1
        - requestName: RecordRoute_MD5D
          startAt: 1
        - requestName: RouteChat_QQEf
          startAt: 1

In this example, you configure the top-level test’s behavior, including setting a name for the test and specifying the test pattern by referencing requests and scenarios as defined in the scenario configuration. Advanced capabilities like configuring load testing available in the Test Description page.

3. Run the Test

Once the test description is in place, you can run the test. To run the test, you first need to reference the specific test file that will be used. To do this, refer to the tests directory. The name of the test will be the name of the respective file containing the test, without the file extension. For example, if you have a file located at tests/checkout-test.yaml, the test file name will be checkout-test.

  skyramp tester start <test file name> \
    -n <Kubernetes namespace where the Skyramp worker resides>

After running the command above to start the test, there will be output on the progress/status of the test until it finishes. Note that if you interrupt the command (such as by sending a SIGINT), the test will continue to run in the background in the Skyramp worker. For an ongoing test, you can check the status by running skyramp tester status <test file name> and providing either the address or namespace, as previously described.

Stop the Test

To stop an ongoing test, run skyramp tester stop <test file name>, once again with either the address or namespace arguments.

Learn more about what you can configure in your test description on the Test Description page.

4. Analyze Test Results

There are several ways to view and retain test results:

  1. Generate an HTML test report by running skyramp tester start with the optional --html-report flag. The report is saved in the “results” directory of your working directory.

  2. Start a Skyramp dashboard by running skyramp dashboard up. Refer to the dashboard documentation to learn more about managing test results.

6.2 - Test Description

Learn more about specific features and configurations of the Skyramp test description.

Introduction

The test description in Skyramp simplifies the process of writing and running tests for complex distributed applications. It consists of three primary components:

  1. Test Configuration: This file, residing in the tests folder, defines the overall behavior of the test. It enables you to configure test patterns and load testing.

  2. Scenario Configuration: Found in the scenarios folder, these files define request behavior for specific methods or chains of requests and asserts in scenarios. They also allow you to configure payloads, dynamic requests, and set overrides and parameters.

  3. Endpoint Configuration: Located in the endpoints folder, these files specify details related to the service’s networking aspects, supporting gRPC, REST, JSON-RPC WebSocket, and JSON-RPC HTTP endpoints.

To get started, follow the steps outlined in the How to Test Services page. This guide will teach you how to dynamically generate a test description by providing service-level information. Alternatively, if you prefer to create a test definition from scratch, you can create .yaml files in the tests, scenarios, and endpoints directories of your project (e.g., my-test.yaml, my-scenario.yaml, and my-endpoint.yaml) and configure the necessary information by following the guidelines below.

Test Configuration

The test configuration serves as the central component of the test definition and defines the overall test behavior.

Example Test Configuration:

version: v1
test:
  name: routeguide
  testPattern:
    - startAt: 1
      scenarioName: scenario1
      atOnce: 2
      targetRPS: 3000
      duration: 10
      rampUp:
        duration: 3
        interval: 1
  override:
    mock:
      - endpointName: helloworld
        methodName: SayHello
        blob: |
          {
              "message": "myTest"
          }

In this example:

  • name: Specifies the name of your test.
  • testPattern: Enables the definition of various test scenarios.
  • override: Allows you to override mock behavior.

This example showcases advanced test capabilities, including:

  • Overrides: Customizing endpoint behaviors by specifying mocks.
  • Load Testing: Simulating heavy user traffic with features like target RPS and ramp-up controls.

Overrides

The override attribute in the test configuration allows you to customize specific endpoints within your tests, providing flexibility in your testing scenarios. By setting the override attribute, you can specify a mock to modify an endpoint defined elsewhere in the project folder. This customization enables you to simulate various scenarios and test your application’s robustness effectively.

Example Test Configuration:

version: v1
test:
  name: routeguide
  testPattern:
    - startAt: 1
      scenarioName: scenario1
  override:
    mock:
      - endpointName: routeguide_jMBp
        methodName: GetFeature
        blob: |-
          {
            "name": "fake",
            "location": {
              "latitude": 400,
              "longitude": 600
            }
          }

The override attribute is used to customize endpoints. The mock section in the example specifies the details of the override:

  • endpointName: Identifies the endpoint you want to override, in this case, routeguide_jMBp.
  • methodName: Specifies the specific method of the endpoint you wish to modify, here, GetFeature.
  • blob: Contains the customized data or response that will replace the original response from the endpoint.

By leveraging the override attribute, you can seamlessly adapt endpoint behaviors within your tests, allowing you to create various testing scenarios and evaluate your application’s performance under different conditions.

Load Testing

Load testing allows you to simulate heavy user traffic on your application by transforming functional tests into load tests. This can be achieved by incorporating specific load profile keywords into your tests.

Example Test Configuration:

version: v1
test:
  name: routeguide
  testPattern:
    - startAt: 1
      scenarioName: scenario1
      atOnce: 2
      targetRPS: 3000
      duration: 10
      rampUp:
        duration: 3
        interval: 1

The atOnce attribute in the testPattern signifies the concurrency of the scenario1. With atOnce set to 2, everything defined in scenario1 will run with a concurrency of 2, happening in parallel.

To control the load, you can utilize the following parameters:

  • targetRPS: Specifies the target Requests Per Second (RPS) your application should handle.
  • duration: Indicates the total duration of the load test in seconds.
  • rampUp: Allows you to gradually increase the load on an endpoint.
    • duration: Specifies how long it takes for the traffic ramp-up to occur.
    • interval: Signifies the rate at which traffic increases.

In the provided example, the load increases over 3 seconds, with increments every second until it reaches the target RPS of 3000. Modifying these values enables you to model traffic behavior for your application and test how it responds to varying levels of load. If targetRPS is not specified, Tester will attempt to send as many requests as possible within the system’s context.

Scenario Configuration

The scenario configuration file defines request behaviors for specific methods and creates scenarios as chains of defined requests and asserts.

Example Scenario Configuration:

version: v1
scenarios:
  - name: scenario1
    steps:
      - requestName: GetFeature_18GO
      - asserts: requests.GetFeature_18GO.res.name == "fake"
requests:
  - name: GGetFeature_18GO
    javascript: |-
      function handler(req) {
        // Your JavaScript logic here
        return {
          value: {
            latitude: x,
            longitude: y
          }
        };
      }      
  - name: ListFeatures_5P9V
    blob: |-
      {
        "hi": {
          "latitude": 0,
          "longitude": 0
        },
        "lo": {
          "      

latitude": 0,
          "longitude": 0
        }
      }
    endpointName: routeguide_jMBp
    methodName: ListFeatures
  # More request configurations...

In this example:

  • scenarios: Allows you to define different test scenarios, and this example includes a scenario named scenario1.
  • requests: Contains configurations for individual requests (to be referenced in scenarios by name).

Some advanced capabilities of the scenario configuration include:

Scenarios and Asserts

Scenarios are representations of end-user use cases that require testing, allowing you to define a sequence of actions to be performed, typically involving requests to specific endpoints. Each named scenario includes a steps attribute, listing these actions, which can be executed sequentially or concurrently, simulating various usage patterns, including load tests.

Example Scenario Configuration:

version: v1
scenarios:
  - name: scenario1
    steps:
      - requestName: GetFeature_18GO
      - asserts: requests.GetFeature_18GO.res.name == "fake"

requests:
  - name: GetFeature_18GO
    endpointName: routeguide_jMBp
    methodName: GetFeature
    javascript: |-
      function handler(req) {
        // Your JavaScript logic here
        return {
          value: {
            latitude: x,
            longitude: y
          }
        };
      }      
  # More request configurations...

In this example:

  • scenario1 is defined, containing two steps executed sequentially.
  • The first step utilizes the requestName attribute, referencing a request object previously defined in the configuration.
  • The second step is an assert statement, used to verify that the response from the request matches the expected value.

To use an assert, the asserts parameter is defined within the step, with a value in the format:

requests.<name of request>.res.message == "<expected value>"

Where <name of request> refers to the name of the previously defined request, and <expected value> is a string representing the expected return value from the request.

Note: Values returned by services are interpreted as JavaScript for evaluating assert statements. The type may not always be a string, but could be a boolean or a number, among other types. When working with a boolean, the <expected value> should be true or false and not "true" or "false" in the assert statement.

In scenarios, the associated steps are executed sequentially. To execute items in parallel, refer to the testPattern defined in the test configuration.

Dynamic Requests

Dynamic requests provide the flexibility to customize request handling logic in your scenario configurations. You can use different attributes to specify dynamic request behavior, such as python, pythonPath, javascript, or javascriptPath. Each attribute allows you to define custom request handling logic and return a JSON representation of the response value.

JavaScript Dynamic Requests

  1. Using the javascript Attribute

    To create JavaScript-based dynamic requests, employ the javascript attribute within the requestValue section of your request definition. Define a function called handler that takes the req parameter. Implement your custom JavaScript logic within the handler function, and return a JSON object representing the response value.

    Example Scenario Configuration:

    version: v1
requests:
  - name: GetFeature_18GO
    javascript: |-
      function handler(req) {
        // Your JavaScript logic here
        return {
          value: {
            latitude: x,
            longitude: y
          }
        };
      }      
    endpointName: routeguide_jMBp
    methodName: GetFeature
  # More request configurations...

  2. Using the javascriptPath Attribute

    Alternatively, you can use the javascriptPath attribute to specify the path to an external JavaScript script file that contains your custom request handling logic.

    Example Scenario Configuration:

    version: v1
requests:
  - name: GetFeature_18GO
    javascriptPath: scripts/getFeature.js
    endpointName: routeguide_jMBp
    methodName: GetFeature
  # More request configurations...

    The external JavaScript script file getFeature.js defines a handler function to process incoming requests and generate appropriate responses.

Installing NPM-Based Packages

If your JavaScript-based dynamic requests require NPM-based packages, follow these steps:

Specify the required packages in the npmPackages section of your test definition. The testing framework will automatically install these packages before running your test.

Example Test Configuration:

version: v1
test:
  name: routeguide
  testPattern:
    - requestName: GetFeature_18GO
      startAt: 1
    - requestName: ListFeatures_5P9V
      startAt: 1
    - requestName: RecordRoute_MD5D
      startAt: 1
    - requestName: RouteChat_QQEf
      startAt: 1
  npmPackages:
    - mathjs
    - chart

Python Dynamic Requests

Note: If your dynamic Python request is dependent on additional Python modules, refer to the Installing Worker with Python Modules section to learn how to build the custom Skyramp Worker image.

  1. Using the python Attribute

    You can use the python attribute within the requestValue section of your request definition. This attribute allows you to define a function called handler that takes the req parameter, representing the incoming request. Within the handler function, you can implement your custom Python logic. Finally, return a JSON representation of the response value using SkyrampValue.

    Example Scenario Configuration:

    version: v1
requests:
  - name: GetFeature_18GO
    python: |-
      def handler(req):
        // Your Python logic here
        return SkyrampValue(
          value={
            "latitude": x,
            "longitude": y
          }
        )      
    endpointName: routeguide_jMBp
    methodName: GetFeature
  # More request configurations...

  2. Using the pythonPath Attribute

    Alternatively, you can use the pythonPath attribute to specify the path to an external Python script file containing your custom request handling logic.

    Example Scenario Configuration:

    version: v1
requests:
  - name: GetFeature_18GO
    pythonPath: scripts/get_feature.py
    endpointName: routeguide_jMBp
    methodName: GetFeature
  # More request configurations...

    The external Python script file get_feature.py defines a handler function to process the request and generate the response.

Chaining and Overrides

Tester provides a powerful feature that allows you to chain values between sequential requests and override them.

Example Test Configuration:

version: v1
test:
  name: routeguide
  testPattern:
    - startAt: 1
      scenarioName: scenario1
  override:
    mock:
      - endpointName: routeguide_jMBp
        methodName: RouteChat
        javascript: |-
          function handler(req) {
            return {
              value: {
                message: req.value.message + "temp",
                location: {
                  latitude: req.value.latitude,
                  longitude: req.value.longitude
                }
              }
            }
          }

Example Scenario Configuration:

version: v1
scenarios:
  - name: scenario1
    steps:
      - requestName: RouteChat_QQEf
      - asserts: requests.RouteChat_QQEf.res.message == "message1temp"
      - requestName: RouteChat_QQEf
        override:
          message: requests.RouteChat_QQEf.res.message
      - asserts: requests.RouteChat_QQEf.res.message == "message1temp1temp"
      - requestName: RouteChat_QQEf
        override:
          message: requests.RouteChat_QQEf.res.message
      - asserts: requests.RouteChat_QQEf.res.message == "message1temp1temp1temp"

requests:
  - name: RouteChat_QQEf
    endpointName: routeguide_jMBp
    methodName: RouteChat
    vars:
      message: "message"
    javascript: |
      i = 0
      function handler() {
        i++
        return {
          value: {
            message: vars.message + i,
            location: {
              latitude: req.value.latitude,
              longitude: req.value.longitude
            }
          }
        }
      }      
  # More request configurations...

In this example:

  • The override attribute in the test section allows you to customize the behavior of an endpoint defined elsewhere in the project folder by specifying a mock.

  • Within the scenarios section, multiple steps are defined. Each step calls the RouteChat_QQEf request and includes an assert. What sets them apart is that in subsequent requestName calls, the message variable is overridden. The message variable takes on the value of the response returned by the request. This chaining is done multiple times to create a sequence of messages.

  • The requests attribute shows how the vars keyword is used to define a new variable called message in the RouteChat_QQEf request. This variable is utilized in the JavaScript snippet using vars.message. By overriding this variable in scenario1, you can modify the message content in the subsequent requests.

This feature allows you to create dynamic test scenarios where the output of one request influences the behavior of subsequent requests, making your testing more versatile and powerful.

Request Parameters and Headers

When making REST calls, requests often require headers, such as Basic Authentication information, and variables in the path. You can achieve this using the request object.

Example Scenario Configuration:

version: v1
requests:
  - name: addCartRequest
    endpointName: cart-service
    methodName: cart-service-post
    blob: |
      {
          "product_id": "OLJCESPC7Z",
          "quantity": 1
      }      
    headers:
      Authorization: "Basic YWxhZGRpbjpvcGVuc2VzYW1l"
    params:
      - name: user_id
        in: path
        value: abcde

In this example:

  1. Path Parameters: In the cart-service endpoint, if the path contains a path parameter (/cart/user_id/{user_id}), we can define a params attribute and set user_id to abcde. Importantly, because we set in to path, it’s treated as a path parameter. You can also set in to query to make it a REST query parameter.

  2. Headers: The headers attribute adds a header with the key Authorization and the value "Basic YWxhZGRpbjpvcGVuc2VzYW1l". It allows you to include headers in your requests, which is often required for authentication and other purposes.

Endpoint Configuration

The endpoint configuration file defines networking-level service details for an endpoint.

Example Endpoint Configuration:

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

For configuring the endpoint file, we have a few key attributes:

  • services: This section lists the services available in your project. In this example, there is one service named routeguide.

  • endpoints: Under the endpoints section, you define individual endpoints, specifying the available methods, the service definition path, and the service name. In the example, we have an endpoint named routeguide_jMBp for the RouteGuide service.

  • methods: Within each endpoint, you list the available methods. In this case, we have methods like GetFeature, ListFeatures, RecordRoute, and RouteChat. This helps specify the details of each method and how it should behave.

  • defined: Here, you specify the service definition file’s path and the service name. The service definition file (route_guide.proto) outlines the structure of the service and its methods.

By configuring endpoints, you define the available services and methods within your project, facilitating the testing of your distributed application. We recommend dynamically generating a test by providing service-level information.

7 - Reference

Skyramp reference documentation

Here you can browse the reference documentation for Skyramp client applications.

7.1 - Architecture

Learn about the high level architecture of Skyramp

Kubernetes Architecture

Kubernetes Architecture

There are three main components that form the core of Skyramp:

  1. Skyramp Library
  2. Skyramp Worker
  3. Skyramp Clients

Skyramp Library

Skyramp exposes all the key abstractions needed for distributed testing through the Skyramp Library on the client side. The Skyramp Library interacts with the Skyramp Worker deployed in-cluster to implement service mocking and testing, available as Mocker and Tester respectively.

In addition to Mocker and Tester, there is a separate client side abstraction exposed by the Library — Deployer. Deployer allows you to deploy a subset of your application given a Helm Chart.

For inner dev loop testing you can access the functionality of the library through our Clients. Alternatively, you can directly use the libraries in your CI pipelines to create custom testing solutions.

Skyramp Worker

The Skyramp Worker implements the core functionality of Mocker and Tester. It is deployed via Helm into your cluster. You can communicate with the Worker either directly via the Library or by using Skyramp Clients. The Worker provides several management features that are useful for testing and development including running and managing mocks, generating load for tests, managing and visualizing tests and more.

Skyramp Clients

Skyramp provides a Terminal client and a VSCode Extension for inner dev loop testing.

Terminal Client

The Terminal Client has a comprehensive list of CLI Commands you can use in ad-hoc testing. To install, visit the Install Client page.

VSCode Extension

The VSCode Extension is a visual way to interact with Skyramp right from your development environment. For more info, visit the VSCode Extension page.

Cluster Orchestration

Skyramp supports Kubernetes for orchestration as shown in the architecture diagram.

7.2 - CLI Commands

List of commands for the Skyramp terminal client

7.2.1 - skyramp

Command line tool to interact with Skyramp

skyramp

skyramp [flags]

Options

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters
  • completion - Generate the autocompletion script for the specified shell
  • dashboard - Manage dashboard
  • deployer - Manage target services
  • init - Create description template
  • logs - Retrieve debug, usage, and cluster create logs
  • mocker - Manage mocks
  • resolver - Manage DNS Resolver
  • tester - Manage tests
  • validate - Validate description
  • version - Show version
  • viz - (beta) Run terminal UI for Skyramp

7.2.2 - cluster

Manage Kubernetes clusters

skyramp cluster

skyramp cluster [flags]

Options

      --airgap   enable airgap mode (only supported for local clusters)

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • create - Create a new Kubernetes cluster
  • current - Show current cluster
  • ingress - Manage ingress
  • list - List registered clusters
  • register - Register kubeconfig of a pre-provisioned cluster
  • remove - Delete cluster
  • switch - Select current cluster

7.2.2.1 - create

Create a new Kubernetes cluster

skyramp cluster create

Create a new local cluster or register an existing Kubernetes cluster.

skyramp cluster create [flags]

Options

  -d, --dashboard     install dashboard
      --listen-any    Kind API server listens to any address, default is localhost
  -l, --local         local cluster
  -n, --name string   name of the cluster to be created

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters

7.2.2.2 - current

Show current cluster

skyramp cluster current

skyramp cluster current [flags]

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters

7.2.2.3 - ingress

Manage ingress

skyramp cluster ingress

skyramp cluster ingress [flags]

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters
  • down - Delete ingress
  • up - Create ingress

7.2.2.3.1 - down

Delete ingress

skyramp cluster ingress down

skyramp cluster ingress down [flags]

Options

  -c, --cluster string              cluster context for Skyramp
      --kubernetes-service string   Kubernetes service list separated by comma
  -n, --namespace string            valid Kubernetes namespace

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.2.3.2 - up

Create ingress

skyramp cluster ingress up

skyramp cluster ingress up [flags]

Options

  -c, --cluster string              cluster context for Skyramp
      --kubernetes-service string   Kubernetes service list separated by comma
  -n, --namespace string            valid Kubernetes namespace
      --protocol string             protocol to use for the ingress generation (one of [grpc rest thrift])

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.2.4 - list

List registered clusters

skyramp cluster list

skyramp cluster list [flags]

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters

7.2.2.5 - register

Register kubeconfig of a pre-provisioned cluster

skyramp cluster register

Register kubeconfig of a pre-provisioned cluster. Alternative to ‘skyramp config apply’.

skyramp cluster register <kubeconfig-file-path> [flags]

Options

      --context string    k8s context
  -d, --dashboard         install dashboard
      --install-ingress   deploy skyramp ingress controller
  -n, --name string       name of the cluster to be created

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters

7.2.2.6 - remove

Delete cluster

skyramp cluster remove

skyramp cluster remove [flags]

Options

  -l, --local         local cluster
  -n, --name string   name of the cluster to be removed

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters

7.2.2.7 - switch

Select current cluster

skyramp cluster switch

skyramp cluster switch <cluster name> [flags]

Options inherited from parent commands

      --airgap                enable airgap mode (only supported for local clusters)
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • cluster - Manage Kubernetes clusters

7.2.3 - completion

Generate the autocompletion script for the specified shell

skyramp completion

skyramp completion <shell> [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • off - Disable autocompletion for Skyramp
  • on - Enable autocompletion for Skyramp

7.2.3.1 - off

Disable autocompletion for Skyramp

skyramp completion off

skyramp completion off <shell> [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • completion - Generate the autocompletion script for the specified shell

7.2.3.2 - on

Enable autocompletion for Skyramp

skyramp completion on

skyramp completion on <shell> [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • completion - Generate the autocompletion script for the specified shell

7.2.4 - dashboard

Manage dashboard

skyramp dashboard

skyramp dashboard [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • down - Bring down dashboard
  • up - Bring up dashboard

7.2.4.1 - down

Bring down dashboard

skyramp dashboard down

skyramp dashboard down [flags]

Options

  -g, --grafana   force dashboard installation/update

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.4.2 - up

Bring up dashboard

skyramp dashboard up

Bring up dashboard (Skyramp by default)

skyramp dashboard up [flags]

Options

  -d, --docker    open the Skyramp dashboard deployed on Docker
  -f, --force     force dashboard installation/update
  -g, --grafana   bring up Grafana dashboard

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.5 - deployer

Manage target services

skyramp deployer

skyramp deployer [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • clean - Remove all Kubernetes resources deployed by Skyramp
  • coverage - Configures or retrieves coverage data
  • down - Tear down target services
  • generate - Generates configurations from an existing deployment
  • status - Show details for deployed targets
  • up - Bring up target services

7.2.5.1 - clean

Remove all Kubernetes resources deployed by Skyramp

skyramp deployer clean

Remove all Kubernetes resources deployed by Skyramp from a cluster. Note that this will not clean up the cluster(s) and infrastructure.

skyramp deployer clean [flags]

Options

  -c, --cluster string   cluster context for Skyramp

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.5.2 - coverage

Configures or retrieves coverage data

skyramp deployer coverage

skyramp deployer coverage [flags]

Options

  -n, --namespace string   Kubernetes namespace

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • deployer - Manage target services
  • collect - Retrieves coverage data
  • restart - Resets the collected coverage data

7.2.5.2.1 - collect

Retrieves coverage data

skyramp deployer coverage collect

skyramp deployer coverage collect [flags]

Options

      --api-schema strings         schema file(s) to use for the coverage data
      --code-coverage-out string   output directory for the code coverage data (default "/tmp/cover")
      --protocol string            protocol to use for the schema files (one of [rest]) (default "rest")

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • coverage - Configures or retrieves coverage data

7.2.5.2.2 - restart

Resets the collected coverage data

skyramp deployer coverage restart

skyramp deployer coverage restart <target-name> [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • coverage - Configures or retrieves coverage data

7.2.5.3 - down

Tear down target services

skyramp deployer down

skyramp deployer down <target name> [flags]

Options

  -c, --cluster string     cluster context for Skyramp
  -f, --force              force delete the target
  -n, --namespace string   Kubernetes namespace

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.5.4 - generate

Generates configurations from an existing deployment

skyramp deployer generate

skyramp deployer generate [flags]

Options

      --api-coverage      generate and pull API coverage data
      --code-coverage     generate and pull code coverage data
      --protocol string   protocol to use for the deployer configuration (one of [rest]) (default "rest")

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • deployer - Manage target services
  • kubernetes - Generates configurations from an existing deployment in Kubernetes

7.2.5.4.1 - kubernetes

Generates configurations from an existing deployment in Kubernetes

skyramp deployer generate kubernetes

skyramp deployer generate kubernetes [flags]

Options

      --kubeconfig string   path of the kubeconfig where 
      --namespace string    namespace where the application is deployed

Options inherited from parent commands

      --api-coverage          generate and pull API coverage data
      --code-coverage         generate and pull code coverage data
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
      --protocol string       protocol to use for the deployer configuration (one of [rest]) (default "rest")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • generate - Generates configurations from an existing deployment

7.2.5.5 - status

Show details for deployed targets

skyramp deployer status

skyramp deployer status [flags]

Options

  -c, --cluster string   cluster context for Skyramp

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.5.6 - up

Bring up target services

skyramp deployer up

skyramp deployer up <target name> [flags]

Options

  -c, --cluster string        cluster context for Skyramp
      --local-images          load local container images
  -n, --namespace string      Kubernetes namespace
      --skip-deploy-worker    
      --worker-image string   worker image URL

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.6 - init

Create description template

skyramp init

skyramp init [flags]

Options

  -f, --force   force create description

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • mock - Create mock description
  • project - Create folder structure for a new Skyramp project
  • target - Create target description
  • test - Create test description

7.2.6.1 - mock

Create mock description

skyramp init mock

skyramp init mock [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • init - Create description template
  • grpc - Create mock description for gRPC protocol
  • jsonrpc-http - Create mock description for JSON-RPC over HTTP protocol
  • jsonrpc-ws - Create mock description for JSON-RPC over WebSocket protocol
  • rest - Create mock description for REST protocol

7.2.6.1.1 - grpc

Create mock description for gRPC protocol

skyramp init mock grpc

skyramp init mock grpc <mock name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • mock - Create mock description

7.2.6.1.2 - jsonrpc-http

Create mock description for JSON-RPC over HTTP protocol

skyramp init mock jsonrpc-http

skyramp init mock jsonrpc-http <mock name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • mock - Create mock description

7.2.6.1.3 - jsonrpc-ws

Create mock description for JSON-RPC over WebSocket protocol

skyramp init mock jsonrpc-ws

skyramp init mock jsonrpc-ws <mock name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • mock - Create mock description

7.2.6.1.4 - rest

Create mock description for REST protocol

skyramp init mock rest

skyramp init mock rest <mock name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • mock - Create mock description

7.2.6.2 - project

Create folder structure for a new Skyramp project

skyramp init project

skyramp init project <project name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • init - Create description template

7.2.6.3 - target

Create target description

skyramp init target

skyramp init target <target name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • init - Create description template

7.2.6.4 - test

Create test description

skyramp init test

skyramp init test [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • init - Create description template
  • grpc - Create test description for gRPC protocol
  • jsonrpc-http - Create test description for JSON-RPC over HTTP protocol
  • jsonrpc-ws - Create test description for JSON-RPC over WebSocket protocol
  • rest - Create test description for REST protocol

7.2.6.4.1 - grpc

Create test description for gRPC protocol

skyramp init test grpc

skyramp init test grpc <test name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • test - Create test description

7.2.6.4.2 - jsonrpc-http

Create test description for JSON-RPC over HTTP protocol

skyramp init test jsonrpc-http

skyramp init test jsonrpc-http <test name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • test - Create test description

7.2.6.4.3 - jsonrpc-ws

Create test description for JSON-RPC over WebSocket protocol

skyramp init test jsonrpc-ws

skyramp init test jsonrpc-ws <test name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • test - Create test description

7.2.6.4.4 - rest

Create test description for REST protocol

skyramp init test rest

skyramp init test rest <test name> [flags]

Options inherited from parent commands

  -f, --force                 force create description
      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • test - Create test description

7.2.7 - logs

Retrieve debug, usage, and cluster create logs

skyramp logs

skyramp logs [flags]

Examples

  skyramp logs container-name -t target-name        # Get debug logs
  skyramp logs --cluster-create                     # Get cluster create logs

Options

  -c, --cluster string   cluster context for Skyramp
      --cluster-create   retrieve logs from cluster creation
  -f, --follow           stream logs
  -t, --target string    target which will contain the container

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp

7.2.8 - mocker

Manage mocks

skyramp mocker

skyramp mocker [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • apply - Update mock configurations to the running worker container
  • delete - Delete mock configurations from the running worker container
  • generate - Generate mock configurations
  • status - Show applied mocks on the running worker container

7.2.8.1 - apply

Update mock configurations to the running worker container

skyramp mocker apply

skyramp mocker apply <mock file> [flags]

Examples

  skyramp mocker apply -n namespace            # Apply mocks to the worker container running on Kubernetes
  skyramp mocker apply -a localhost:35142      # Apply mocks to the worker container running on Docker

Options

  -a, --address string     ip:port of Skyramp worker
  -c, --cluster string     cluster context for Skyramp
      --endpoint string    endpoint to use for mocking
      --method string      method to use for mocking (endpoint argument must be specified)
  -n, --namespace string   Kubernetes namespace where Skyramp worker resides
      --value string       response value to use for mocking (endpoint and method arguments must be specified)

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.8.2 - delete

Delete mock configurations from the running worker container

skyramp mocker delete

skyramp mocker delete [flags]

Examples

  skyramp mocker delete -a localhost:35142      # Delete mocks from the worker container running on Docker

Options

  -a, --address string     ip:port of Skyramp worker
  -c, --cluster string     cluster context for Skyramp
  -n, --namespace string   Kubernetes namespace where Skyramp worker resides

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.8.3 - generate

Generate mock configurations

skyramp mocker generate

skyramp mocker generate [flags]

Options

      --alias string             Kubernetes service / Docker alias name
      --api-schema string        path to API schema file, or URL (URL support for OpenAPI 3.x only)
  -g, --glyphs string            Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --language string          specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
      --openai                   (experimental) use OpenAI to generate mock values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-context string    (experimental) Optional, extra context to give OpenAI to augment the mock values
      --openai-model string      (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --port int                 port number for the service
      --sample-response string   path to API sample response file

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • mocker - Manage mocks
  • grpc - Generate mock configurations for gRPC protocol
  • jsonrpc-http - Generate mock configurations for JSON-RPC over HTTP protocol
  • jsonrpc-ws - Generate mock configurations for JSON-RPC over Websocket protocol
  • rest - Generate mock configurations for REST protocol
  • rest-protobuf - Generate mock configurations for REST protocol using protobuf

7.2.8.3.1 - grpc

Generate mock configurations for gRPC protocol

skyramp mocker generate grpc

skyramp mocker generate grpc [flags]

Examples

  skyramp mocker generate grpc --api-schema path/to/schema.proto --alias my-service --port 8080 --service ProductService

Options

      --service string   proto service to utilize

Options inherited from parent commands

      --alias string             Kubernetes service / Docker alias name
      --api-schema string        path to API schema file, or URL (URL support for OpenAPI 3.x only)
  -g, --glyphs string            Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure            enable insecure mode for interactions with Kubernetes clusters
      --language string          specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
      --openai                   (experimental) use OpenAI to generate mock values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-context string    (experimental) Optional, extra context to give OpenAI to augment the mock values
      --openai-model string      (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --port int                 port number for the service
  -p, --project-path string      path to Skyramp project folder (default ".")
      --sample-response string   path to API sample response file
  -v, --verbose count            verbose (-v or -vv)

SEE ALSO

  • generate - Generate mock configurations

7.2.8.3.2 - jsonrpc-http

Generate mock configurations for JSON-RPC over HTTP protocol

skyramp mocker generate jsonrpc-http

skyramp mocker generate jsonrpc-http [flags]

Examples

  skyramp mocker generate jsonrpc-http --sample-response path/to/sample-response.json --alias my-service --port 8080 --endpoint-path /api/v1 --method calculateSum

Options

      --endpoint-path string   the REST path that upgrades http to a websocket
      --method string          json-rpc method to utilize

Options inherited from parent commands

      --alias string             Kubernetes service / Docker alias name
      --api-schema string        path to API schema file, or URL (URL support for OpenAPI 3.x only)
  -g, --glyphs string            Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure            enable insecure mode for interactions with Kubernetes clusters
      --language string          specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
      --openai                   (experimental) use OpenAI to generate mock values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-context string    (experimental) Optional, extra context to give OpenAI to augment the mock values
      --openai-model string      (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --port int                 port number for the service
  -p, --project-path string      path to Skyramp project folder (default ".")
      --sample-response string   path to API sample response file
  -v, --verbose count            verbose (-v or -vv)

SEE ALSO

  • generate - Generate mock configurations

7.2.8.3.3 - jsonrpc-ws

Generate mock configurations for JSON-RPC over Websocket protocol

skyramp mocker generate jsonrpc-ws

skyramp mocker generate jsonrpc-ws [flags]

Examples

  skyramp mocker generate jsonrpc-ws --sample-response path/to/sample-response.json --alias my-service --port 8080 --endpoint-path /api/v1 --method calculateSum

Options

      --endpoint-path string   the REST path that upgrades http to a websocket
      --method string          json-rpc method to utilize

Options inherited from parent commands

      --alias string             Kubernetes service / Docker alias name
      --api-schema string        path to API schema file, or URL (URL support for OpenAPI 3.x only)
  -g, --glyphs string            Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure            enable insecure mode for interactions with Kubernetes clusters
      --language string          specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
      --openai                   (experimental) use OpenAI to generate mock values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-context string    (experimental) Optional, extra context to give OpenAI to augment the mock values
      --openai-model string      (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --port int                 port number for the service
  -p, --project-path string      path to Skyramp project folder (default ".")
      --sample-response string   path to API sample response file
  -v, --verbose count            verbose (-v or -vv)

SEE ALSO

  • generate - Generate mock configurations

7.2.8.3.4 - rest

Generate mock configurations for REST protocol

skyramp mocker generate rest

skyramp mocker generate rest [flags]

Examples

  skyramp mocker generate rest --api-schema https://example.com/api/v1/openapi.yaml --alias my-service --port 8080 --tag users --paths /api/v1/users
  skyramp mocker generate rest --sample-response path/to/sample-response.json --alias my-service --port 8080 --endpoint-path /api/v1

Options

      --endpoint-path string   the REST path that upgrades http to a websocket
      --path strings           REST path to filter on. Can be used multiple times to filter on multiple paths.
      --paths string           comma-separated list of REST paths to filter on (to be deprecated: use --path instead)
      --tag string             OpenAPI tag to filter on

Options inherited from parent commands

      --alias string             Kubernetes service / Docker alias name
      --api-schema string        path to API schema file, or URL (URL support for OpenAPI 3.x only)
  -g, --glyphs string            Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure            enable insecure mode for interactions with Kubernetes clusters
      --language string          specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
      --openai                   (experimental) use OpenAI to generate mock values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-context string    (experimental) Optional, extra context to give OpenAI to augment the mock values
      --openai-model string      (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --port int                 port number for the service
  -p, --project-path string      path to Skyramp project folder (default ".")
      --sample-response string   path to API sample response file
  -v, --verbose count            verbose (-v or -vv)

SEE ALSO

  • generate - Generate mock configurations

7.2.8.3.5 - rest-protobuf

Generate mock configurations for REST protocol using protobuf

skyramp mocker generate rest-protobuf

skyramp mocker generate rest-protobuf [flags]

Options

      --api-schemas strings           paths to API schema file
      --proto-path string             proto_path to use for parsing multiple protobuf files
      --protobuf-any stringToString   map of the location of a protobuf any type to the value to the type to replace the type (default [])
      --service string                proto service to utilize

Options inherited from parent commands

      --alias string             Kubernetes service / Docker alias name
      --api-schema string        path to API schema file, or URL (URL support for OpenAPI 3.x only)
  -g, --glyphs string            Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure            enable insecure mode for interactions with Kubernetes clusters
      --language string          specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
      --openai                   (experimental) use OpenAI to generate mock values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-context string    (experimental) Optional, extra context to give OpenAI to augment the mock values
      --openai-model string      (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --port int                 port number for the service
  -p, --project-path string      path to Skyramp project folder (default ".")
      --sample-response string   path to API sample response file
  -v, --verbose count            verbose (-v or -vv)

SEE ALSO

  • generate - Generate mock configurations

7.2.8.4 - status

Show applied mocks on the running worker container

skyramp mocker status

skyramp mocker status [flags]

Options

  -a, --address string     ip:port of Skyramp worker
  -c, --cluster string     cluster context for Skyramp
  -e, --endpoint string    endpoint name to filter on
  -n, --namespace string   Kubernetes namespace where Skyramp worker resides

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • mocker - Manage mocks
  • response - Display response values of applied mocks by method or ID

7.2.8.4.1 - response

Display response values of applied mocks by method or ID

skyramp mocker status response

skyramp mocker status response [flags]

Options

  -a, --address string     ip:port of Skyramp worker
  -c, --cluster string     cluster context for Skyramp
  -e, --endpoint string    endpoint name to filter on
  -i, --id string          ID from mocker status table to query response value
  -m, --method string      method name to query response value
  -n, --namespace string   Kubernetes namespace where Skyramp worker resides

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • status - Show applied mocks on the running worker container

7.2.9 - resolver

Manage DNS Resolver

skyramp resolver

skyramp resolver [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • add - Add wildcard domain to Resolver
  • remove - Remove wildcard domain from Resolver
  • start - Start Resolver
  • status - Status of wildcard domains configured for Resolver
  • stop - Stop Resolver

7.2.9.1 - add

Add wildcard domain to Resolver

skyramp resolver add

skyramp resolver add [flags]

Options

      --domain string   domain
      --ip string       ip

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.9.2 - remove

Remove wildcard domain from Resolver

skyramp resolver remove

skyramp resolver remove [flags]

Options

      --domain string   domain

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.9.3 - start

Start Resolver

skyramp resolver start

skyramp resolver start [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.9.4 - status

Status of wildcard domains configured for Resolver

skyramp resolver status

skyramp resolver status [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.9.5 - stop

Stop Resolver

skyramp resolver stop

skyramp resolver stop [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.10 - tester

Manage tests

skyramp tester

skyramp tester [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • curl - Execute a single http request in the running worker container
  • generate - Generate test configurations
  • start - Starts a test description in the running worker container
  • status - Shows all tests in progress in the running worker container
  • stop - Stops a test description in the running worker container

7.2.10.1 - curl

Execute a single http request in the running worker container

skyramp tester curl

skyramp tester curl <request file> [flags]

Options

  -a, --address string     ip:port of Skyramp worker
      --data string        request payload for curl execution
  -n, --namespace string   Kubernetes namespace where Skyramp worker resides

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.10.2 - generate

Generate test configurations

skyramp tester generate

skyramp tester generate [flags]

Examples

  skyramp tester generate --cluster-id cluster-id --namespace namespace --start-time "-5m" --telemetry-provider pixie
  skyramp tester generate --trace-file trace-file.json

Options

      --address string              destination address of tests
      --alias string                Kubernetes service / Docker alias name
      --api-schema string           path to API schema file, or URL (URL support for OpenAPI 3.x only)
      --cluster-id string           cluster id from telemetry provider
  -f, --force                       force create test configurations and overwrite existing files
  -g, --glyphs string               Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --language string             specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
  -n, --namespace string            Kubernetes namespace where Skyramp worker resides
      --openai                      (experimental) use OpenAI to generate test values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-model string         (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --output-prefix string        prefix for generated files
      --port int                    port number for the service
      --start-time string           start time to retrieve traces from
      --telemetry-provider string   telemetry provider, currently only pixie is supported
      --trace-file string           trace file path

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • tester - Manage tests
  • graphql - Generate test configurations for Graphql protocol
  • grpc - Generate test configurations for gRPC protocol
  • rest - Generate test configurations for REST protocol
  • rest-protobuf - Generate test configurations for REST protocol with a Protobuf schema definition

7.2.10.2.1 - graphql

Generate test configurations for Graphql protocol

skyramp tester generate graphql

skyramp tester generate graphql [flags]

Options

      --graphql-url-path string   graphql http url path
      --graphql-ws-path string    graphql ws url path

Options inherited from parent commands

      --address string              destination address of tests
      --alias string                Kubernetes service / Docker alias name
      --api-schema string           path to API schema file, or URL (URL support for OpenAPI 3.x only)
      --cluster-id string           cluster id from telemetry provider
  -f, --force                       force create test configurations and overwrite existing files
  -g, --glyphs string               Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure               enable insecure mode for interactions with Kubernetes clusters
      --language string             specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
  -n, --namespace string            Kubernetes namespace where Skyramp worker resides
      --openai                      (experimental) use OpenAI to generate test values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-model string         (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --output-prefix string        prefix for generated files
      --port int                    port number for the service
  -p, --project-path string         path to Skyramp project folder (default ".")
      --start-time string           start time to retrieve traces from
      --telemetry-provider string   telemetry provider, currently only pixie is supported
      --trace-file string           trace file path
  -v, --verbose count               verbose (-v or -vv)

SEE ALSO

  • generate - Generate test configurations

7.2.10.2.2 - grpc

Generate test configurations for gRPC protocol

skyramp tester generate grpc

skyramp tester generate grpc [flags]

Examples

  skyramp tester generate grpc --api-schema path/to/your.proto --alias my-service --port 8080 --service ProductService

Options

      --service string   proto service to utilize

Options inherited from parent commands

      --address string              destination address of tests
      --alias string                Kubernetes service / Docker alias name
      --api-schema string           path to API schema file, or URL (URL support for OpenAPI 3.x only)
      --cluster-id string           cluster id from telemetry provider
  -f, --force                       force create test configurations and overwrite existing files
  -g, --glyphs string               Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure               enable insecure mode for interactions with Kubernetes clusters
      --language string             specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
  -n, --namespace string            Kubernetes namespace where Skyramp worker resides
      --openai                      (experimental) use OpenAI to generate test values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-model string         (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --output-prefix string        prefix for generated files
      --port int                    port number for the service
  -p, --project-path string         path to Skyramp project folder (default ".")
      --start-time string           start time to retrieve traces from
      --telemetry-provider string   telemetry provider, currently only pixie is supported
      --trace-file string           trace file path
  -v, --verbose count               verbose (-v or -vv)

SEE ALSO

  • generate - Generate test configurations

7.2.10.2.3 - rest

Generate test configurations for REST protocol

skyramp tester generate rest

skyramp tester generate rest [flags]

Examples

  skyramp tester generate rest --api-schema https://example.com/api/v1/openapi.yaml --alias my-service --port 8080 --tag users --paths /users

Options

      --endpoint-path string         the REST path that upgrades http to a websocket
      --negative-scenarios           generate negative test scenarios for REST endpoints (default true)
      --no-functional-scenarios      disable generating functional scenarios for REST endpoints
      --no-negative-scenarios        disable generating negative test scenarios for REST endpoints
      --path strings                 REST path to filter on. Can be used multiple times to filter on multiple paths.
      --paths string                 comma-separated list of REST paths to filter on (to be deprecated: use --path instead)
      --robot                        generate robot tests
      --sample-form-param strings    sample form parameter for REST endpoints in key=value format
      --sample-query-param strings   sample query parameter for REST endpoints in key=value format
      --sample-request string        path to API sample request file
      --tag string                   OpenAPI tag to filter on

Options inherited from parent commands

      --address string              destination address of tests
      --alias string                Kubernetes service / Docker alias name
      --api-schema string           path to API schema file, or URL (URL support for OpenAPI 3.x only)
      --cluster-id string           cluster id from telemetry provider
  -f, --force                       force create test configurations and overwrite existing files
  -g, --glyphs string               Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure               enable insecure mode for interactions with Kubernetes clusters
      --language string             specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
  -n, --namespace string            Kubernetes namespace where Skyramp worker resides
      --openai                      (experimental) use OpenAI to generate test values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-model string         (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --output-prefix string        prefix for generated files
      --port int                    port number for the service
  -p, --project-path string         path to Skyramp project folder (default ".")
      --start-time string           start time to retrieve traces from
      --telemetry-provider string   telemetry provider, currently only pixie is supported
      --trace-file string           trace file path
  -v, --verbose count               verbose (-v or -vv)

SEE ALSO

  • generate - Generate test configurations

7.2.10.2.4 - rest-protobuf

Generate test configurations for REST protocol with a Protobuf schema definition

skyramp tester generate rest-protobuf

skyramp tester generate rest-protobuf [flags]

Options

      --api-schemas strings           paths to API schema file
      --proto-path string             proto_path to use for parsing multiple protobuf files
      --protobuf-any stringToString   map of the location of a protobuf any type to the value to the type to replace the type (default [])
      --service string                proto service to utilize

Options inherited from parent commands

      --address string              destination address of tests
      --alias string                Kubernetes service / Docker alias name
      --api-schema string           path to API schema file, or URL (URL support for OpenAPI 3.x only)
      --cluster-id string           cluster id from telemetry provider
  -f, --force                       force create test configurations and overwrite existing files
  -g, --glyphs string               Specify the glyph combination to use: "1,2,3" - 1.Chinese 2.Cedilla 3.Emoji 4.Korean 5.German 6.French 7.Spanish 8.Russian 9.Control Char
      --kube-insecure               enable insecure mode for interactions with Kubernetes clusters
      --language string             specify output language for Skyramp library code generation. Accepted values: "python" (default "YAML")
  -n, --namespace string            Kubernetes namespace where Skyramp worker resides
      --openai                      (experimental) use OpenAI to generate test values (the 'OPENAI_API_KEY' environment variable must be set with an OpenAI API token)
      --openai-model string         (experimental) Optional, GPT model to use for OpenAI (one of [gpt-3.5-turbo gpt-4]). Note that some models may not accessible based on the API token (default "gpt-3.5-turbo")
      --output-prefix string        prefix for generated files
      --port int                    port number for the service
  -p, --project-path string         path to Skyramp project folder (default ".")
      --start-time string           start time to retrieve traces from
      --telemetry-provider string   telemetry provider, currently only pixie is supported
      --trace-file string           trace file path
  -v, --verbose count               verbose (-v or -vv)

SEE ALSO

  • generate - Generate test configurations

7.2.10.3 - start

Starts a test description in the running worker container

skyramp tester start

skyramp tester start <test description> [flags]

Examples

  skyramp tester start mytest -n my-namespace         # Start a test in the worker container running on Kubernetes
  skyramp tester start mytest -a localhost:35142      # Start a test in the worker container running on Docker

Options

  -a, --address string         ip:port of Skyramp worker
      --at-once int            set number of threads for load test, default is 1
  -c, --cluster string         cluster context for Skyramp
      --duration string        set duration for load test (e.g., 1s, 1m, 1h)
  -f, --fail                   return non zero for failed tests
      --html-report            generate an HTML test report in the "results" directory
      --local-images           load local container images
  -n, --namespace string       Kubernetes namespace where Skyramp worker resides
      --override strings       override values for skyramp objects
      --override-file string   override value file path for skyramp objects
      --set strings            set values for globalVars
      --stdout                 print results to stdout
      --truncate               truncate responses in terminal logging
      --worker-image string    worker image URL

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.10.4 - status

Shows all tests in progress in the running worker container

skyramp tester status

skyramp tester status <test description> [flags]

Options

  -a, --address string     ip:port of Skyramp worker
  -c, --cluster string     cluster context for Skyramp
      --id string          tester id
  -n, --namespace string   Kubernetes namespace where Skyramp worker resides

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.10.5 - stop

Stops a test description in the running worker container

skyramp tester stop

skyramp tester stop <test description> [flags]

Options

  -a, --address string     ip:port of Skyramp worker
  -c, --cluster string     cluster context for Skyramp
      --id string          tester id
  -n, --namespace string   Kubernetes namespace where Skyramp worker resides

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.11 - validate

Validate description

skyramp validate

skyramp validate [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp
  • mock - Validate mock description
  • target - Validate target description
  • test - Validate test description

7.2.11.1 - mock

Validate mock description

skyramp validate mock

skyramp validate mock <mock name> [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.11.2 - target

Validate target description

skyramp validate target

skyramp validate target <target name> [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.11.3 - test

Validate test description

skyramp validate test

skyramp validate test <test name> [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

7.2.12 - version

Show version

skyramp version

skyramp version [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp

7.2.13 - viz

(beta) Run terminal UI for Skyramp

skyramp viz

skyramp viz [flags]

Options inherited from parent commands

      --kube-insecure         enable insecure mode for interactions with Kubernetes clusters
  -p, --project-path string   path to Skyramp project folder (default ".")
  -v, --verbose count         verbose (-v or -vv)

SEE ALSO

  • skyramp - Command line tool to interact with Skyramp

7.3 - Dashboard

Manage Test Results and Mocks with Skyramp Dashboard

Welcome to the Skyramp Dashboard documentation. This guide will walk you through deploying and utilizing the Skyramp Dashboard on your Kubernetes cluster, allowing you to efficiently manage test results, mocks, and maintain records of your test runs.

Prerequisites

Before you begin, ensure your Kubernetes cluster is registered with Skyramp. If it isn’t, you can configure it using either the skyramp cluster create or skyramp cluster register commands. Verify your cluster configuration by running:

skyramp cluster current

Bringing Up the Dashboard

To bring up the Skyramp Dashboard for Kubernetes deployments, execute the following command:

skyramp dashboard up

This command automates the deployment process, creating essential Kubernetes assets (client, server, and MongoDB Kubernetes Operator) within the skyramp namespace of your cluster. It also initiates port forwarding for local access. Once the dashboard is live, the terminal client will provide the forwarding address:

...
The dashboard is accessible here: http://localhost:53430/testresults
Port forwarding is started for the dashboard, hit Ctrl+c (or Cmd+c) to stop

No manual opening of this address in your browser is required; it should be done automatically.

All the flags available for skyramp dashboard can be found on the CLI Commands page.

Viewing the Dashboard

Running skyramp dashboard up will open the dashboard in a new browser tab. If you’re starting fresh without previous test runs, you’ll see an empty test result page:

Analyzing Test Results

Once your dashboard is running, you can use Tester to execute tests in-cluster and view the results automatically on the dashboard. For example, if you start the Checkout system testcase and a Checkout system load test testcase, they will then appear in the Test Results section of the dashboard:

From the Test Results page of the dashboard, you can click through to the Checkout system testcase to see the functional test results, including output, errors, duration, and status:

Navigate to the Checkout system load test testcase to view the load test results:

You can scroll down and view various load-related outputs and graphs related to latency, error rate, requests per second (RPS), and pod-specific utilization. Dashboard test results are valuable for retaining test run history and sharing among team members on a shared cluster.

Tracking Active Mocks

Once your dashboard is running, you can use Mocker to apply mocks in-cluster and track active mocks. For example, if you mock the payment-service with skyramp mocker apply, you can view active mocks and responses in the Mocked Services section:

This is particularly useful when managing multiple mocks across teams on a shared cluster and keeping track of the payloads for each endpoint.

Bringing Down the Dashboard

To stop the dashboard and clean up Kubernetes manifests, run the following command:

skyramp dashboard down

You are now ready to efficiently manage your testing environment with the Skyramp Dashboard!

7.4 - Libraries

Learn about the supported Skyramp libraries

Python

How to install the Skyramp Python library:

pip install skyramp

Visit the PyPI module page for more info.

JavaScript

How to install the Skyramp JavaScript library:

npm install skyramp

Visit the NPM module page for more info.

7.5 - Resolver

Manage DNS resolution to your Kubernetes clusters

Skyramp runs a Dnsmasq container, called Resolver, on the local machine to resolve addresses under the skyramp.test domain. Resolver can also be used to configure access to other kubernetes clusters not managed by Skyramp.

Resolver uses port mapping 5553:53 on MAC and 53:53 on WSL (Windows Subsystem for Linux), and is automatically started when new domain configurations are added.

Before you begin

Resolver commands can be triggered via the Skyramp binary. Follow instructions here to install Skyramp.

Resolver works out of the box on Linux, macOS, and WSL (Windows Subsystem for Linux). To use it on Windows, follow the additional configuration steps.

Start Resolver

Skyramp automatically starts Resolver in two cases:

  1. when a cluster is brought up by Skyramp.
  2. when a new configuration is added to Resolver via the config add command.

To force start Resolver, you can run the following command:

skyramp resolver start

Add domain

As noted earlier, the skyramp.test domain is automatically added to Resolver for clusters brought up by Skyramp. To add a new domain, run the following command:

skyramp resolver config add --domain <domain> --ip <ip>

Based on the Operating System you are on, Skyramp makes the appropriate configurations as follows:

MAC : A new domain configuration is created in the /etc/resolver directory for each configured domain.

Linux (Ubuntu): Skyramp updates the configuration file at /etc/systemd/resolved.conf with the IP of the resolver container and restarts the systemd-resolved service.

Windows: Skyramp updates the configuration file at /etc/resolv.conf with the Resolver container as the first nameserver.

View configuration

You can view all DNS resolutions configured by Resolver by running:

skyramp resolver config show

Verify configuration

Test the configuration by performing a ping to any configured domain.

  ping  -c 1 <domain>

Example result:

  PING <domain> (127.0.0.1): 56 data bytes
  64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.033 ms

  --- <domain> ping statistics ---
  1 packets transmitted, 1 packets received, 0.0% packet loss
  round-trip min/avg/max/stddev = 0.033/0.033/0.033/0.000 ms

Remove domain

List configured domains for the skyramp resolver by running:

skyramp resolver config remove --domain <domain>

Stop Resolver

You can stop Resolver at any time by running the stop command.

skyramp resolver stop

Windows Configuration

While Resolver works out of the box on WSL, additional configuration is needed to use it on Windows.

  1. Download Resolver on WSL by following the documentation for installing Skyramp.
  2. Download and install Docker Desktop.
  3. Ensure that Resolver is not running in WSL: skyramp resolver stop.
  4. On Windows, open Settings and select Network & internet to view current DNS server configuration.
  5. Edit DNS Server Assignment, and select Manual DNS settings.
  6. Set Preferred DNS value to 127.0.0.1 and Alternate DNS to the primary DNS server as listed in step 2.

    Windows Settings

All Resolver specific commands can be run inside WSL now.

7.6 - VSCode Extension

Learn about the Skyramp VSCode Extension

Easily isolate your services from surrounding dependencies and write and run integration and performance tests as you develop and debug, directly in VSCode. Visit the VSCode extension marketplace to download and install the extension.

Getting Started

1. Set Up a Kubernetes Cluster

First, run the Set Up Cluster command to configure a Kubernetes cluster to use with Mocker and Tester. Set Up Cluster

Note: Please be aware that provisioning a local cluster is supported only on MacOS or Linux. On Windows, you can only connect to an existing cluster.

2. Deploy New Worker Container

Next, install the Worker container in your cluster by running the Deploy New Worker Container command. Deploy New Worker Container

Mocker

How Mocker works

Mocker is an in-cluster solution for creating API mock servers. Refer to the Mocker page to learn more about how Mocker works. You can follow the following steps to use Mocker in the VS code extension:

1. Generate Mock

When you’re ready to mock a service, run the Generate Mock command to generate a mock configuration in the form of a .yaml file in the mocks folder of your working directory. You will be prompted to select an API schema file to mock against, and input some necessary configuration details including the Kubernetes service name, port number, and proto service name (if applicable). Generate Mock

Tip: We recommend running the generate command in your source code repo so mocks are versioned and shareable across your team.

2. Edit Mock

Mocker generates default values for responses based on the API signature. You can edit the default values by editing the generated mock in the mocks folder. Edit Mock

Note: Read more about writing mock configurations here

3. Apply Mock

Now, you can push the mock configuration to Mocker by running the Apply Mocks command: Apply Mock That’s it! All calls to the mocked service/s are now routed to Mocker and it responds with the default values in the configuration.

Note: Mocker does not automatically update the mocks when the responses are updated in the mock configuration file. You can run the Apply Mocks command again when your mock values change. Note: When mocking a gRPC service the container needs to be redeployed if the proto definition of the mock changes.

Tester

How Tester works

Tester is a solution that simplifies the process of both writing and running tests for complicated distributed apps. Refer to the Tester page to learn more about how Tester works. You can follow the following steps to use Tester in the VS code extension:

1. Generate Test

When you’re ready to test a service, run the Generate Test command to generate a test configuration in the form of a .yaml file in the tests folder of your working directory. You will be prompted to select an API schema file to test against, and input some necessary configuration details including the test name, Kubernetes service name, port number, and proto service name (if applicable). Generate Test

2. Edit Test

Tester generates default values for requests based on the API signature. You can edit the default values and add request steps by editing the generated test in the tests folder. Edit Test

Note: Read more about Tester and writing test configurations here

3. Start Test

Now, you can start the test configurations by running the Start Test command: Start Test That’s it! Tester will execute the test and output on the test results in the results output directory.

Requirements

Helm

The Worker container is installed in your cluster via Helm. In case you don’t have Helm installed, refer to Helm’s documentation to get started.