@skyramp/skyramp

skyramp

skyramp is an npm module that provides utility functions for leveraging skyramp CLI commands. The skyramp module provides functionalities to create and apply mock configurations for both gRPC and REST APIs. It also offers features for testing and asserting scenarios in various test environments. The module exports the following classes: RestEndpoint, GrpcEndpoint, Scenario, and SkyrampClient.

Installation

To install Skyramp, simply run the following command in your terminal:

npm install @skyramp/skyramp

Usage

Once you've installed Skyramp, you can import it into your project like this:

// Import necessary modules from skyramp
const { GrpcEndpoint, RestEndpoint, SkyrampClient, Scenario } = require('skyramp');

SkyrampClient

The SkyrampClient class is the main entry point to interact with the skyramp module. It allows you to apply configurations, start test scenarios, and deploy and delete workers. You have the option of configuring the SkyrampClient to be used either in the Kubernetes setting (by deploying a local cluster or connecting to an existing cluster) and deploying the Skyramp worker.

Kubernetes Configuration

First, you must set up the SkyrampClient with a Kubernetes cluster.

Example: Provision Local Cluster with Skyramp

// Create a SkyrampClient instance
const skyrampClient = new SkyrampClient();

// Apply a local Kubernetes cluster
skyrampClient.applyLocal().then(() => {
  // Local cluster provisioned
}).catch((error) => {
  // Error occurred during provisioning
});

Once you have a SkyrampClient instance configured with a Kubernetes cluster, you can deploy the Skyramp Worker in-cluster, for applying mocks and running tests.

Example: Deploy Skyramp Worker

// Deploy Skyramp Worker in-cluster
skyrampClient.deploySkyrampWorker('my-namespace').then(() => {
  // Worker deployed successfully
}).catch((error) => {
  // Error occurred during deployment
});

Docker Configuration

For the Docker setting, you can bring up a SkyrampClient instance and deploy the Skyramp Worker in the network of your choice, for applying mocks and running tests.

Example: Run Skyramp Worker in Docker Network

// Create a SkyrampClient instance
const skyrampClient = new SkyrampClient();

// Run Skyramp Worker in Docker network
skyrampClient.runDockerSkyrampWorker().then(() => {
  // Worker run successfully
}).catch((error) => {
  // Error occurred during worker bring-up
});

Mocking

To configure mock responses to apply them to the SkyrampClient, you must first create an Endpoint object (currently supported: GrpcEndpoint and RestEndpoint) and configure a ResponseValue for the method you wish to mock and passing through a dynamic javascriptFunction (a handler function) or a JSON blob.

Here is an example flow of creating a REST Mock Configuration from a RestEndpoint object:

Example: Create REST Mock Configuration

// Define endpoint options
const endpointOptions = {
  serviceName: 'payment-service',
  port: 8080,
  restPath: '/payment',
  methodTypes: ['POST'], 
};

// Create a RestEndpoint instance
const restEndpoint = new RestEndpoint(endpointOptions);

// Define JSON blob for mock response
const jsonBlob = '{"transaction_id": "default-value"}';

// Create a ResponseValue for the mock
const paymentResponse = new ResponseValue({
  name: 'payment', 
  endpoint: restEndpoint, 
  methodType: 'POST',
  blob: jsonBlob
});

// Create a traffic configuration
trafficConfig = new TrafficConfig(100, new DelayConfig(9000, 10000));

// Apply the mock with the response and traffic configuration
skyrampClient.mockerApplyV1('my-namespace', '', paymentResponse, trafficConfig).then(() => {
  // Mock applied successfully
}).catch((error) => {
  // Error occurred during mock application
});

Here is an example flow of creating a gRPC Mock Configuration from a GrpcEndpoint object:

Example: Create gRPC Mock Configuration

// Create a GrpcEndpoint instance
const grpcEndpoint = new GrpcEndpoint('helloworld', 'Greeter', 50052, 'pb/helloworld.proto');

// Define mock handler js function 
function handler(req) {
  return {
    value: {
      name: 'mock'
    }
  };
}

// Create a ResponseValue for the mock
const helloResponse = new ResponseValue({
  name: 'SayHello', 
  endpoint: grpcEndpoint, 
  methodName: 'SayHello', 
  javascriptFunction: handler.toString()
});

// Create a traffic configuration
trafficConfig = new TrafficConfig(100, new DelayConfig(9000, 10000));

// Apply the mock with the response and traffic configuration
skyrampClient.mockerApplyV1('my-namespace', '', helloResponse, trafficConfig).then(() => {
  // Mock applied successfully
}).catch((error) => {
  // Error occurred during mock application
});

Testing

To configure test requests to apply them to the SkyrampClient, you must first create an Endpoint object (currently supported: GrpcEndpoint and RestEndpoint) and configure Scenario built from AssertEquals and RequestValues for the method you wish to test and passing through a dynamic javascriptFunction (a handler function) or a JSON blob.

Here is an example flow of creating a REST Mock Configuration from a RestEndpoint object:

Example: Test Assert Scenario (REST)

// Define a REST parameter
const param = new RestParam('echo', 'path', 'string', 'echo_param');

// Define a REST request
const request = new RequestValue({
  name: 'echo-post', 
  endpoint: echoEndpoint, 
  methodType: 'POST', 
  params: [param],
  blob: '{ "v": "echo test" }'
});

// Create a Scenario for testing
const scenario = new Scenario('payment-assert-test');

// Add the REST request to the scenario
const step1 = scenario.addRequestV1(request);

// Define global headers
const globalHeaders = {'Authorization': 'Bearer 1234567890'};

// Start the test scenario
skyrampClient.testerStartV1('my-namespace', '', scenario, 'test', globalHeaders ).then(() => {
  // Test scenario started
}).catch((error) => {
  // Error occurred during the test scenario
});

Example: Test Assert Scenario (gRPC)

// Define handler for gRPC mock response
function handler(req) {
  return {
    value: {
      name: 'name'
    }
  };
}

// Define gRPC request value
const grpcRequest = new RequestValue({
  name: 'SayHello', 
  endpoint: dynamicGrpcEndpoint, 
  methodName: 'SayHello', 
  javascriptFunction: handler.toString()
});

// Create a Scenario for gRPC testing
const grpcScenario = new Scenario('routeguide-assert-test');

// Add the gRPC request to the scenario
const step1 = grpcScenario.addRequestV1(grpcRequest);

// Add an assertion to the scenario
const step2 = grpcScenario.addAssertEqual(`${step1}.res.message`, 'mock');

// Define global headers for gRPC testing
const grpcGlobalHeaders = {'Authorization': 'Bearer 1234567890'};

// Start the gRPC test scenario
skyrampClient.testerStartV1('my-namespace', '', grpcScenario, 'test', grpcGlobalHeaders ).then(() => {
  // Test scenario started
}).catch((error) => {
  // Error occurred during the test scenario
});

Reference

Table of Contents

• DelayConfig
  • Parameters
• Endpoint
  • Parameters
• GrpcEndpoint
  • Parameters
• RequestValueOptions
  • Properties
• RequestValue
  • Parameters
• ResponseValueOptions
  • Properties
• ResponseValue
  • Parameters
• RestEndpoint
  • Parameters
• RestParam
  • Parameters
• Scenario
  • Parameters
  • addRequestV1
    • Parameters
  • addAssertEqual
    • Parameters
• SkyrampClient
  • applyLocal
  • addKubeConfig
    • Parameters
  • removeLocal
  • removeCluster
    • Parameters
  • deploySkyrampWorker
    • Parameters
  • deleteSkyrampWorker
    • Parameters
  • runDockerSkyrampWorker
    • Parameters
  • removeDockerSkyrampWorker
    • Parameters
  • mockerApplyV1
    • Parameters
  • testerStartV1
    • Parameters
• TrafficConfig
  • Parameters

DelayConfig

The DelayConfig class represents a configuration for delay values.

Parameters

• minDelay number The minimum delay value.
• maxDelay number The maximum delay value.

Endpoint

The Endpoint class represents an endpoint object to manage endpoint data and generate mock configurations.

Parameters

• endpointData string The endpoint data in JSON format.
• endpointAddress string The address of the endpoint.

GrpcEndpoint

Extends Endpoint

The GrpcEndpoint class represents a gRPC API Endpoint.

Parameters

• name string The name of the endpoint.
• service string The name of the service.
• port number The port number.
• pbFile string The protocol buffer file containing the API schema definition.
• endpointAddress string The endpoint address.

RequestValueOptions

Type: Object

Properties

• name string The name of the request.
• endpoint Object The descriptor for the endpoint of the request.
• methodType string The type of HTTP method for the request.
• methodName string The name of the method for the request.
• params Object The parameters for the request.
• headers Object The headers for the request.
• vars Object The variables for the request.
• blob Object The blob data for the request.
• javascriptPath string The path to the JavaScript file for the request.
• javascriptFunction string The JavaScript function for the request.

RequestValue

The RequestValue class represents a request value to use for testing API endpoint methods.

Parameters

• options RequestValueOptions The options for initializing the RequestValue object.

ResponseValueOptions

Type: Object

Properties

• name string The name of the response value.
• endpoint Object The descriptor of the endpoint associated with the response.
• methodType string The type of the HTTP method used for the response.
• methodName string The name of the method used for the response.
• params Object The parameters of the response.
• headers Object The headers of the response.
• vars Object The variables of the response.
• blob string The blob data of the response.
• javascriptPath string The path to the JavaScript file associated with the response.
• javascriptFunction string The JavaScript function associated with the response.

ResponseValue

The ResponseValue class represents a response value to use for mocking API endpoint methods.

Parameters

• options ResponseValueOptions The options for initializing the ResponseValue object.

