Overview

This guide illustrates the usage of microcks-cli, a command-line tool for interacting with Microcks APIs. It allows for launching tests or importing API artifacts with minimal dependencies. It is managed and released independently of the core Microcks server components within its own GitHub repository. The CLI connects to API and uses Service Account and so it’s definitely worth the read 😉

The CLI also supports authenticated and non-authenticated modes when Microcks is deployed without Keycloak. You’ll still have to provide the client ID and secret to commands, but they will be ignored. See issue #23 for more details.

1. Install the CLI

The CLI is provided as a binary distribution or can be used directly through a container image.

Using Homebrew

You can install microcks-cli using Homebrew.

brew tap microcks/tap
brew install microcks-cli

Binary distribution

The CLI binary releases are available for Linux, macOS or Windows platforms with different architectures on GitHub releases. Just download the binary corresponding to your system and put it in the PATH somewhere. For example, on a Linux platform with amd64 architecture, you may run these commands:

curl -Lo microcks-cli https://github.com/microcks/microcks-cli/releases/download/0.5.5/microcks-cli-darwin-amd64 \
    && chmod +x microcks-cli

Container image

The microcks-cli is also available as a container image so that you may run it without installing it. The hosting repository is on Quay.io. You can simply pull the image to get it locally:

docker pull quay.io/microcks/microcks-cli:latest

2. Launching a test

Assuming you are running the same examples as in the Getting started and Getting started with Tests tutorials, you may use this command line to launch a new test:

microcks-cli test 'API Pastry - 2.0:2.0.0' http://host.docker.internal:8282 OPEN_API_SCHEMA \
    --microcksURL=http://host.docker.internal:8585/api/ \
    --keycloakClientId=microcks-serviceaccount \
    --keycloakClientSecret="ab54d329-e435-41ae-a900-ec6b3fe15c54" \
    --operationsHeaders='{"globals": [{"name": "x-api-key", "values": "azertyuiop"}], "GET /pastries": [{"name": "x-trace-id", "values": "qsdfghjklm"}]}' \
    --insecure --waitFor=6sec

With some explanations on arguments and flags:

• 1st argument is API name and version separated with :,
• 2nd argument is the Application endpoint to test,
• 3rd argument is the testing strategy to execute,
• --flags are contextual flags for API endpoints, authentication, timeouts, etc.

The same command can also be executed using the container image:

docker run -it quay.io/microcks/microcks-cli:latest microcks-cli test \
    'API Pastry - 2.0:2.0.0' http://host.docker.internal:8282 OPEN_API_SCHEMA \
    --microcksURL=http://host.docker.internal:8585/api/ \
    --keycloakClientId=microcks-serviceaccount \
    --keycloakClientSecret="ab54d329-e435-41ae-a900-ec6b3fe15c54" \
    --operationsHeaders='{"globals": [{"name": "x-api-key", "values": "azertyuiop"}], "GET /pastries": [{"name": "x-trace-id", "values": "qsdfghjklm"}]}' \
    --insecure --waitFor=6sec

Check the microcks-cli README for full instructions on arguments and flags.

Wrap-up

You have learned how to install and use the Microcks CLI to launch a new test. This is what you would typically do within your CI/CD pipeline to ensure that the application you just deployed correctly implements the API specifications.

Microcks CLI also provides the import command that allows you to push artifacts into the Microcks repository. This command requires that you have a Service Account with more privileges than the default one, though. You may follow up on this guide by learning more about Service Accounts.

The CLI provides the helpful commands version and help to get basic information on it. Check the microcks-cli README for full instructions on available commands depending on your version.