YAKS

By default, the installation is using a global operator mode. This means that the operator only lives once in your cluster watching for tests in all namespaces. A global operator uses cluster-roles in order to manage tests in all namespaces.

When running on OpenShift the default namespace for global operators is openshift-operators (it is available by default). Be sure to select this namespace when installing YAKS in the global mode:

You can disable the global mode with a CLI setting when running the install command:

In the non global namespaced mode the YAKS operator will only have the rights to create new tests in the same namespace as it is running on. The operator will only watch for tests created in that the very same namespace.

Please also have a look at the temporary namespaces section in this guide to make a decision on operator modes.

You can simply add a tag to your BDD feature specification in order to declare a runtime dependency for your test.

The given Camel route uses the groovy language support and this is not part in the basic YAKS runtime image. So we add the tag @require('org.apache.camel:camel-groovy:@camel.version@'). This tag will load the Maven dependency at runtime before the test is executed in the YAKS runtime image.

Note that you have to provide proper Maven artifact coordinates with proper groupId, artifactId and version. You can make use of version properties for these versions available in the YAKS base image:

You can add dependencies also by specifying the dependencies as command line parameter when running the test via yaks CLI.

This will add a environment setting in the YAKS runtime container and the dependency will be loaded automatically at runtime.

YAKS supports adding runtime dependency information to a property file called yaks.properties. The dependency is added through Maven coordinates in the property file using a common property key prefix yaks.dependency.

You can add the property file when running the test via yaks CLI like follows:

When more dependencies are required to run a test you may consider to add a configuration file as .yaml or .json.

The configuration file is able to declare multiple dependencies:

You can add the configuration file when running the test via yaks CLI like follows:

You can add repositories also by specifying the repositories as command line parameter when running the test via yaks CLI.

This will add a environment setting in the YAKS runtime container and the repository will be added to the Maven runtime project model.

YAKS supports adding Maven repository information to a property file called yaks.properties. The dependency is added through Maven repository id and url in the property file using a common property key prefix yaks.repository.

You can add the property file when running the test via yaks CLI like follows:

More complex repository configuration might require to add a configuration file as .yaml or .json.

The configuration file is able to declare multiple repositories:

You can add the configuration file when running the test via yaks CLI like follows:

Test variables represent the fundamental concept to own test data throughout your test. Once a variable has been created you can reference its value in many places in YAKS and Citrus. You can add a new identifier as a variable and reference its value in many places such as message headers, body content, SQL statements and many more.

This will create the variable orderId in the current test context. All subsequent steps and operations may reference the variable with the expression ${orderId}. Citrus makes sure to replace the variable placeholder with its actual value before sending out messages and before validating incoming messages. As already mentioned you can use the variable placeholder expression in many places such as message headers and body content:

You can create multiple variables in one single step using:

You can also load variables from an external property file resource.

The given {file} should be a property file holding one to many test variables with key and value.

Sometimes variables values are too big to write them directly into the feature file (e.g. large request/response body data). In this case you may want to load the variable value from an external file.

The step loads the file content as a String value and references it as a new test variable with the given name.

Logging a message to the output can be helpful in terms of debugging and/or to give information about the context of an operation.

YAKS provides following steps to add log output:

The steps are printing log messages to the output using INFO level. The text that is printed supports test variables and functions. All placeholders will be replaced before logging.

You can also use multiline log messages as shown in the next example.

The sleep step lets the test run wait for a given amount of time (in milliseconds). During the sleep no action will be performed and the subsequent steps are postponed respectively.

The above step performs a sleep with the default time of 5000 milliseconds.

You can also provide the duration to sleep in milliseconds or ISO 8601 format.

The step receives a numeric parameter that represents the amount of time (in milliseconds) to wait.

The Camel context is a central place to add routes and manage Camel capabilities and services. You can start a new default (empty) Camel context using the following step.

This will setup and start a new Camel context as part og the current test scenario. You can now create and add routes to this context. In case you have special configuration and/or some default routes that you need to initialize as part of the context you can provide a Camel Spring bean configuration in the Camel context step.

In Apache Camel you need to create routes in order to start producing/consuming data from endpoints. The routes can be defined in XML or Groovy.

In addition to XML route definitions YAKS also supports the Groovy DSL.

The above steps create the Camel routes and automatically starts them in the current context. The given routes start to consume messages from the endpoint direct:hello.

We are able to explicitly start and stop routes in the current context.

The given name references a route in the current Camel context. This starts the route and consumes messages from the enpoint URI.

After stopping a route the route will not consume any messages on the given endpoint URI.

In case a Camel route is not needed anymore you can also remove it from the current Camel context.

We can send exchanges using any Camel endpoint URI. The endpoint URI can point to an external component or to a route in the current Camel context and trigger its processing logic. The exchange body is given as single or multiline body content.

The step sends an exchange with the body Hello Camel!. You can also use multiline body content with the following step:

In addition to a body content the Camel exchange also defines a set of message headers. You can use a data table to specify message headers when sending a message.

The YAKS test is able to receive messages from a Camel endpoint URI in order to verify the message content (header and body) with an expected control message.

