@skyramp/skyramp v0.4.83
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 AssertEqual
s and RequestValue
s 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
- Endpoint
- GrpcEndpoint
- RequestValueOptions
- RequestValue
- ResponseValueOptions
- ResponseValue
- RestEndpoint
- RestParam
- Scenario
- SkyrampClient
- TrafficConfig
DelayConfig
The DelayConfig
class represents a configuration for delay values.
Parameters
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
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\ 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, defaultfalse
)
- 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, defaultWORKER_URL
)workerTag
string The tag of the Docker worker image. (optional, defaultWORKER_TAG
)hostPost
(optional, defaultCONTAINER_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, defaultCONTAINER_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, defaultfalse
)isDockerenv
boolean Optional flag to indicate if the test is running in a Docker environment. Default is false. (optional, defaultfalse
)
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.
5 days ago
8 days ago
8 days ago
23 days ago
1 month ago
1 month ago
1 month ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
2 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
8 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago