Getting started with Tests
Getting started (continue) with Tests
Now that you have finished the Getting started guide, you should have a Microcks installation up-and-running and filled with some samples from the Microcks repository. The goal of this page is to show you how you can use Microcks to achieve Contract Testing for your API, either manually from the UI or in an automated way using the CLI tooling.
If you have not done it in the previous step, you will need to load one of Microcks samples: the Pastry API. For that, just create a new Importer with the Pastry API name and this URL : https://raw.githubusercontent.com/microcks/microcks/master/samples/APIPastry-openapi.yaml
Once loaded, Microcks will discover the API Pastry - 2.0 in version 2.0.0. You will be able to browse the operations/resources and associated request/response samples of this service.
You’ll see that this sample contains a number of different features. It will illustrate:
- Simple
GET
operation mocking and testing, Path parameters
matching and testing,- Content negotiation matching and testing.
Now that we have the sample API registered in Microcks, we can deploy an implementation of this API contract. This will be our System Under Test.
Deploying the API Pastry implementation
We provide a basic implementation of the API Pastry - 2.0 in version 2.0.0 API and you may find the source code of it within this GitHub repository. The component is available as the following container image: quay.io/microcks/quarkus-api-pastry:latest
.
Follow the instructions based on the platform you used for deploying Microcks (Kubernetes or docker-compose).
On Kubernetes
On Kubernetes, we recommend creating a dedicated namespace
for holding the component. You can reuse our manifests to easily create a Deployment
and associated Service
as well as an Ingress
that will allow you to expose the application outside the cluster. You’ll need to edit this Ingress
to fix the URL to suit your cluster settings.
$ kubectl create ns api-pastry
namespace/api-pastry created
$ kubectl create -f https://raw.githubusercontent.com/microcks/api-lifecycle/master/api-pastry-demo/api-implementations/quarkus-api-pastry/deployment.yml -n api-pastry
deployment.apps/quarkus-api-pastry created
service/quarkus-api-pastry created
$ kubectl create -f https://raw.githubusercontent.com/microcks/api-lifecycle/master/api-pastry-demo/api-implementations/quarkus-api-pastry/ingress.yml -n api-pastry
ingress.networking.k8s.io/quarkus-api-pastry created
$ kubectl edit ingress/quarkus-api-pastry -n api-pastry
ingress.extensions/quarkus-api-pastry edited
You can easily retrieve the URL of the ingress using the following command:
$ kubectl get ingress/quarkus-api-pastry -n api-pastry -o json | jq '.spec.rules[0].host'
"quarkus-api-pastry.192.168.64.8.nip.io"
If you used docker-compose
On docker-compose, locally, you’ll just have to open a new terminal window and run this command to locally launch the component:
$ docker run -i --rm -p 8282:8282 quay.io/microcks/quarkus-api-pastry:latest
__ ____ __ _____ ___ __ ____ ______
--/ __ \/ / / / _ | / _ \/ //_/ / / / __/
-/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2020-10-19 14:49:37,134 INFO [io.quarkus] (main) quarkus-api-pastry 1.0.0-SNAPSHOT native (powered by Quarkus 1.7.1.Final) started in 0.104s. Listening on: http://0.0.0.0:8282
2020-10-19 14:49:37,135 INFO [io.quarkus] (main) Profile prod activated.
2020-10-19 14:49:37,135 INFO [io.quarkus] (main) Installed features: [cdi, resteasy, resteasy-jaxb, resteasy-jsonb]
Depending on you system and docker version, the application endpoint will be reachable at http://docker.for.mac.localhost:8282
or http://docker.for.win.localhost:8282
or http://localhost:8282
from you host network. However you’ll have to use http://host.docker.internal:8282
as the test endpoint when launching a step in next step.
If you still encounter issues joining this container from Microcks main one, you may use the command
docker run -i --name pastry --network=docker-compose_default --rm -p 8282:8282 quay.io/microcks/quarkus-api-pastry:latest
to force the implementation to join the network that was created by the Microcks docker-compose. After that, you’ll have to usehttp://pastry:8282
as the test endpoint.
Launching a test
Now that our component implementing the API is running, it’s time to launch some tests to check if it is actually compliant with the API Contract. This is what we call Contract Testing. You can launch and run tests from the UI or from the microcks-cli
tool.
From the UI
You may already have seen it but there’s a NEW TEST… button on the right hand side of the page detailing the API Pastry service. Hitting it leads you to the following form where you will be able to specify a target URL for the test, as well as a Runner — a testing strategy for your new launch:
Just copy/paste the endpoint URL where your quarkus-api-pastry
deployment can be reached here - either the Kubernetes Ingress URL or the local docker-compose one. Then select the OPEN_API_SCHEMA
test strategy (read here for more on tests runners). And finally, hit the Launch test ! button. This lead you to the following screen where you will wait for tests to run and finalize (green check marks should appear after some seconds).
Following the Full results link in the above screen will lead you to a screen where you’ll have access to all the test details and request/responses content exchanged with the endpoint during the tests. Very handy for troubleshooting or comparing results on different environments!
From the CLI
Microcks also provides the microcks-cli
tool that can be used to automate the testing. Binary releases for Linux, MacOS or Windows platform are available on the GitHub releases page. Just download the binary corresponding to your system and put the binary into the PATH
somewhere.
You can also use the corresponding container image for a quick ride! Just specify the test
command followed by the API/Service name and version, the test endpoint URL, the runner as well as some connection credentials and it will launch the test for you:
$ docker run -it quay.io/microcks/microcks-cli:latest microcks-cli test \
'API Pastry - 2.0:2.0.0' http://quarkus-api-pastry.192.168.64.8.nip.io OPEN_API_SCHEMA \
--microcksURL=https://microcks.192.168.64.8.nip.io/api/ \
--keycloakClientId=microcks-serviceaccount \
--keycloakClientSecret=ab54d329-e435-41ae-a900-ec6b3fe15c54 \
--insecure --waitFor=6sec
MicrocksClient got status for test "5f8eb1a5c696bd71fcdcb6ad" - success: false, inProgress: true
MicrocksTester waiting for 2 seconds before checking again or exiting.
MicrocksClient got status for test "5f8eb1a5c696bd71fcdcb6ad" - success: true, inProgress: false
Of course, you will have to replace the test endpoint URL as well as the Microcks URL with the ones from your platform (e.g.
http://docker.for.mac.localhost:8282
,http://docker.for.win.localhost:8282
for the API Pastry,https://docker.for.mac.localhost:8080
orhttps://docker.for.win.localhost:8080
for Microcks when using docker-compose)
What’s next?
Now that you have basic information on how to use Microcks for mocking and testing, you can go further with:
- Understanding how Microcks compare to alternatives,
- Creating your definition files using OpenAPI, AsyncAPI, SoapUI or Postman,
- Using exposed mocks and using variables,
- Executing your tests on endpoints where your services and API are deployed,
- Using advanced features of Microcks and admin stuffs.