Intersmash - Cloud-native testing with Java

Intersmash is a Java library that makes it easy to automate the provisioning and execution of tests in cloud-native environments. It helps the user prototype and test complex interoperability scenarios on kubernetes compliant cloud-native environments and platforms, most notably OpenShift. (Other Kubernetes implementations will be supported in the future.)

Intersmash is designed with these principles.

• It is integrated with JUnit.
• It handles all the plumbing (i.e. provisioning) of the cloud container. It deploys the test scenario product components, manages their life-cycle orchestration, and undeploys and cleans up the environment on test completion. (The term services and product components will be used interchangeably.)
• Intersmash is designed to be extensible. If there is a cloud service not yet implemented, the user can easily create an implementation and integrate it into the framework.
• The framework is cloud implementation agnostic. It will be possible (in the future) to test on different Kubernetes compliant cloud implementations. This will ensure application portability.

For usage examples, see Getting Started.

Framework Design

Intersmash provides a set of annotations, APIs and application service contracts the developer uses to describe the test scenario, within the test class. This information is used by the framework to deploy the services and to manage their life-cycle orchestration directly from the test class. A curated list of service "provisioners" is provided to cover the most common use cases, for example provisioning the Kafka Operator, or a PostgreSql service via templates, or a s2i build and deploy a WildFly application. The full list of provided services can be found here.

Components

There are three main components that make up the framework:

• annotations: Intersmash annotations are used to declare the product components that make up the test scenario. These statements can be applied to the test class and its fields.

  There are four annotations

  • @Intersmash: applied to the test class level definition, contains a list of identified services that make up the test scenario.
  • @Service: the class reference to an individual service
  • @ServiceUrl: applied to a given test class field, injects into the test class as a String or URL the address of a service
  • @ServiceProvisioner: applied to a given test class field, injects into the test class a provisioner that enables control over platform-specific actions or example, scaling the deployment up and down.

• applications: An Intersmash provided interface that describes the configuration and specific properties of a given service. For every supported product component there is a corresponding "application" interface class. The Framework's naming convention for these classes is ProductComponentNameApplication.java. (e.g. BootableJarOpenShiftApplication.java, ActiveMQOperatorApplication.java HelmChartOpenShiftApplication.java, ... etc) The interface provides default values for most of the service's configuration information. The user is required to create an implementation class of the interface and provide some select information. It is this user created implemented class that is declared in the annotations, @Service, @ServiceUrl, and @ServiceProvisioner.

• provisioners: Classes that take care of deploying, undeploying, managing the life-cycle orchestration of services, and control the specific workflow that needs to be executed for the test scenario. The user has no direct interaction with these classes. See the Intersmash provisioning documentation to learn about supported services provisioners.

Properties

XTF is used by Intersmash to communicate with OpenShift. This tool provides a means to pass configuration properties from Intersmash to OpenShift. Intersmash also uses class, XTFConfig, internally. XTF supports four ways to provide properties. In priority order they are,

• System properties
• Environment variables
• test.properties file: residing by default in the root of the project with the goal to contain user specific setup.
• global-test.properties file: residing by default in the root of the project with the goal to contain a shared setup.

A table of properties Intersmash uses to configure and execute tests can be found here.

Maven Dependencies

Two maven archives are needed to build and run with Intersmash.

<dependencies>
  <!-- contains the Intersmash core annotations, contracts and APIs -->
  <dependency>
    <groupId>org.jboss.intersmash</groupId>
    <artifactId>intersmash-core</artifactId>
  </dependency>
  <!-- provisioning implementations and components-->
  <dependency>
      <groupId>org.jboss.intersmash</groupId>
      <artifactId>intersmash-provisioners</artifactId>
  </dependency>
</dependencies>

Building Intersmash

JDK version

JDK-11 is the current version this project supports.

Build the project without running the tests

mvn clean install -DskipTests

Running the Intersmash testsuite

Note: to run the Intersmash testsuite Openshift and XTF properties files with corresponding configuration information are needed. See the Framework Design section above.

• Run the testsuite against community deliverables, e.g.: Keycloak operator or WildFly images:

  mvn test -pl testsuite/ -Pts.execution-profile.community

  This is usually executed to test community images, deliverables and for application servers like WildFly - deployments built from community artifacts.

• Run the testsuite against productised deliverables, e.g.: Red Hat Single Sign On operator or JBoss EAP images:

  mvn test -pl testsuite/ -Pts.execution-profile.prod

  This is usually executed to test productised images, deliverables and - for application servers like JBoss EAP - deployments built from community artifacts.

Project Modules

• core - core interfaces, annotations and extensions.
• provisioners - implementations of interfaces from core for selected services.
• testsuite - tests that verify the integration with OpenShift. (Note: OpenShift is needed in order to run them.)
  • test-deployments - sources for shared deployments which are used by the testsuite.
  • deployments-provider - provides support to get path to compiled deployments
• examples - Test samples that illustrate the use of Intersmash.

Supported services

Intersmash aims at providing tools for provisioning up to the latest stable release generally available. The following table is a best-effort tracker for the version that each supported service has been tested with. That being said, since each service could be provisioned via different means - like templates and operators - having their own release cadence - it could happen that a service version is provisioned which is not the one listed.

Feel free to submit an issue in such a case, Intersmash welcomes community contributions to keep the tooling up to date.

Since multiple deliverables can be bound to a given service version, e.g.: container images, operator CRs, or Helm Charts, more information can be found in the provisioners' documentation, or in the resources there linked.

Platforms

Intersmash is designed to allow executions on different Kubernetes compliant platforms. At the moment we are fully focused on supporting provisioning implementation for OpenShift, running on Linux support. We welcome community contributions to other Kubernetes implementations.

Future goals

• K8s support and Quarkus provisioning
• documentation and examples enhancements

see the current milestone for a complete list of issues.

Issue tracking

To tack or report an issue see GitHub issue.

When reporting an issue please choose the proper template and fill it with the required information.

Contributing

Intersmash is an open source community project. We welcome participation and contributions. See Intersmash contributing guidelines.