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