Getting started with Tests
Getting started (continue) with Tests
Now that you have finished the Getting started, you should have a Microcks installation up-and-running and filled with some samples coming from the Microcks repository. The goal of this page is to introduce you how you can use Microcks to realize Contract Testing for your API, either manually from the UI or in an automated way using the CLI tooling.
If you have not do it in previous step, you will need to load one of Microcks samples that is 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 allow to illustrate:
- Simple
GET
operation mocking and testing, Path parameters
matching and testing,- Content negociation matching and testing.
Now that we have the sample API registered in Microcks, we’ll have to 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 coming instructions depending 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 exposing the application outside the cluster. You’ll need to edit this Ingress
in order 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, the application endpoint will be reachable at http://docker.for.mac.localhost:8282
or http://docker.for.win.localhost:8282
or http://localhost:8282
.
Launching a test
Our component implementing the API now 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 see it but there’s a NEW TEST… button on the right hand size of the page detailing the API Pastry service. Hitting it leads you to the following form where you will be able to specify an target URL for test, as well as a Runner - a testing strategy for your new launch:
Just copy/paste here the endpoint URL where your quarkus-api-pastry
deployment can be reached - 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 when 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 sreen will lead you to a screen where you’ll have access to all the test details and request/responses content exchnaged with the endpoint during the tests. Very handy for troubleshooting or comparing results on different environments !
From the CLI
Microcks is also providing 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 somme 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.