Once the message is received YAKS makes use of the powerful message validation capabilities of Citrus to make sure that the content is as expected.

The step receives an exchange from the endpoint URI seda:tokens and verifies the body to be equal to Hello. See the next example on how to validate a multiline message body content.

We can also verify a set of message headers that must be present on the received exchange. Once again we use a data table to define the message headers. This time we provide expected message header values.

In the previous steps we have seen how to send and receive messages to anf from Camel endpoint URIs. We have used the exchange body and header in a single step so far.

In some cases it might be a better option to use multiple steps for defining the complete exchange data upfront. The actual send/receive operation then takes place in a separate step.

The following examples should clarify the usage.

@Given("^Camel exchange message header {name}=\"{value}\"$")

This sets a message header on the exchange. We can also use a data table to set multiple headers in one single step:

Then we can also set the body in another step.

Multiline body content is also supported.

When the body is getting too big it may be a better idea to load the content from an external file resource:

This step loads the body content from the given file resource.

Now that we have specified the exchange headers and body content we can send or receive that specific echange in a separate step.

In the previous section we have covered a 2nd approach to send and receive messages with Apache Camel. You specify the exchange in multiple steps first and then send/receive the exchange to/from and endpoint URI in a separate step.

Sets the default timeout for all Camel components that consume data from messaging transports. After that time the test will fail with a timeout exception when no message has been received.

The Apache Camel steps are able to create resources such as routes. By default these resources get removed automatically after the test scenario.

The auto removal of Camel resources can be turned off with the following step.

Usually this step is a Background step for all scenarios in a feature file. This way multiple scenarios can work on the very same Camel resources and share integrations.

There is also a separate step to explicitly enable the auto removal.

By default, all Camel resources are automatically removed after each scenario.

The default Camel K API version used to create and manage resources is v1. You can overwrite this version with a environment variable set on the YAKS configuration.

This sets the Camel K API version for all operations.

Creates a new Camel K integration with specified route DSL. The integration is automatically started and can be referenced with its {name} in other steps.

You can add optional configurations to the Camel K integration such as dependencies, traits and properties.

The route DSL as source for the Camel K integration.

List of Maven coordinates that will be added to the integration runtime as a library.

List of trait configuration that will be added to the integration spec. Each trait configuration value must be in the format traitname.key=value.

List of property bindings added to the integration. Each value must be in the format key=value.

Loads the file {name}.groovy as a Camel K integration.

Deletes the Camel K integration with given {name}.

A Camel K integration is run in a normal Kubernetes pod. The pod has a state and is in a phase (e.g. running, stopped). You can verify the state with an expectation.

Checks that the Camel K integration with given {name} is in state running and that the number of replicas is > 0. The step polls the state of the integration for a given amount of attempts with a given delay between attempts. You can adjust the polling settings with:

Watches the log output of a Camel K integration and waits for given {log-message} to be present in the logs. The step polls the logs for a given amount of time. You can adjust the polling configuration with:

You can also wait for a log message to not be present in the output. Just use this step:

The Camel K steps are able to create resources such as integrations. By default these resources get removed automatically after the test scenario.

The auto removal of Camel K resources can be turned off with the following step.

Usually this step is a Background step for all scenarios in a feature file. This way multiple scenarios can work on the very same Camel K resources and share integrations.

There is also a separate step to explicitly enable the auto removal.

By default, all Camel K resources are automatically removed after each scenario.

The default Kamelet API version used to create and manage resources is v1alpha1. You can overwrite this version with a environment variable set on the YAKS configuration.

This sets the Kamelet API version for all operations.

A Kamelets defines a set of properties and specifications that you can set with separate steps in your feature. Each of the following steps set a specific property on the Kamelet. Once you are done with the Kamelet specification you are able to create the Kamelet in the current namespace.

First of all you can specify the media type of the available slots (in, out and error) in the Kamelet.

The Kamelet can use a title that you set with the following step.

Each template uses an endpoint uri and defines a set of steps that get called when the Kamelet processing takes place. The following step defines a template on the current Kamelet.

The template uses two properties {{message}} and {{period}}. These placeholders need to be provided by the Kamelet user. The next step defines the property message in detail:

The property receives specification such as type, required and an example. In addition to the example you can set a default value for the property.

In addition to using a template on the Kamelet you can add multiple sources to the Kamelet.

The previous steps defined all properties and Kamelet specifications so now you are ready to create the Kamelet in the current namespace.

The Kamelet requires a unique name. Creating a Kamelet means that a new custom resource of type Kamelet is created. As a variation you can also set the template when creating the Kamelet.

This creates the Kamelet in the current namespace.

You can create new Kamelets by giving the complete specification in an external YAML file. The step loads the file content and creates the Kamelet in the current namespace.

Loads the file {name}.kamelet.yaml as a Kamelet. At the moment only kamelet.yaml source file extension is supported.

Deletes the Kamelet with given {name} from the current namespace.

Verifies that the Kamelet custom resource is available in the current namespace.

YAKS provides multiple steps that bind a Kamelet source to a sink. The binding is going to forward all messages processed by the source to the sink.

You can create new KameletBindings by giving the complete specification in an external YAML file. The step loads the file content and creates the KameletBinding in the current namespace.

Loads the file {name}.yaml as a KameletBinding. At the moment YAKS only supports .yaml source files.

Deletes the KameletBinding with given {name} from the current namespace.

Verifies that the KameletBinding custom resource is available in the current namespace.

The described steps are able to create Kamelet resources on the current Kubernetes namespace. By default these resources get removed automatically after the test scenario.

The auto removal of Kamelet resources can be turned off with the following step.

Usually this step is a Background step for all scenarios in a feature file. This way multiple scenarios can work on the very same Kamelet resources and share integrations.

There is also a separate step to explicitly enable the auto removal.

By default, all Kamelet resources are automatically removed after each scenario.

YAKS uses Citrus components behind the scenes. The Citrus components are configurable through a Groovy domain specific language. You can add endpoints and other components as Citrus framework configuration like follows:

In the next example the step uses a Groovy domain specific language to define a new Http server endpoint.

The configuration step creates a new Citrus endpoint named helloServer with given properties (port, autoStart) in form of a Groovy configuration script. The endpoint is a Http server Citrus component that is automatically started listening on the given port. In the following the scenario can send messages to that server endpoint.

The Groovy configuration script adds Citrus components to the test context and supports following elements:

Let’s quickly have a look at a bean configuration where a new JDBC data source is added to the test suite.

The data source will be added as a bean named dataSource and can be referenced in all Citrus SQL test actions.

All Groovy configuration scripts that we have seen so far can also be loaded from external file resources, too.

The file content is loaded as a Groovy configuration DSL. The next code sample shows such a configuration script.

Endpoints describe an essential part in terms of messaging integration during a test. There are multiple ways to add custom endpoints to a test. Endpoint Groovy scripts is one comfortable way to add custom endpoint configurations in a test scenario. You can do so with the following step.

The step receives a unique name for the endpoint and a Groovy DSL that sepcifies the endpoint component with all its properties. In the following sample a new Http server endpoint component will be created.

The scenario creates a new Http server endpoint named helloServer. This server component can be used directly in the scenario to receive and verify messages sent to that endpoint.

You can also load the endpoint configuration from an external file resources.

The referenced file should contain the endpoint Groovy DSL.

YAKS provides a huge set of predefined test actions that users can add to the Gherkin feature files out of the box. However, there might be situations where you want to run a customized test action code as a step in your feature scenario.

With the Groovy script support in YAKS you can add such customized test actions via script snippets:

The Groovy test action DSL script receives a unique {name}. You can reference this name later in the test in order to apply the defined actions. When applied to the test the defined actions are executed. A sample will show how it is done.

The example above defines the test actions with the Groovy DSL under the name basic.groovy. Later in the test the actions are executed with the apply step.

Users familiar with Citrus will notice immediately that the action script is using the Citrus actions DSL to describe what should be done when running the Groovy script as part of the test.

The Citrus action DSL is quite powerful and allows you to perform complex actions such as iterations, conditionals and send/receive operations as shown in the next sample.

As an alternative to write the Groovy DSL directly into the test feature file you can also laod the test action script from external file resources.

The file name is the name of the action script. So you can use the file name to apply the script in the test for execution.

You can also use a shortcut syntax to directly call a test action.

This will add a new echo test action and run the action. The action code uses a Groovy script that defines the test action by using the common Citrus test action domain specific language.

You can apply multiline scripts directly, too.

Sometimes it is mandatory to cleanup test data after a scenario. It would be good to have a set of test actions that get executed in a guaranteed way - even in case the test scenario failed with errors before.

The Citrus framework provides a concept of finally block actions. These actions will be run after the test in all circumstances (success and failure).

As an alternative syntax you can add a 'doFinally()' test action to your script.

This is how you can define test actions in Groovy that get executed after the test.

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

The given URL points to a server endpoint. All further client Http steps send the requests to that endpoint.

As an alternative you can reference a Http client component that previously has been added to the framework configuration.

This step loads a Http client component by its name and uses that for further requests.

Once you have configured the Http endpoint URL or the Http client you can start sending request messages.

Sending requests via Http is as easy as choosing the Http method (GET, POST, PUT, DELETE, …​) to use.

The given path resides to a valid resource on the server endpoint. The resource path is added to the base URL and identifies the resource on the server.

You can choose the Http method that should be used to send the request (e.g. GET). Of course the request can have headers and a message body. You need to set these before sending the request in separate steps.

In the previous section several steps have defined the Http request (header, parameter, body) before sending the message in a separate step. As an alternative to this approach you can also specify the complete Http request data in a single step.

The next example shows the complete Http request data step:

The time you send out a Http request you will be provided with a response from the server. YAKS is able to verify the Http response content in order to make sure that the server has processed the request as expected.

The most critical part of the Http response is thee status code (e.g. 200, 404, 500). The status code should refer to the success or error of the request. The server can use a wide range of Http status codes that are categorized as follows, also see W3C.

The reason phrase OK is optional and is also not part of the verification mechanism for the response. It just gives human readers a better understanding of the status code.

