Get Started

• 1: Install Client
• 2: Install Worker
• 3: Tutorial

1 - Install 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)"

2 - Install Worker

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 Docker Compose installed, refer to Docker’s documentation to install it. Then, follow these two steps to run the Skyramp Worker using Docker Compose:

1. Add Docker Compose for Skyramp

Add the following to an existing docker-compose.yaml or create a new one with the following services and volumes necessary for updating the Docker network:

services:
  skyramp:
    image: public.ecr.aws/j1n2c2p2/rampup/worker:latest
    volumes:
      - skyramp:/etc/skyramp
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "35142:35142"
    restart: always
  # The services below (dashboard-server, dashboard-client, and mongodb)
  # can be included optionally for Skyramp Dashboard bring up
  dashboard-server:
    image: public.ecr.aws/j1n2c2p2/rampup/dashboard-server:latest
    environment:
      NODE_ENV: production
      DOCKER_ENV: true 
    ports:
      - "4000:4000"
    restart: always
  dashboard-client:
    image: public.ecr.aws/j1n2c2p2/rampup/dashboard-client:latest
    environment:
      NODE_ENV: production
    ports:
      - "3000:3000"
    restart: always
  mongodb:
    image: mongo:6.0.6
    container_name : mongo-datastore-svc
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: skyramp
      MONGO_INITDB_DATABASE: dashboarddb
    volumes:
      - mongodb:/data/db
    restart: always
volumes:
  mongodb:
  skyramp:

2. docker compose up

Deploy the Skyramp Worker by running the following:

docker compose up -d --wait

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 Docker Compose.

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 can update your docker-compose.yaml file to use the new custom image. Replace public.ecr.aws/j1n2c2p2/rampup/worker:latest with <image-name>:<image-tag> in the image field under the skyramp service:

services:
  skyramp:
    image: <image-name>:<image-tag>
    volumes:
      - skyramp:/etc/skyramp
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 35142:35142
    restart: always
volumes:
  skyramp:

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.

3 - Tutorial

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

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 Docker Compose to run a simple service that we can test.

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, create a file called compose.yaml in your project directory and paste the following contents using vi or your favorite text editor:

services:
  skyramp:
    image: public.ecr.aws/skyramp/rampup/worker:latest
    volumes:
      - skyramp:/etc/skyramp
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "35142:35142"
    restart: always
  echo:
    image: public.ecr.aws/skyramp/rampup/echo:latest
    ports:
      - "12346:12346"
volumes:
  skyramp:

This file is a Docker Compose file and contains 2 services: the Skyramp Worker and an echo service. The Skyramp Worker is responsible for running tests and applying mocks, as well as other duties. The echo service is a simple service that we will use for testing in this tutorial, and will ultimately be substituted by your own services you want to test.

3. After the file is saved, you can start up the application services by running docker compose up from the project directory.

docker compose up &

You should see output similar to the screenshot below:

4. Now, let’s open a second terminal window and navigate back to the project directory created above.

cd tutorial

5. We can check to see if the echo service is running properly by issuing a curl command. Run this in the terminal:

curl localhost:12346/echo/ping

The echo service simply takes a request value and appends “pong” to it for the response. By sending “ping”, you should see this output:

{"message":"ping pong"}%

6. 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 Dockerized 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 -a localhost:35142

Expected output:

Starting tests
Tester finished
Test echo test------
 [Status: finished] [Started at: 2024-01-04 08:04:41 PST] [End: 2024-01-04 08:04:41 PST] [Duration: 0s]
  - pattern0.echo_test
    [Status: finished] [Started at: 2024-01-04 08:04:41 PST] [Duration: 0.0065s]
  - pattern0.echo_test.0.echo_get
    [Status: finished] [Started at: 2024-01-04 08:04:41 PST] [Duration: 0.0016s]
    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:

• Tester
• Scenarios and Asserts
• Dynamic Requests
• Load Testing

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 Docker environments.

1. From the first terminal running Docker Compose, execute the following to stop the Docker Compose services:

docker compose down

2. Comment out these lines from the compose.yaml file in the project directory:

#  echo:
#    image: public.ecr.aws/skyramp/rampup/echo:latest
#    ports:
#      - "12346:12346"

3. Bring the Docker application back up, which will only be running the Skyramp Worker at this stage.

docker compose up &

4. Now, let’s switch back to our second terminal. 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 -a localhost:35142

Expected output:

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

5. 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"
      }      

6. 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:

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

skyramp mocker apply echo-mock -a localhost:35142

Expected output:

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

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

skyramp tester start echo-test -a localhost:35142

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-04 08:32:51 PST] [End: 2024-01-04 08:32:51 PST] [Duration: 0s]
  - pattern0.echo_test
    [Status: finished] [Started at: 2024-01-04 08:32:51 PST] [Duration: 0.0125s]
  - pattern0.echo_test.0.echo_get
    [Status: finished] [Started at: 2024-01-04 08:32:51 PST] [Duration: 0.0034s]
    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:

• Mocker
• Dynamic Responses
• Generate a Mock from User Input
• gRPC Proxying

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 Dockerized Services

1. Identify the services in your Docker 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:

• Dashboard
• Architecure
• Libraries
• CLI commands
• YouTube Videos
• Blog Articles