RestEndpoint

Extends Endpoint

The RestEndpoint class represents a REST API Endpoint.

Parameters

• args ...any The arguments to create the REST endpoint.

RestParam

The RestParam class represents a REST (query, path, etc) param.

Parameters

• name string The name of the parameter.
• in_ string The location of the parameter (e.g., 'query', 'header', 'path').
• type_ string The data type of the parameter.
• value any The value of the parameter.

Scenario

The Scenario class allows you to define test scenarios by adding requests and asserts.

Parameters

• name string The name of the scenario.

addRequestV1

Adds a request to the scenario and updates the list of services and endpoints.

Parameters

• request Request The request to add to the scenario.

Returns string The name of the added request.

addAssertEqual

Adds an assertion to the scenario that checks if the value of value1 is equal to value2.

Parameters

• value1 string The first value to compare.
• value2 string The second value to compare.

Returns string The assertion string.

SkyrampClient

The SkyrampClient class is the main client that provides methods for interacting with the Skyramp service. It allows users to manage Kubernetes clusters, deploy and delete workers and targets, apply mock descriptions, and start tests.

applyLocal

Applies local changes to the Kubernetes cluster configuration.

Returns Promise A promise that resolves when the local changes are successfully applied, or rejects with an error if any error occurs.

addKubeConfig

Adds a Kubernetes configuration to the SkyrampClient object.

Parameters

• context string The context of the Kubernetes configuration.
• clusterName string The name of the Kubernetes cluster.
• kubeConfigPath string The path to the kubeconfig file.

Returns Promise A Promise that resolves if the operation is successful or rejects with an error if an error occurs.

removeLocal

Removes the local configuration of the SkyrampClient.

Returns Promise<void> A promise that resolves when the removal is successful, or rejects with an error if an error occurs during the removal process.

removeCluster

Asynchronously removes a cluster from the configuration.

Parameters

• clusterName string The name of the cluster to be removed from the configuration.

Returns Promise A Promise that resolves if the cluster is successfully removed, or rejects with an error if the removal fails.

deploySkyrampWorker

Deploys a worker to a Kubernetes cluster.

Parameters

• namespace string The namespace where the worker will be deployed.
• workerImage string The image of the worker to be deployed. (optional, default '')
• localImage boolean Indicates whether the worker image is local or not. (optional, default false)

• Throws Error If there is no cluster to deploy the worker to.

Returns Promise A Promise that resolves if deployment is successful, and rejects with an error if any error occurs during deployment.

deleteSkyrampWorker

Deletes a worker from a specified namespace in the SkyrampClient class.

Parameters

• namespace string The namespace from which the worker should be deleted.

• Throws Error If there is no cluster to delete the worker from or if there is no worker to delete from the specified namespace.

Returns Promise A promise that resolves with no value upon successful deletion.

runDockerSkyrampWorker

Asynchronous method that runs a Docker worker using the provided image, tag, port, and network name.

Parameters

• workerImage string The URL of the Docker worker image. (optional, default WORKER_URL)
• workerTag string The tag of the Docker worker image. (optional, default WORKER_TAG)
• hostPost (optional, default CONTAINER_PORT)
• targetNetworkName string The name of the network to connect the Docker worker to. (optional, default "")
• hostPort number The port on the host machine to expose for the Docker worker. (optional, default CONTAINER_PORT)

Returns Promise A Promise that resolves if the Docker worker starts successfully and rejects if there is an error starting the worker.

removeDockerSkyrampWorker

Asynchronous method that removes a Docker container running the Skyramp worker.

Parameters

• containerName string The name of the Docker container to be removed.

• Throws Error If an error occurs during the removal process.
• Throws Error If a non-empty response is received.

Returns Promise A promise that resolves when the container is successfully removed.

mockerApplyV1

Applies a mock description to a specified namespace and address.

Parameters

• namespace string The namespace where the mock description will be applied.
• address string The address to which the mock description will be applied.
• response object The details of the mock response.
• trafficConfig object The traffic configuration parameters.

Returns Promise A Promise that resolves when the mock description is successfully applied.

testerStartV1

Starts a test scenario in a specified namespace.

Parameters

• namespace string The namespace in which to start the test scenario.
• address string The address of the target service to test.
• scenario object The scenario object that defines the test steps and assertions.
• testName string The name of the test.
• globalHeaders object Optional global headers to be included in the test requests.
• generateTestReport boolean Optional flag to generate a test report. Default is false. (optional, default false)
• isDockerenv boolean Optional flag to indicate if the test is running in a Docker environment. Default is false. (optional, default false)

Returns Promise A promise that resolves when the test scenario is started.

TrafficConfig

Represents a configuration for traffic values.

Parameters

• lossPercentage number The loss percentage for traffic configuration.
• delayConfig DelayConfig The delay configuration for traffic. It is an optional field and can be set using an instance of the DelayConfig class.