Of course the Http response can also have headers and a message body. YAKS is able to verify those response data, too. Please define the expected headers and body content before verifying the status code.

In the previous section several steps have defined the Http response (header, parameter, body) before verifying the message received. As an alternative to this approach you can also specify the complete expected Http response data in a single step.

The next example shows the complete Http response data step:

When verifying Http client responses sent by the server you can use JsonPath expressions to validate the response message body content.

The step defines a JsonPath expression (e.g. $.person.age) and an expected value. The expression is evaluated against the received response message body and the value is compared to the expected value. This way you can explicitly verify elements in the Json body.

The very same mechanism also applies to XML message body content. Just use a XPath expression instead of JsonPath.

On the server side YAKS needs to start a Http server instance on a given port and listen for incoming requests. The test is able to verify incoming requests and then provide a simulated response message with response headers and body content.

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).

After the request verification has passed the server responds with a simple Http 201 CREATED.

The next sections guide you through the Http server capabilities in YAKS.

When the test run starts YAKS will initialize the Http server instance and listen on a port for incoming requests.

You can define expected incoming Http requests as part of the test.

The incoming request must match the given '{method}` and {path}.

Of course, you can also verify headers and the request message body. You need to specify the expected request before receiving the request with the receive steps.

In the previous section several steps have defined the expected Http request (header, parameter, body). As an alternative to this approach you can also specify the complete Http request data in a single step.

The next example shows the complete Http request data step:

When verifying Http client requests you can use JsonPath expressions to validate the request message body content.

The step defines a JsonPath expression (e.g. $.person.age) and an expected value. The expression is evaluated against the received request message body and the value is compared to the expected value. This way you can explicitly verify elements in the Json body.

The very same mechanism also applies to XML message body content. Just use a XPath expression instead of JsonPath.

The time you have verified a Http request as a server you need to provided a proper response to the calling client. YAKS is able to simulate the Http response content.

The step defines the Http response status code (e.g. 200, 404, 500) to return.

The reason phrase OK is optional. It just gives human readers a better understanding of the status code returned.

Of course the Http response can also have headers and a message body. YAKS is able to simulate this response data, too.

In the previous section several steps have defined the Http response (header, parameter, body). As an alternative to this approach you can also specify the complete Http response data in a single step.

The next example shows the complete Http response data step:

Often Http server provide a health endpoint so clients can check the status of the server to be up and running. The health check is supported with the following steps.

The step performs a health check on the given {URL} by sending a request to the endpoint and checking for a response status code marking success (200 OK).

Instead of specifying the complete health check URL you can make use of the base URL given in the central Http step.

The given path is added to the base URL and should resolve to the health check resource on the server (e.g. /health).

The steps above perform the health check only a single time. Based on the provided Http server response status the step passes or fails. In some cases can not make sure that the server has been started yet and the health check might fail occasionally. In these cases it is a good iodea to use the wait health check step.

The step will wait for given URL to return a 200 OK response. The step is actively waiting while polling the URL multiple times when the response is not positive. By default this step uses a HEAD request. You can explicitly choose another Http method, too.

The sample above uses a GET request for the health checks.

Also you can explicitly specify the expected return code that must match in order to pass the wait health check.

Once again the {reason_phrase} is optional and only for better readability reasons.

Last not least you can specify the request method on the wait operation, too.

This completes the health check capabilities in the Http steps.

YAKS steps support secure Http connections on both client and server.

On the client side enabling secure Http connection is as simple as defining a request URL with https scheme.

YAKS is going to initialize the client with a SSL request factory and use secure Http connections.

On the server side you have to enable secure Http with the following step:

Please use this step before starting the server with:

The secure SSL connector uses the port 8443 by default. You can adjust this secure port with:

The Http server uses a default SSL keystore with a self signed certificate. Users are able to customize the server certificate with a custom SSL keystore.

The steps set a custom keystore (e.g. server.jks) file and a custom keystore password.

The keystore settings are also accessible via environment variables.

The Http server components also provide a convenient way to add server properties when creating new instances:

Before running any SQL statement you need to configure a datasource that allows connecting to the database.

The step configures a new database connection and uses a data table to define connection properties such as connection URL, username and password.

This defines the connection parameters so the test is able to connect to the database.

In addition to that you can also reference an existing datasource that has been added to the framework configuration.

The name of the datasource should reference a configured component in the test project. You can add components as Spring beans for instance.

The test is able to run SQL updates (UPDATE, INSERT, DELETE) on the database.

The step executes the given SQL statement using the configured database connection. For multiline statements please use:

You can also run multiple statements in a single step by using a data table.

The SQL query obtains data from the database in form of result sets. The YAKS test is able to verify the result sets with an expected set of rows and column values returned.

This step defines the query to execute. Multiline SQL query statements are supported, too.

You can also run multiple queries in one step. As usual the step uses a data table.

In a next step you can provide the expected outcome in form of column name and value.

For more complex result set validation you can use a Groovy result set verification script.

The Groovy script can work with the complete result set and is quite powerful.

The JMS standard requires clients to open connections over a connection factory. The connection factory is a vendor specific implementation and receives a set of properties such as connection URL, username and password.

The configuration step receives a data table that defines the connection settings.

The connection factory type is vendor specific and depends on what kind of message broker you are using in your environment. Please make sure to add the respective client library as a project dependency in the YAKS configuration.

Sensitive values such as username and password can be set with a test variable placeholder. The variable value can be set by a secret in Kubernetes/Openshift. This ensures to not share sensitive data in the public.

As an alternative to defining the connection factory as part of the test steps you can load a predefined connection factory component from the configuration.

The step references a connection factory component that has been added to the framework configuration (e.g. as Spring bean). This way you can share the connection factory in multiple tests.

In addition to the connection factory the test needs to specify the JMS destination (queue or topic) to use.

This sets the destination name for the next steps. As an alternative to that you can also reference a predefined endpoint component from the configuration.

The step tries to resolve the JMS endpoint with given {name} in the available configuration. The endpoint has a destination set and references a connection factory on its own.

So now the test is ready to produce and consume messages from JMS destinations.

A test can publish messages on a JMS destination. The message consists of message headers and a body content. Before sending a message the tests needs to specify the message content.

Similar to sending messages to a JMS destination the test can also consume messages from a queue or topic. When the message has been received a validation mechanism makes sure that the message content received matches the expectations.

Users are able to provide expected message headers and body content in order to verify the received message.

First of all the test needs to connect to Kafka bootstrap servers. The connection provides several parameters that you can set with the following step.

The configuration step receives a data table that defines the connection settings.

The most important part of the connection settings is the url that points to one or more Kafka bootstrap servers.

In addition to the connection settings there is a set of producer and consumer properties that you can set in order to configure the behavior of producers and consumers connecting with Kafka.

The available properties to set here are described in the Apache Kafka documentation. See the following example how to set producer and consumer properties.

In addition to the connection the test needs to specify the Kafka topic to use.

This sets the topic name for the next steps. As an alternative to that you can also reference a predefined endpoint component from the configuration.

The step tries to resolve the Kafka endpoint with given {name} in the available configuration. The endpoint can reference a topic set and connection settings on its own.

So now the test is ready to produce and consume events from Kafka topics.

A test can publish events on a Kafka topic. The event consists of message headers and a body content. Before sending an event the tests needs to specify the message content.

Similar to publishing events to a Kafka topic the test can also consume events from an event stream. When the event has been received a validation mechanism makes sure that the message content received matches the expectations.

Users are able to provide expected message headers and body content in order to verify the received event.

The Kafka standard provides a set of special configuration that you can set as part of the test.

This set the topic partition for all further steps publishing or consuming events from that topic.

The default Kubernetes API version used to create and manage resources is v1. You can overwrite this version with an environment variable set on the YAKS configuration.

This sets the Kubernetes API version for all operations.

This sets the timeout for all Kubernetes client operations.

Kubernetes uses the concept of namespaces to separate workloads on the cluster. You can connect to a specific namespace with the follwing step.

A Kubernetes pod has a state and is in a phase (e.g. running, stopped). You can verify the state with an expectation.

Checks that the Kubernetes pod with given {name} is in state running and that the number of replicas is > 0. The step polls the state of the pod for a given amount of attempts with a given delay between attempts. You can adjust the polling settings with:

Instead of identifying the pod by its name you can also filter the pod with a label expression. The expression is a label key and value that identifies the pod in the current namespace.

Watches the log output of a Kubernetes pod and waits for given {log-message} to be present in the logs. The step polls the logs for a given amount of time. You can adjust the polling configuration with:

You can also wait for a log message to not be present in the output. Just use this step:

One of the most important features in the YAKS Kubernetes support is the management of services and in particular the automatic deployment of simulated services in Kubernetes.

The user is able to start a local Http server instance and create a service in Kubernetes out of it. This way the test is able to simulate services in Kubernetes and receive and verify incoming requests as part of the test.

First of all we define a new service within the test.

This initializes a new Http server that will be used as Kubernetes service. The server is listening on a default port 8080. You can use another port.

In the following the test is able to create a new Kubernetes service with that Http server.

The step creates the service in the Kubernetes namespace and exposes the given service port as target port. Clients are now able to connect to that new service. Each requests on the service will reside in a request in the test pod. The test is able to receive the request and verify its content as usual.

This way we can easily simulate Kubernetes services in the current namespace.

In case you need to use another target port you can adjust the port as follows.

This exposes the service with the given target port.

In case you do not need the service anymore you can delete it with this step:

Secrets are resources that hold sensitive data. Other resources on the cluster can mount the secret content and access it.

You can create secrets in the current namespace in multiple ways.

The step receives a secret name and a data table holding the property keys and values. These properties build the content of the secret.

Instead of listing all properties in the test itself you can load the secret from an external property file.

The step loads the property file and creates the secret from the file content. The file name is used as the name fo the secret.

In case you want to clean up the secret you can delete it with:

Sometimes secrets need to have labels and/or annotations that mark the secret with important metadata. You can add labels/annotations on the Kubernetes resource with these steps:

Or use multiple labels/annotations in one single step:

In the previous sections the test has creates services and secrets as Kubernetes resources. In addition to that the test is able to apply any resource as a YAML file on the Kubernetes cluster.

With this step you can apply any Kubernetes resource as a YAML file.

The step above creates a new pod resource with the given specification. Instead of adding the resource specification in the test itself you can also load an external YAML file.

In case you need to delete a resource you can do so by specifying the minimal resource as a YAML specification.

You can also provide the external YAML file when deleting a resource. The step will automatically extract the resource kind and name from the file content.

In the previous sections the test has created Kubernetes resources (pods, services, secrets, deployments, …​). The user can also define custom resources in order to extend Kubernetes. YAKS is also able to manage these custom resources.

The user has to provide a YAML specification of the custom resource.

The step needs to know the {crd} (Custom Resource Definition) of the custom resource. In the example above the test creates a new resource of kind Broker in the custom resource definition brokers.eventing.knative.dev.

Of course, you can also load the custom resource from external file resource.

Once again the step needs to have the CRD type and the YAML specification as a file resource.

Prior to using the custom resource in a YAKS test you need to grant role permissions to the YAKS runtime. Otherwise, the test is not allowed to create the custom resource due to security constraints on the cluster.

The YAKS runtime uses a service account yaks-viewer to run the test. The service account needs to have proper roles and permissions for managing the custom resource.

The YAKS operator uses another service account yaks-operator. This service account needs to have the same permissions on the custom resource, too. This is because the operator manages the yaks-viewer service account in a specific namespace. When using temporary namespaces as a test runtime the YAKS operator will create the yaks-viewer service account and its roles and permissions on the fly.

Assume that there is a CRD foos.yaks.dev and you want to manage the resources in your test:

The role to manage the new CRD foos.yaks.dev would be:

The role yaks-operator-foo is granted to create/delete/get/list/update custom resources of type foos.yaks.dev.

You also need a role binding to the yaks-operator service account:

You can use the YAKS command line tool to properly add the role and role binding on the YAKS operator:

The commands above create the role and role bindings on the yaks-operator service account. The command automatically covers all available operator instances on the cluster. Also, the command will automatically convert the role to a cluster role when there is a global operator on the cluster.

Both role resources use a specific label yaks.citrusframework.org/append-to-viewer: "true". This makes sure that the YAKS operator adds the permissions also to the yaks-viewer account. This is done automatically when the operator starts a new test.

As a naming convention the roles and role bindings targeting on the YAKS operator use the yaks-operator- name prefix.

In case you want to make use of temporary namespaces you need to add the roles to the runtime configuration of the test. This is because the operator for the temporary namespace will not be able to automatically apply the additional operator roles.

Please add the roles to the yaks-config.yaml as follows.

This makes sure that the yaks command line tool installs the roles on the temporary namespace before the test is run.

In case you need to delete a custom resource from Kubernetes the user has to provide a minimal YAML specification that identifies the resource.

As an alternative to that you can use an external file resource that holds the minimal YAML specification.

Custom resources often define a status and describe multiple conditions (e.g. ready, available, completed). You can verify the condition on a custom resource.

The step verifies that the given Kubernetes resource with name {name} describes a status condition {condition}. The step polls the state of the resource for a given amount of attempts with a given delay between attempts. You can adjust the polling settings with:

Assume you have a custom resource like this:

The custom resource defines a status with multiple conditions. You can wait for a condition in the test.

The expected condition is Ready for the resource named my-foo-resource. The resource name can use a prefix that represents the kind information foo/. The kind helps to identify the custom resource. Also the step defines the resource type foos.yaks.dev and version v1. This is required to identify the custom resource on the cluster.

Instead of identifying the resource by its name you can also filter the resources with a label expression. The expression is a label key and value that identifies the resource in the current namespace.

This will get all resources of type {type} and filter by given label {key}={value}. Then the given condition is verified on the resource.

The described steps are able to create Kubernetes resources on the current Kubernetes namespace. By default these resources get removed automatically after the test scenario.

The auto removal of Kubernetes resources can be turned off with the following step.

Usually this step is a Background step for all scenarios in a feature file. This way multiple scenarios can work on the very same Kubernetes resources.

There is also a separate step to explicitly enable the auto removal.

By default, all Kubernetes resources are automatically removed after each scenario.

The default Knative API version used to create and manage resources is v1beta1. You can overwrite this version with a environment variable set on the YAKS configuration.

This sets the Knative API version for all operations.

This sets the timeout for all Knative client operations.

Knative uses the concept of namespaces to separate workloads on the cluster. You can connect to a specific namespace with the follwing step.

Eventing deals with publish/subscribe delivery of events in Knative. Knative eventing uses a broker that manages channels, subscriptions and events.

This sets the broker name to use in all further steps that publish and consume events. The broker should already be present on the Kubernetes namespace. In case there is no broker yet you can create one.

The step creates a new broker with the given {name}. The broker uses the default settings given in the Knative platform.

You can verify that the broker is up and running with the following step:

The Knative broker delivers events to sinks. In order to start consuming events in a test you should create a event consumer service which acts as a sink.

