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
3. Install Helm - Follow these instructions.
You can verify the Helm installation with helm version:
$ helm version
version.BuildInfo{Version:"v3.13.3", GitCommit:"c8b948945e52abba22ff885446a1486cb5fd3474", GitTreeState:"clean", GoVersion:"go1.21.5"}
4. Install kubectl - Follow these instructions.
You can verify the kubectl installation with kubectl version --client:
$ kubectl version --client
Client Version: v1.29.0
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
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 Kubernetes to run a simple service that we can test with Skyramp.
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, let’s create a Kubernetes cluster using the Skyramp CLI. You can always register your own Kubernetes cluster with Skyramp, but we’ll create one for the purposes of this tutorial. Simply execute this command in a terminal client:
skyramp cluster create -l
You will see output similar to this:
Creating local cluster [##############################################################] 100 %
Successfully created local cluster.
Starting/restarting Resolver [###########################################################] 100 %
Resolver manages DNS changes needed to access the cluster and needs sudo access.
Password:
Provide the password and then set the KUBECONFIG environment variable in the terminal:
export KUBECONFIG=$HOME/.skyramp/kind-cluster.kubeconfig
3. In order install services from Skyramp’s Helm charts, add and update the Skyramp Helm repository using the helm repo command as shown below:
helm repo add skyramp https://letsramp.github.io/helm/; helm repo update
Then, install the echo service into the Kubernetes cluster using helm install:
helm install echo skyramp/echo -n default
The echo service is a simple service that we will use for testing in this tutorial, and can ultimately be substituted by your own services you want to test.
You should see output similar to this:
NAME: echo
LAST DEPLOYED: Thu Jan 11 08:48:55 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
1. Get the application URL by running these commands:
export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=echo,app.kubernetes.io/instance=echo" -o jsonpath="{.items[0].metadata.name}")
export CONTAINER_PORT=$(kubectl get pod --namespace default $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
echo "Visit http://127.0.0.1:8080 to use your application"
kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT
4. Use kubectl to verify that the echo service was deployed to the cluster and is up and running.
kubectl get pods -n default
You should see output similar to below. Wait to proceed until you see “1/1” in the “READY” column for the service.
NAME READY STATUS RESTARTS AGE
echo-cfd9d4bd9-t5vqq 1/1 Running 0 68s
5. Finally, 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 distributed 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 -n default
Note: the first time you run the test, the Skyramp Worker will be provisioned and installed to the cluster.
Expected output:
Starting tests
Tester finished
Test echo test------
[Status: finished] [Started at: 2024-01-11 08:51:26 PST] [End: 2024-01-11 08:51:26 PST] [Duration: 0s]
- pattern0.echo_test
[Status: finished] [Started at: 2024-01-11 08:51:26 PST] [Duration: 0.0083s]
- pattern0.echo_test.0.echo_get
[Status: finished] [Started at: 2024-01-11 08:51:26 PST] [Duration: 0.0033s]
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:
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 Kubernetes environments.
1. From the terminal, execute the following to uninstall the running echo service:
helm uninstall echo -n default
Expected output:
release "echo" uninstalled
2. 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 -n default
Expected output:
Starting tests
Tester failed
Test echo test------
[Status: failed] [Started at: 2024-01-11 09:05:29 PST]
Error: failed to resolve echo: lookup echo on 10.96.0.10:53: no such host
- pattern0.echo_test
[Status: initializing] [Started at: N/A]
3. 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"
}
4. 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:
5. We can apply our new mock using skyramp mocker from the command line:
skyramp mocker apply echo-mock -n default
Expected output:
Applying mock config [##############################################################] 100 %
Successfully applied mock configurations.
6. Run the test scenario again with the mock in place:
skyramp tester start echo-test -n default
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-11 08:54:53 PST] [End: 2024-01-11 08:54:53 PST] [Duration: 0s]
- pattern0.echo_test
[Status: finished] [Started at: 2024-01-11 08:54:53 PST] [Duration: 0.0015s]
- pattern0.echo_test.0.echo_get
[Status: finished] [Started at: 2024-01-11 08:54:53 PST] [Duration: 0.0011s]
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:
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 Kubernetes Services
1. Identify the services in your Kubernetes 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:
