diff --git a/README.md b/README.md index 38f9308..7331e72 100644 --- a/README.md +++ b/README.md @@ -17,130 +17,59 @@ Current development version is `0.5.6`. [![GitHub Workflow Status](https://img.s It is available as a container image named `quay.io/microcks/microcks-cli:nightly`. -## Usage instructions +## CLI Command Overview -Usage is simply `microcks-cli [command]` - -where `[command]` can be one of the following: - -* `version` to check this CLI version, -* `help` to display usage informations, -* `test` to launch new test on Microcks server. -* `import` to import API artifacts on Microcks server. - -### Test command - -The `test` command has a bunch of arguments and flags so that you can use it that way: - -``` -microcks-cli test - --microcksURL=<> --waitFor=5sec - --keycloakClientId=<> --keycloakClientSecret=<> -``` - -The arguments: - -* `` : Service to test reference. Example: `'Beer Catalog API:0.9'` -* `` : URL where is deployed implementation to test -* `` : Test strategy (one of: `HTTP`, `SOAP`, `SOAP_UI`, `POSTMAN`, `OPEN_API_SCHEMA`, `ASYNC_API_SCHEMA`, `GRPC_PROTOBUF`, `GRAPHQL_SCHEMA`) - -The flags: - -* `--microcksURL` for the Microcks API endpoint, -* `--waitFor` for the time to wait for test to finish (int + one of: milli, sec, min), -* `--keycloakClientId` for the Keycloak Realm Service Account ClientId, -* `--keycloakClientSecret` for the Keycloak Realm Service Account ClientSecret. - -> Since `0.5.2` release, `microcks-cli` also works in unauthenticated mode, without Keycloak being deployed and configured with your Microcks instance. However, you still have to specify the Keycloak flags on the command even if you put random values there. For eg. `--keycloakClientId=foo --keycloakClientSecret=bar`. - -Real life example command and execution: - -```sh -$ ./microcks-cli test 'Beer Catalog API:0.9' http://localhost:9090/api/ POSTMAN \ - --microcksURL=http://localhost:8080/api/ \ - --keycloakClientId=microcks-serviceaccount \ - --keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 \ - --waitFor=3sec -[...] -MicrocksClient got status for test "5c1781cf6310d94f8169384e" - success: false, inProgress: true -MicrocksTester waiting for 2 seconds before checking again. -MicrocksClient got status for test "5c1781cf6310d94f8169384e" - success: true, inProgress: false -Full TestResult details are available here: http://localhost:8080/#/tests/5c1781cf6310d94f8169384e +### Usage +```bash +microcks [command] [flags] ``` -#### Advanced options - -The `test` command provides additional flags for advanced usages and options: - -* `--verbose` allows to dump on standard output all the HTTP requests and responses, -* `--insecure` allows to interact with Microcks and Keycloak instances through HTTPS without checking certificates issuer CA, -* `--caCerts=` allows to specify additional certificates CRT files to add to trusted roots ones, -* `--secretName=''` is an optional flag specifying the name of a Secret to use for connecting endpoint, -* `--filteredOperations=` allows to filter a list of operations to launch a test for, -* `--operationsHeaders=` allows to override some operations headers for the tests to launch, -* `--oAuth2Context=` allows specification of an OAuth2 grant flow to execute before launching the test (starts with Microcks version `1.8.0`). +### Availabel Commands +| Command | Description | Documentation | +| ------------ | -------------------------------------------------------- | ----------------------------------------------- | +| `login` | Log in to a Microcks instance using Keycloak credentials | [`login`](documentation/cmd/login.md) | +| `logout` | Log out and remove authentication from a given context | [`logout`](documentation/cmd/logout.md) | +| `context` | Manage CLI contexts (list, use, delete) | [`context`](documentation/cmd/context.md) | +| `start` | Start a local Microcks instance via Docker/Podman | [`start`](documentation/cmd/start.md) | +| `stop` | Stop a local Microcks instance | [`stop`](documentation/cmd/stop.md) | +| `import` | Import API spec files from local filesystem | [`import`](documentation/cmd/import.md) | +| `import-url` | Import API spec files directly from a remote URL | [`import-url`](documentation/cmd/import-url.md) | +| `test` | Run tests against a deployed API using selected runner | [`test`](documentation/cmd/test.md) | +| `version` | Print Microcks CLI version | [`version`](documentation/cmd/version.md) | + +### Options + +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `-h, --help` | help for microck command | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | -Overriden test operations headers is a JSON strings where 1st level keys are operation name (eg. `GET /beer`) or `globals` for header applying to all the operations of the API. Headers are specified as an array of objects defining `key` and `values` properties. -Here's below an example of using some of this flags: - -```sh -$ ./microcks-cli test 'Beer Catalog API:0.9' http://localhost:9090/api/ OPEN_API_SCHEMA \ - --microcksURL=http://localhost:8080/api/ \ - --keycloakClientId=microcks-serviceaccount \ - --keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 \ - --insecure --verbose --waitFor=3sec \ - --filteredOperations='["GET /beer", "GET /beer/{name}"]' \ - --operationsHeaders='{"globals": [{"name": "x-api-key", "values": "my-values"}], "GET /beer": [{"name": "x-trace-id", "values": "xcvbnsdfghjklm"}]}' \ - --oAuth2Context='{"clientId": "microcks-test", "clientSecret": "ab54d329-e435-41ae-a900-ec6b3fe15c54", "tokenUri": "https://idp.acme.org/realms/my-app/protocol/openid-connect/token", "grantType": "CLIENT_CREDENTIALS"}' +## Installation -MicrocksClient got status for test "64c25f7ddec62569f9a0ed95" - success: true, inProgress: false -Full TestResult details are available here: http://localhost:8080/#/tests/64c25f7ddec62569f9a0ed95 +### Building from Source +To build the CLI locally: +```bash +make build-local ``` -### Import command - -The `import` command has one argument and common flags with `test` command. You can use it that way: - +The resulting binary will be available at: +```bash +/build/dist/microcks ``` -microcks-cli import - --microcksURL=<> - --keycloakClientId=<> --keycloakClientSecret=<> -``` - -The arguments: - -* `` : Comma separated list of API specs to import with flag telling if it's a primary artifact. Example: `'specs/my-openapi.yaml:true,specs/my-postmancollection.json:false'` - -The flags: -* `--microcksURL` for the Microcks API endpoint, -* `--keycloakClientId` for the Keycloak Realm Service Account ClientId, -* `--keycloakClientSecret` for the Keycloak Realm Service Account ClientSecret. - -> Since `0.5.2` release, `microcks-cli` also works in unauthenticated mode, without Keycloak being deployed and configured with your Microcks instance. However, you still have to specify the Keycloak flags on the command even if you put random values there. For eg. `--keycloakClientId=foo --keycloakClientSecret=bar`. - -Real life example command and execution: - -```sh -$ ./microcks-cli import 'samples/weather-forecast-openapi.yml:true,samples/weather-forecast-postman.json:false' \ - --microcksURL=http://localhost:8080/api/ \ - --keycloakClientId=microcks-serviceaccount \ - --keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 -Microcks has discovered 'WeatherForecast API:1.1.0' -Microcks has discovered 'WeatherForecast API:1.1.0' +You can move it to a location in your $PATH for global usage, for example: +```bash +sudo mv build/dist/microcks /usr/local/bin/microcks ``` -#### Advanced options - -The `import` command provides additional flags for advanced usages and options: - -* `--verbose` allows to dump on standard output all the HTTP requests and responses, -* `--insecure` allows to interact with Microcks and Keycloak instances through HTTPS without checking certificates issuer CA, -* `--caCerts=` allows to specify additional certificates CRT files to add to trusted roots ones, - - -## Installation ### Binary diff --git a/documentation/cmd/context.md b/documentation/cmd/context.md new file mode 100644 index 0000000..9a08273 --- /dev/null +++ b/documentation/cmd/context.md @@ -0,0 +1,39 @@ +## `microcks context` โ€“ Manage CLI Contexts +Switch between, list, or delete configured Microcks CLI contexts. + +### Usage +```bash +microcks context [CONTEXT] [flags] +``` + +### Examples +```bash +# List all available contexts +microcks context/ctx + +# Switch to this context +microcks context/ctx http://localhost:8080 + +# Delete the context +microcks context/ctx http://localhost:8080 --delete/-d +``` +### Options +| Flag | Description | +| -------------- | ---------------------------- | +| `-d, --delete` | Delete the specified context | +| `-h, --help` | help for context | + +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | + + + diff --git a/documentation/cmd/import.md b/documentation/cmd/import.md index 83832b0..4ef31e4 100644 --- a/documentation/cmd/import.md +++ b/documentation/cmd/import.md @@ -1,56 +1,43 @@ -# Import Command +## `microcks import` โ€“ Import API Artifacts into Microcks +Uploads one or more API spec files (e.g., OpenAPI, AsyncAPI, Postman) to the Microcks server and optionally watches them for changes. -The `import` command in Microcks CLI is used to upload and register API specification artifacts (like OpenAPI, AsyncAPI, Postman collections, etc.) into a Microcks server. +### Usage +```bash +microcks import , [flags] +``` + +### Examples +```bash +# Import a single artifact (marked as main) +microcks import ./api.yaml -๐Ÿ“ Description +# Specify mainArtifact flag for each file +microcks import ./api.yaml:false,./schema.json:true -The `import` command enables developers to push one or multiple API artifacts to a Microcks instance. It supports secure authentication via Keycloak and allows custom TLS configurations for secure communication. +# Import and watch file for changes +microcks import ./api.yaml --watch -๐Ÿ“Œ Usage -```bash -microcks import , \ - --microcksURL \ - --keycloakClientId \ - --keycloakClientSecret \ - [--insecure] \ - [--caCerts ] \ - [--verbose] +# Import specification to microcks without logining to microcks +microck import ./api.yaml \ + --micrcoksURL \ + --keycloakClientId \ + --keycloakClientSecret ``` -Arguments -- ``: -A comma-separated list of specification file paths to import. -Optionally, each file can be suffixed with `:true` or `:false` to indicate whether it's the primary artifact. -| Flag | Type | Required | Description | -|-------------------------|---------|----------|-----------------------------------------------------------------------------| -| `--microcksURL` | string | โœ… | The URL of the Microcks API endpoint. | -| `--keycloakClientId` | string | โœ… | The Keycloak Service Account Client ID for OAuth2 authentication. | -| `--keycloakClientSecret`| string | โœ… | The Keycloak Service Account Client Secret for authentication. | -| `--insecure` | bool | โŒ | Allow insecure TLS connections (e.g., self-signed certs). | -| `--caCerts` | string | โŒ | Comma-separated paths to additional CA certificate files (PEM format). | -| `--verbose` | bool | โŒ | Enable verbose mode to dump HTTP requests and responses to the console. | +### Options +| Flag | Description | +| ----------- | --------------------------------------------------- | +| `-h, --help`| help for import | +| `--watch` | Watch the file(s) and auto-reimport them on changes | -๐Ÿงช Examples -- Basic Import -```bash -microcks import my-api.yaml \ - --microcksURL http://localhost:8080/api \ - --keycloakClientId my-client \ - --keycloakClientSecret my-secret -``` -- Import Multiple Files with Primary Indicator -```bash -microcks import openapi.yaml:true,postman.json:false \ - --microcksURL https://microcks.example.com/api \ - --keycloakClientId my-client \ - --keycloakClientSecret my-secret -``` -- Using Custom TLS CA Certificates and Verbose Logging -```bash -microcks-cli import spec.yaml \ - --microcksURL https://microcks.example.com/api \ - --keycloakClientId my-client \ - --keycloakClientSecret my-secret \ - --caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \ - --verbose -``` +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | diff --git a/documentation/cmd/importURL.md b/documentation/cmd/importURL.md index c8b664b..d273f0c 100644 --- a/documentation/cmd/importURL.md +++ b/documentation/cmd/importURL.md @@ -1,60 +1,34 @@ -# ImportURL Command +## `microcks import-url` โ€“ Import API Artifacts from URL +Imports API specification files (OpenAPI, AsyncAPI, etc.) hosted at a remote URL into the Microcks server. -The `import-url` command in Microcks CLI is used to upload and register API specification artifacts(like OpenAPI, AsyncAPI, Postman collections, etc.) from URLs into a Microcks server. - -๐Ÿ“ Description - -The `import-url` command provides a convenient way to register API specifications (OpenAPI, AsyncAPI, Postman collections, etc.) hosted online without needing to download them manually. This is useful for CI/CD pipelines or importing frequently updated remote specs. - -๐Ÿ“Œ Usage +### Usage ```bash -microcks import-url , \ - --microcksURL \ - --keycloakClientId \ - --keycloakClientSecret \ - [--insecure] \ - [--caCerts ] \ - [--verbose] +microcks import-url , [flags] ``` -Arguments -- ``: -A comma-separated list of publicly accessible URLs pointing to specification files. -Optionally, each URL can be suffixed with `:true` or `:false` to mark it as a primary artifact. - - -| Flag | Type | Required | Description | -|-------------------------|---------|----------|-----------------------------------------------------------------------------| -| `--microcksURL` | string | โœ… | The URL of the Microcks API endpoint. | -| `--keycloakClientId` | string | โœ… | The Keycloak Service Account Client ID for OAuth2 authentication. | -| `--keycloakClientSecret`| string | โœ… | The Keycloak Service Account Client Secret for authentication. | -| `--insecure` | bool | โŒ | Allow insecure TLS connections (e.g., self-signed certs). | -| `--caCerts` | string | โŒ | Comma-separated paths to additional CA certificate files (PEM format). | -| `--verbose` | bool | โŒ | Enable verbose mode to dump HTTP requests and responses to the console. | - -๐Ÿงช Examples -- Importing from a Single URL +### Example ```bash -microcks import-url https://example.com/api/openapi.yaml \ - --microcksURL http://localhost:8080/api \ - --keycloakClientId my-client \ - --keycloakClientSecret my-secret -``` +# Import a single artifact (marked as main) +microcks import-url https://example.com/openapi.yaml -- Importing Multiple Remote Artifacts with Primary Designation -```bash -microcks import-url https://example.com/openapi.yaml:true,https://example.com/postman.json:false \ - --microcksURL https://microcks.example.com/api \ - --keycloakClientId my-client \ - --keycloakClientSecret my-secret -``` +# Specify mainArtifact flag for each file +microcks import-url https://example.com/spec1.yaml:true,https://example.com/spec2.yaml:false -- Using Custom TLS CA Certificates and Verbose Logging -```bash -microcks import-url https://mydomain.com/api/spec.yaml \ - --microcksURL https://microcks.example.com/api \ - --keycloakClientId my-client \ - --keycloakClientSecret my-secret \ - --caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \ - --verbose +# Import specification to microcks without logining to microcks +microck import-url https://example.com/openapi.yaml \ + --micrcoksURL \ + --keycloakClientId \ + --keycloakClientSecret ``` + +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | \ No newline at end of file diff --git a/documentation/cmd/login.md b/documentation/cmd/login.md new file mode 100644 index 0000000..099e7c9 --- /dev/null +++ b/documentation/cmd/login.md @@ -0,0 +1,46 @@ +## `microcks login` โ€“ Authenticate with a Microcks Instance +Log in to a Microcks instance using username/password or SSO. Creates or updates a CLI context with authentication details. + +### Examples +```bash +# Login to microcks using a username and password +microcks login http://locahost:8080 + +# Provide name to your logged in context (Defautl context name is server name) +microcks login http://localhost:8080 --name + +# Provide username and password as flags +microcks login http://localhost:8080 --username --password + +# Perform SSO login +microcks login http://localhost:8080 --sso + +# Change port callback server for SSO login +microcks login http://localhost:8080 --sso --sso-port + +# Get OAuth URI instead of getting redirect to browser for SSO login +microcks login http://localhost:8080 --sso --sso-launch-browser=false +``` + +### Options +| Flag | Description | +| ---------------------- | ------------------------------------------------------------ | +| `-h, --help` | help for login | +| `--name` | Name to assign the context (default: server URL) | +| `--username` | Username for login | +| `--password` | Password for login | +| `--sso` | Perform Single Sign-On (OIDC-based) login | +| `--sso-launch-browser` | Launch system browser for SSO (default: `true`) | +| `--sso-port` | Local port to use for SSO callback server (default: `58085`) | + +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | diff --git a/documentation/cmd/logout.md b/documentation/cmd/logout.md new file mode 100644 index 0000000..1fb0f87 --- /dev/null +++ b/documentation/cmd/logout.md @@ -0,0 +1,28 @@ +## `microcks logout` โ€“ Log Out from a Microcks Context +Removes authentication tokens from the specified context. + +### Usage +```bash +microcks logout CONTEXT +``` + +### Example +```bash +# Log out from the specified context +microcks logout http://localhost:8080 + +# Log out from a named context +microcks logout dev-context +``` + +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | diff --git a/documentation/cmd/start.md b/documentation/cmd/start.md index 4a073cb..65d8e89 100644 --- a/documentation/cmd/start.md +++ b/documentation/cmd/start.md @@ -1,34 +1,48 @@ -# Start Command +## `microcks start` โ€“ Start a Local Microcks Instance +Starts a Microcks instance using Docker or Podman and configures it as the current CLI context. -The `start` command allows you to launch a Microcks instance using a container runtime like Docker or Podman. It either starts a new container or resumes a previously created one based on saved configuration. - -๐Ÿ“Œ Usage +### Usage ```bash microcks start [flags] ``` -๐Ÿšฉ Flags -| Flag | Description | Required | Default | -| ---------- | -------------------------------------------------- | -------- | ---------------------------------------------- | -| `--name` | Name of the Microcks container/instance | No | `microcks` | -| `--port` | Host port to expose Microcks | No | `8585` | -| `--image` | Image to use for creating the container | No | `quay.io/microcks/microcks-uber:latest-native` | -| `--rm` | Auto-remove container on exit (like `docker --rm`) | No | `false` | -| `--driver` | Container runtime to use (`docker` or `podman`) | No | `docker` | +### Example +```bash +# Start a Microcks instance +microcks start +# Define your port (by default 8585) +microcks start --port [Port you want] -๐Ÿงช Examples +# Define your driver (by default docker) +microcks start --driver [driver you wnat either 'docker' or 'podman'] -Start Microcks with default settings: -```sh -microcks start -``` -Start Microcks on port 9090 using Podman: -```sh -microcks start --port 9090 --driver podman -``` +# Define name of your microcks container/instance +microcks start --name [name of you container/instance] -Start with a custom container name and image: -```sh -microcks start --name dev-microcks --image custom/microcks:latest +# Auto remove the container on exit +microcks start --rm ``` + +### Options +| Flag | Description | +| ----------- | -------------------------------------------------------------------------------- | +| `-h, --help`| help for start | +| `--name` | Name for the Microcks instance (default: `microcks`) | +| `--port` | Host port to expose Microcks (default: `8585`) | +| `--image` | Container image to use (default: `quay.io/microcks/microcks-uber:latest-native`) | +| `--rm` | Auto-remove the container when it exits (like Docker `--rm`) | +| `--driver` | Container driver to use (`docker` or `podman`, default: `docker`) | + +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | + diff --git a/documentation/cmd/stop.md b/documentation/cmd/stop.md new file mode 100644 index 0000000..59153db --- /dev/null +++ b/documentation/cmd/stop.md @@ -0,0 +1,25 @@ +## `microcks stop` โ€“ Stop a Local Microcks Instance +Stops the running Microcks instance associated with the current context. Cleans up config if --rm was used during start. + +### Usage +```bash +microcks stop +``` + +### Examples +```bash +# Stop the running instance linked to the current context +microcks stop +``` + +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | \ No newline at end of file diff --git a/documentation/cmd/test.md b/documentation/cmd/test.md new file mode 100644 index 0000000..9fb0c79 --- /dev/null +++ b/documentation/cmd/test.md @@ -0,0 +1,49 @@ +## `microcks test` โ€“ Run Tests on Microcks +Runs contract or integration tests against a deployed API using the selected runner. + +### Usage +```bash +microcks test [flags] +``` + +### Example +```bash +# Run a basic HTTP test on the local hello-api version 1.0.0 +microcks test hello-api:1.0.0 http://localhost:8080/api HTTP + +# Run a POSTMAN test on petstore API version 2.0.0, wait up to 10 seconds for completion +microcks test petstore:2.0.0 https://api.example.com POSTMAN --waitFor 10sec + +# Run a POSTMAN test on the local Beer Catalog API version 0.9.0 without logining to microcks +microcks test Beer Catalog API:0.9 http://localhost:9090/api/ POSTMAN \ + --microcksURL \ + --keycloakClientId \ + --keycloakClientSecret \ +``` + +### Runner Options +One of: +`HTTP`|`SOAP_HTTP`|`SOAP_UI`|`POSTMAN`|`OPEN_API_SCHEMA`|`ASYNC_API_SCHEMA`|`GRPC_PROTOBUF`|`GRAPHQL_SCHEMA` + +### Options +| Flag | Description | +| ---------------------- | ----------------------------------------------------------------------------------- | +| `-h, --help` | help for test | +| `--waitFor` | Time to wait for test result. Format: `5sec`, `2000milli`, `1min` (default: `5sec`) | +| `--secretName` | Secret name for accessing secured test endpoint | +| `--filteredOperations` | Comma-separated list of operations to test | +| `--operationsHeaders` | Custom headers for operations as JSON string | +| `--oAuth2Context` | OAuth2 client context as JSON string | + + +### Options Inherited from Parent Commands +| Flag | Description | +| ------------------------ | ------------------------------------------- | +| `--config` | Path to Microcks config file | +| `--microcks-context` | Name of the Microcks context to use | +| `--verbose` | Produce dumps of HTTP exchanges | +| `--insecure-tls` | Allow insecure HTTPS connections | +| `--caCerts` | Comma-separated paths of CA cert files | +| `--keycloakClientId` | Keycloak Realm Service Account ClientId | +| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret | +| `--microcksURL` | Microcks API URL | diff --git a/documentation/cmd/version.md b/documentation/cmd/version.md new file mode 100644 index 0000000..20f7969 --- /dev/null +++ b/documentation/cmd/version.md @@ -0,0 +1,6 @@ +## `microcks version` - Print microcks CLI version + +## Usage +```bash +microcks version +``` \ No newline at end of file