This step creates a new event consumer service. In particular this step creates a new Kubernetes service. The service instantiates a new local Http server and creates a new Kubernetes service from it. The service exposes a port which is 8080 by default.

You can adjust the service port as follows:

By default the Kubernetes service uses the service port as a target port when exposing the service. You can choose another target port, too.

Triggers are used to deliver events to services and channels. In YAKS users can create a trigger as part of the test in order to start consuming events.

Channels represent a central concept of Knative eventing. Channels are able to deliver events to multiple subscribers. A test in YAKS is able to create new channels.

Once the channel is available you can subscribe a service to the channel.

The test is able to publish events on the Knative broker. YAKS uses the Knative Http client API to publish events on the broker.

Because of that the test needs to specify a proper broker URL before publishing any events.

In order to receive events from Knative you should setup a service or channel in combination with a trigger. The trigger watches for events on the broker and forwards these to the service or channel.

The test is able to receive events and verify its content.

The described steps are able to create Knative resources on the current Kubernetes namespace. By default these resources get removed automatically after the test scenario.

The auto removal of Knative resources can be turned off with the following step.

Usually this step is a Background step for all scenarios in a feature file. This way multiple scenarios can work on the very same Knative resources and share integrations.

There is also a separate step to explicitly enable the auto removal.

By default, all Knative resources are automatically removed after each scenario.

The test is able to load OpenAPI specifications via Http URL or the local file system. When loaded into the test steps can make use of all available operations in the specification.

The given url can point to a local file on the file system or to a Http endpoint. The step loads the OpenAPI specification so all operations are ready to be used.

You can invoke operations as a client by referencing the operation name given in the specification. YAKS loads the operation from the specification and automatically generates proper request/response data for you.

The rules in the OpenAPI specification define how to generate proper test data with randomized values.

The step obtains the operation with the given {id} and invokes it on the Http URL that is given in the specification. In case the server URL is missing in the specification the step uses the base URL of the OpenAPI endpoint where the document has been loaded from.

The step uses the specification rules for the operation to generate a proper request for you. Request parameters, headers and body content are automatically generated. In case the operation defines a request body the step will also generate it with randomized values.

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.

Now that the test has sent the request you can verify the operation result in a next step.

The test is able to verify the response status code returned by the server.

The step expects a {status_code} (e.g. 200, 404, 500) and optionally gives the {reason_phrase} (e.g. OK, NOT_FOUND, INTERNAL_SERVER_ERROR). Thee reason phrase is optional and is only for better readability reasons.

The operation defines a set of responses in the OpenAPI specification. The step tries to find the response with the given {status_code} and reads the given rules such as response body, headers etc. Based on the response definition in the OpenAPI specification the step automatically verifies the server reponse and makes sure that the response matches the given rules.

In particular the step generates an expected response body (if any is specified) and compares the actual response with the generated one.

The generated response makes use of Citrus validation matchers based on the rules in the specification. Id values are validated with @isNumber()@, String values should not be empty @notEmpty()@ and enumeration values are checked with @matches(value_1|value_2|…​|value_x)@.

The received response must match all these validation matchers. In addition to that a Json schema validation is performed on the response.

On the server side your test is able to verify incoming requests based on the rules in the specification. The test references a given operation by its name in the specification and generates proper verification steps on the request content. Based on the specification the incoming request must follow the rules and schemas attached to the OpenAPI operation.

The step expects a request matching the operation with the given {id}. The step loads the operation from the specification and autoamtically verifies that the incoming request matches the specified request.

In fact the step generates a request body (if any is specified on the operation) with validation expressions and compares the incoming request with the generated template. In case the incoming request does not match the generated validation rules the test will fail accordingly.

The generated request uses Citrus validation matchers based on the rules in the OpenAPI specification. Identifiers are validated with @isNumber()@, String values should not be empty @notEmpty()@ and enumeration values are checked with @matches(value_1|value_2|…​|value_x)@.

This way you can make sure that the incoming request matches the rules defined in the OpenAPI specification. In addition to the message request body verification the step will automatically verify Content-Type headers, path parameters, query parameters and the general request path used.

When the OpenAPI step has received and verified a request it is time to respond with proper message content. The given operation in the OpenAPI specification is able to define multiple response messages that are valid. In the test the user picks one of these response messages and the step generates the message content based on the specification.

The step will generate proper test data with randomized values as response body.

The step obtains the operation response with the status 201 and generates the response data. The response is able to define Content-Type headers and response body content.

The generated response 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.

The YAKS OpenAPI steps use the information in the specification to generate proper message content for requests and responses. The generated test data follows the schemas attached to the operations and response definitions. By default, the steps include optional fields when generating and validating message contents.

You can disable the optional fields in generation and validation accordingly:

With this setting the OpenAPI steps will exclude optional fields from both test data generation and message content validation.

Data dictionaries are a good way to make generated randomized values more human readable. By default YAKS generates random values based on the specifications in the OpenAPI document. You can overwrite the basic generation rules by specifying rules in a data dictionary.

When the OpenAPI steps fire requests to the server the step synchronously waits for the response. All other steps are in the feature are blocked by the synchronous communication. In some cases this is a problem because you might want to run some steps in parallel to the synchronous communication.

