Welcome to Intersmash, a Java library that makes it easy to provision and execute (complex) test scenarios on OpenShift.

If you work as an enterprise application developer, runtime components engineer, quality engineer or in DevOps, Intersmash will help you prototype and test complex interoperability scenarios on cloud-native environments and platforms, most notably on OpenShift (and on Kubernetes as well, soon :) ).

Through a convenient set of annotations and APIs, Intersmash provides the developer with tools to describe and deploy services and to manage their life-cycle orchestration directly from the test class.

Intersmash has been designed to provide components that interact in the context of a testing workflow in order to:

1. provision a products' stack environment, i.e. the scenario
2. execute tests in order to validate the behavior of the scenario

There are three main components on which this design is based:

• annotations: describes the scenario and the services it's made of. These statements are declared in the test class.

• applications: interface implementations that describe the configuration and specific properties of a given service that belongs to a scenario.

• provisioners: takes care of and controls the specific workflow that needs to be executed for the given products that a scenario consists of. See the Intersmash provisioning documentation to learn about supported services provisioners.

Two intersmash archives provide the three components described above. The dependencies are added to the project configuration, e.g.:

<dependencies>
  <dependency>
    <groupId>org.jboss.intersmash</groupId>
    <artifactId>intersmash-tools-core</artifactId>
  </dependency>
  <dependency>
      <groupId>org.jboss.intersmash</groupId>
      <artifactId>intersmash-tools-provisioners</artifactId>
  </dependency>
</dependencies>

The following is an example of a test:

@Intersmash({
        // 1
        @Service(PostgresqlApplication.class),
        @Service(OpenShiftWildflyApp.class)
    }
)
public class SampleTest {
    @ServiceUrl(OpenShiftWildflyApp.class) // 2
    private String wildflyRouteUrl;

    @ServiceProvisioner(OpenShiftWildflyApp.class) // 3
    private OpenShiftProvisioner wildflyOpenShiftProvisioner;

    @Test
    public void test() {
        // Do your thing.
    }
}

• 1: The applications/products used in the test are listed as @Service items within the @Intersmash annotation. Each of the mentioned classes provides the platform-specific configuration for the given application/product. You may deploy the application on some server (Wildfly), setup services that don't require a deployment, or just deploy a database.
• 2: To inject information about the application into the test, the tooling layer provides several annotations. The application class must match the class declared in the @Service annotation in point #1. @ServiceUrl provides support to inject into a String or a URL type field, the address of the service. Beware, some applications (e.g. DB running on OpenShift) might not provide @ServiceUrl as there is no route to them created.
• 3: Should you need control over platform-specific actions, you can also inject a provisioner via the @ServiceProvisioner annotation. This will enable you to, for example, scale your deployment up and down.

In the most common use cases, you just need to implement the correct Application interface and pass the class via the@Service annotation. It's the task for the framework to choose a suitable Provisioner implementation (an exception will be thrown in case no suitable Provisioner was yet implemented).

The following snippet represents the PostgresqlApplication class that is being used by the previously detailed test class:

public class PostgresqlApplication implements PostgreSQLTemplateOpenShiftApplication {
	static String NAME = "postgresql";

	@Override
	public PostgreSQLTemplate getTemplate() {
		return PostgreSQLTemplate.POSTGRESQL_EPHEMERAL;
	}

	@Override
	public String getName() {
		return NAME;
	}
}

• Simple build, will build the project's components including the deployments module. That module has WildFly deployments that are used by the testsuite with default - i.e. community artifacts:

mvn clean install -DskipTests

• By building with the wildfly-deployments-build.eap profile, the WildFly deployments will instead be built by using productised bits configuration:

mvn clean install -DskipTests -Pwildfly-deployments-build.eap

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

mvn test -pl testsuite/ -Pts.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.prod

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

• Intersmash is using XTF to communicate with OpenShift cluster for the OpenShift cloud environment. The XTFConfig class is also used internally, properties are resolved as following: System Properties > Environment Properties > test.properties file > global-test.properties, see https://github.com/xtf-cz/xtf#configuration for more details on this.

• The following properties can be used to configure Intersmash build and test execution, see the CI checks e2e tests script as an example:

[*] - When intersmash.skip.deploy is set, please take into account that the prepared environment should be configured accordingly to the Application descriptors which are defined by the test class @Service annotations. E.g.: if a test class defines an WildflyOperatorApplication as one of its services, and such application sets the name to be "wildfly-operator-app", then a Wildfly operator application with such a name should exist in the prepared environment. This feature is useful to save debugging time during development, where you can deploy a complex scenario and then enable the property to just execute tests in the following runs.

• Although Intersmash is designed to allow executions on different platforms, at the moment we fully focus on OpenShift support.

• Intersmash Framework tooling modules support Java 11 language features, and the compiled code is set to be compliant with such version as well.

The Intersmash repository hosts several modules which are meant to provide core APIs (tools/intersmash-tools-core), tooling implementation (tools/intersmash-tools-provisioners), shared deployments (deployments), a testsuite (testsuite) and examples (demos).

• Tools (tools) - set of core components for platform configuration and application deployment.
  • intersmash-tools-core - core interfaces, annotations and extensions.
  • intersmash-tools-provisioners - implementations of interfaces from core for selected services.
• Testsuite - tests that verify the integration with OpenShift, hence a cluster is needed.
• Deployments (deployments) - sources for shared deployments which are used by the testsuite. Moreover, the intersmash-deployments-provider submodule provides support to get path to compiled deployments. Or you can get any deployment by GAV.
• Demos - examples that illustrate how to integrate Intersmash.

The Intersmash tooling modules are configured to generate both sources and Javadoc JAR artifacts each time they're built.

The doc profiles must be activated in order to produce the sources and Javadoc artifacts, e.g.:

mvn clean install -DskipTests -Pdoc

a new directory, namely apidocs, is generated inside the target directory of both intersmash-tools-core and intersmash-tools-provisioners, and HTML files containing the Javadoc are added to it.

In the target directory two additional artifacts are generated, the sources and Javadoc artifacts. For instance, for intersmash-tools-provisioner the following artifacts are generated:

• intersmash-tools-provisioners-<version>.jar - Actual provisioners implementation
• intersmash-tools-provisioners-<version>-sources.jar - Unzip to get the sources or use in your IDE
• intersmash-tools-provisioners-<version>-javadoc.jar - unzip to get Javadoc

The Intersmash Library project is configured to publish some artifacts to the public Maven repository, so that external projects can access them, e.g.: the intersmash-tools-core.jar artifact which contains the @Intersmash annotation definition.

Just run:

mvn clean deploy -DskipTests 

See Intersmash contributing guidelines.

• Kubernetes support
• Quarkus provisioning

See Intersmash contributing guidelines.