YAKS

You need access to a Kubernetes or Openshift cluster in order to use YAKS. You have different options to setup/use a Kubernetes or OpenShift cluster.

Obviously the cluster will be the place where the tests will be executed and probably also the place where to run the SUT (System Under Test).

For setting up roles and custom resources you may need to have administrative rights on that cluster.

For full support of Yaks on Windows please enable "Windows Subsystem for Linux". You can do it manually by heading to Control Panel > Programs > Turn Windows Features On or Off and checking "Windows Subsystem for Linux". Or you can simply execute this command in powershell:

This action requires a full reboot of the system.

The YAKS operator will listen for new test resources in order to run those on the cloud infrastructure. The operators is in charge of preparing a proper runtime for each test and it will reconcile the status of a test.

The easiest way to getting started with the YAKS operator installation is to use the YAKS CLI. You can download the CLI from the release page where you will find installation archives for different operating systems.

Download and decompress the archive. The archive holds a binary that will help you to install YAKS and run the tests. To install the yaks binary, just make it runnable and move it to a location in your $PATH, e.g. on linux:

Once you have the yaks CLI available, log into your cluster using the standard oc (OpenShift) or kubectl (Kubernetes) client tool.

Once you are properly connected to your cluster execute the following command to install YAKS:

This will install and run the YAKS operator in the current namespace.

You can specify the target namespace where to run the operator with a --namespace option:

The namespace must available on the cluster before running the install command. If the namespace has not been created, yet you can create it with the following command:

If not already configured, the command will also setup the YAKS custom resource definitions and roles on the cluster (in this case, the user needs cluster-admin permissions).

You can verify the installation by retrieving the custom resource definition provided in YAKS:

The following command will list all tests in your namespace:

As you run tests with YAKS you add tests to the current namespace. You can review the test status and monitor the test results with the default Kubernetes CLI tool.

The following command will list all tests in your namespace:

The overview includes the test outcome and outline the number of total scenarios that have been executed and the test results for these scenarios (skipped, passed or failed). When a scenario has been failing the error message is also displayed in this overview.

You can get more details of a single test with:

This gets you the complete test details as a YAML file. You can then review status and detailed error messages.

Find out more about the individual test results and how to get reports (e.g. JUnit) from a test run in the section about reporting.

Some of the most used commands are:

The list above is not the full list of available commands. You can run yaks help to obtain the full list. And each command also takes --help as parameter to output more information:

The YAKS testing framework provides a base runtime image that holds all required libraries and artifacts to execute tests. You may need to add additional runtime dependencies though in order to extend the framework capabilities.

For instance when using a Camel route in your test you may need to add additional Camel components that are not part in the basic YAKS runtime (e.g. camel-groovy). You can add the runtime dependency to the YAKS runtime image in multiple ways:

When adding custom runtime dependencies those artifacts might not be available on the public central Maven repository. Instead you may need to add a custom repository that holds your artifacts.

You can do this with several configuration options:

Tests usually need to use credentials and connection URLs in order to connect to infrastructure components and services. This might be sensitive data that should not go into the test configuration directly as hardcoded value. You should rather load the credentials from a secret volume source.

To use the implicit configuration via secrets, we first need to create a configuration file holding the properties of a named configuration.

We can create a secret from that file and label it so that it will be picked up automatically by the YAKS operator:

Once the secret is created you can bind it to tests by their name. Given the test my-test.feature you can bind the secret to the test by adding a label as follows:

For multiple secrets and variants of secrets on different environments (e.g. dev, test, staging) you can add a secret id and label that one explicitly in addition to the test name.

With that in place you just need to set the secret id in your yaks-config.yaml for that test.

You can now write a test and use the secret properties as normal test variables:

The standard steps provide a lot of basic features and predefined steps that you can use to write feature files. Most of the steps aim to leverage capabilities of the underlying test framework Citrus. For instance the steps are able to create Citrus test variables or print messages to the output.

ToDo

If the subject under test is a Camel K integration, you can leverage the YAKS Camel K bindings that provide useful steps for checking the status of integrations.

For example:

The Camel K extension library is provided by default in YAKS.

The Groovy support in YAKS allows to add framework configuration, bean configuration and test actions via script snippets. In particular you can easily add customized endpoints that send/receive data over various messaging transports.

The Http protocol is a widely used communication protocol when it comes to exchanging data between systems. REST Http services are very prominent and producing/consuming those services is a common task in software development these days. YAKS provides ready to use steps that are able to exchange request/response messages via Http during the test.

As a client you can specify the server URL and send requests to it.

The example above sets a base request URL to http://localhost:8080 and performs a health check on path /health. After that we can send any request to the server and verify the response body and status code.

All these steps are part of the core YAKS framework and you can just use them.

On the server side we can start a new Http server instance on a given port and listen for incoming requests. These request can be verified and the test can provide a simulated response message with body and header data.

In the HTTP server sample above we create a new server instance listening on port 8080. Then we expect a GET request on path /todo. The server responds with a Http 200 OK response message and given Json body as payload.

The second scenario expects a POST request with a given body as Json payload. The expected request payload is verified with the powerful Citrus JSON message validator being able to compare JSON tree structures in combination with validation matchers such as isNumber() or matches(0|1).

Once the request is verified the server responds with a simple Http 201 CREATED.

YAKS provides a library that allows to execute SQL actions on relational DBs (limited to PostgreSQL for this POC).

You can find examples of JDBC steps in the examples file.

There’s also an example that uses JDBC and REST together and targets the Syndesis TODO App database.

ToDo

ToDo

ToDo

ToDo

OpenAPI documents specify RESTful Http services in a standardized, language-agnostic way. The specifications describe resources, path items, operations, security schemes and many more components that are part of the REST service. YAKS as a framework is able to use these information in order to generate proper request and response data for your test.

You can find examples of how to use OpenAPI specifications in YAKS in the examples.

Given an OpenAPI specification that you can access via Http URL or local file system you can load all available operations into the test. Once this is completed you can invoke operations by name and verify the response status codes. YAKS will automatically generate proper request/response data for you.

The request/response data is generated from the OpenAPI specification rules and holds randomized values. The following sample shows a generated request for the addPet operation where a new pet is transmitted via Http POST.

The generated request should be valid according to the rules in the OpenAPI specification. You can overwrite the randomized values with test variables and inbound/outbound data dictionaries in order to have more human readable test data.

With this data dictionaries in place the generated request looks like follows:

You see that we are now using more human readable values for $.name and $.category.name.

The same mechanism applies for inbound messages that are verified by YAKS. The framework will generate an expected response data structure coming from the OpenAPI specification. Below is a sample Json payload that verifies the response for the getPetById operation.

All mandatory fields need to be in the received json document. Also enumerations and number values are checked to meet the expected values coming form the OpenAPI specification (e.g. status=@matches(available|pending|sold)@). This ensures that the response respects the rules defined in the specification.

In case you also want to validate the exact values on each field please use the generic Http steps where you can provide a complete expected Http response with payload and header data.