Skip to main content


In the below sections, you will see how to use the Signadot Node.js SDK to programmatically create and manage sandboxes and how you can use them alongside a test framework such as Mocha to write integration tests that run with real dependencies on a Kubernetes cluster.

Working Example

For a full working code example covering all the concepts described below, see


For information on latest SDK version, installation information and other resources, visit the documentation for the Node SDK.


Create Sandbox

Assume a hypothetical Route service in the below example. This Route service is changed and an image corresponding to the new version has been built and pushed to the registry. You wish to run integration tests against that new untested version.

import { ApiClient, SandboxesApi } from '@signadot/signadot-sdk';

// initialize client
const apiClient = new ApiClient();
apiClient.authentications.ApiKeyAuth.apiKey = SIGNADOT_API_KEY;

// A particular service that we want to fork, starting from the specified
// Kubernetes workload of kind "Deployment" called "route" in namespace
// "hotrod". To fork an Argo Rollout, use kind "Rollout".
const routeFork = SandboxFork.constructFromObject({
forkOf: ForkOf.constructFromObject(
{ kind: 'Deployment', name: 'route', namespace: 'hotrod' }),

// customizations to be applied on the fork
customizations: SandboxCustomizations.constructFromObject({

// docker image that the fork should run
images: [
{ image: 'registry/docker-image:tag' })

// any env vars to add / modify
env: [
{ name: 'abc', value: 'def' })

// endpoints that we want to expose in order to run tests
endpoints: [
{ name: 'hotrod-route', port: 8083, protocol: 'http' })

const request = CreateSandboxRequest.constructFromObject({
name: 'test-sandbox',
description: 'route service test sandbox',
cluster: 'your-cluster',
forks: [ routeFork ]

// submitting the request to create sandbox via the API
const sandboxesApi = new SandboxesApi(apiClient);
const response = await sandboxesApi.createNewSandbox('org-name', request);

You specify one or more forks which are new versions of a particular Microservice. Each fork starts with a particular baseline Deployment running in the Kubernetes cluster and then can have one or more customizations applied to it.

The customizations that are currently supported are as follows:

  1. docker images
  2. environment variables

Finally, each fork may have one or more endpoints associated with it. Each of these endpoints will return a hosted preview URL used to run tests.

Retrieve Preview Endpoint

The final call above to createNewSandbox will create the sandbox within the cluster. You use the response and retrieve the specified preview URLs to run tests.

const sandboxID = response.sandboxID;
const endpoint = response.previewEndpoints.filter(ep => === 'hotrod-route')[0];
const previewUrl = endpoint.previewURL;

Wait for Readiness

Before running tests, you need to ensure that the service has come up within the cluster and is ready to take the requests. To do that, you check via the getSandboxReady method.

const readyStateInterval = setInterval(async () => {
const readyState = await sandboxesApi.getSandboxReady(SIGNADOT_ORG, sandboxID);
if (readyState.ready) {
}, 1000);

Run tests

Once the sandbox is ready, you can run tests on the forked service. An example test using Mocha, a popular framework for writing REST service integration tests is shown below.

it('Route service preview', () => {
const serviceURL = `${previewUrl}/route?pickup=123&dropoff=456`

axios.get(serviceURL, {
headers: {
'signadot-api-key': SIGNADOT_API_KEY
.then((response) => {

const data =;
['Pickup', 'Dropoff', 'ETA'].forEach(x => expect(data);
expect(data.ETA).isAbove(0); // ETA should be positive

Delete Sandbox

Once all the tests are executed and have passed, you can delete the sandbox. This will tear down any resources that were set up such a pods, deployments, services etc from the Kubernetes cluster.

sandboxesApi.deleteSandboxById('org-name', sandboxID);

Additional Resources