In these cases you can make use of the form mode when sending Http client requests.

With this in place the step will not block other steps while waiting for the synchronous response from the server. The feature will continue with the next steps when fork mode is enabled. At a later point in time you may verify the response as usual with the separate verification step.

Selenium supports many browsers. When running a YAKS test with Selenium you need to choose which browser type to use. By default, YAKS uses the htmlunit browser type. You can overwrite this type with the system property yaks.selenium.browser.type or environment variable YAKS_SELENIUM_BROWSER_TYPE set on the YAKS configuration.

These are the supported browser types:

This sets the Selenium browser type for all operations.

YAKS creates a default browser component using the given browser type. You can also create a browser instance by yourself and reference this in your test by its name.

This loads the browser component with given name from the configuration (e.g. Spring application context).

You can also use the system property yaks.selenium.browser.name environment variable YAKS_SELENIUM_BROWSER_NAME

As soon as the YAKS test is run on a Kubernetes environment you must use a remote web driver. This is because the default YAKS test runtime pod is not able to run UI tests because no web browser infrastructure is installed in the image.

You can automatically start a Selenium sidecar container as part of the test runtime pod. The Selenium images provide the required web browser infrastructure for UI testing. YAKS adds the Selenium container as a sidecar to the test runtime. Now your test is able to connect with the remote browser using a remote web driver connection.

Add the following configuration to the yaks-config.yaml in your test.

This sets the Selenium container image (selenium/standalone-chrome:88.0), the browser type and the remote web driver URL. YAKS automatically starts the given Selenium container image and connects the browser to the remote web driver.

This way you can run the UI tests in a Kubernetes environment.

Before you can run some user interactions with Selenium you need to start the browser.

See the following step that navigates to a given URL in the browser.

Selenium is able to verify web elements on the current page. You can select the element by its attributes (e.g. id, name, style) and verify its properties (e.g. text value, styles).

This step verifies that the given element of type {element-type} is present on the current web page. The element is selected by the given {attribute} and {value}.

Possible element types are:

Possible attributes to select the element are:

You can add additional attribute validations in a data table

You can click on elements such as buttons or links. The element must be identified by an attribute (e.g. id, name, style) with a given value.

Filling out a user form on a web page is a very common use case in UI testing. YAKS is able to enter text into input fields, select items from a drop down list and check/uncheck checkboxes.

Web pages can open alert dialogs that need to be accepted or dismissed.

You can also verify the alert text displayed to the user.

Selenium provides a good way to encapsulate web page capabilities in form of page objects. These object usually defines elements on a web page and perform predefined operations on that page.

The page object above defines a form element as well as a username input text field. The page identifies the elements with @FindBy annotations. In addition, the page defines operations such as setUserName and submit.

YAKS is able to load the page objects by its name in the current configuration (e.g. Spring application context).

The step loads the page object that has been added to the configuration with the given name.

You can also instantiate new page objects by its types as follows:

This loads a new page object of type org.sample.UserFormPage. Please make sure that the given class is available on the test classpath and that the class provides a default constructor.

You can instantiate many web page objects in a single step.

Once the page objects are loaded you can perform operations.

The step uses the given page object userForm and performs the submit operation. This simply calls the submit() method on the page object.

In case the operation requires parameters you can set those on the operation call.

The setUserName operation on the page object requires the username value as a parameter. This value is set as Christoph in the step above.

Each page operation can use the current TestContext as argument, too. This context will be automatically injected by YAKS when the operation is called.

The page operation setUserName uses the TestContext as additional method argument and is able to set a new test variable. All subsequent steps in the test are able to access this new variable with ${username} then.

The previous section has introduced the concept of page objects and how to perform operations on the given page. You can also use page objects to verify the page contents.

The page validator implements the PageValidator<> interface and implements a validate method. The validation is provided with the actual page object, the browser instance and the current test context.

The validator should verify that the current state on the page is as expected.

YAKS is able to load the page validator by its name in the current configuration (e.g. Spring application context).

The step loads the page validator that has been added to the configuration with the given name.

You can also instantiate new page validator objects by its types as follows:

This loads a new page validator of type org.sample.UserFormPageValidator. Please make sure that the given class is available on the test classpath and that the class provides a default constructor.

You can instantiate many web page validator objects in a single step.

Once the page validator objects are loaded you can perform its validations.

The step calls the validate method on the page validator userFormValidator and passes the userForm page object as argument.

The validator accesses the elements and operations provided in the page object and makes sure the state is as expected.

Running Testcontainers in Kubernetes may require privileges on the YAKS service account. This depends on the restrictions and RBAC settings in your cluster.

Be sure to add privileged security context constraint to the yaks-viewer service account in the namespace where tests are run.

This adds the privileged security constraint to the yaks-viewer service account. This is required for the test to start and manage a Testcontainer pod as part of the test.

You can choose from a wide range of database modules provided in Testcontainers. YAKS is able to run these database containers as part of the test.

Configure and manage a PostgreSQL database container.

Configure and manage a MongoDB database container.