Home

Integration in projects

TODO:

• how to add the dependency
• build lifecycle

You can add the IOM Test Framework to your project by adding the following dependency to your maven project's pom.xml:

<dependency>
    <groupId>com.intershop.oms</groupId>
    <artifactId>iom-test-framework</artifactId>
    <version>4.0.0</version>
    <scope>test</scope>
</dependency>

Components

The IOM Test Framework consists of two main components - data objects and service handlers. These components are designed to act as an abstraction layer between tests and specific API integrations / processes to enable:

• efficient implementation of automated tests
• version agnostic (regression) testing - changing tests to use a new API version should only require configuration changes with no impact on the code
• reusability of tests across projects

Data objects (sometimes mentioned as "business" objects) represent domain entities such as orders, dispatches and returns. In general they are supposed to be used as pure DTOs, i.e. carrying data without providing business logic, although this is not the case for all objects right now - some do still carry logic - please regard this as implicitly deprecated functionality. Service Handlers encapsulate business functionality and specific API integrations, e.g. creating orders via OMSOrderServiceHandler or creating dispatches via OMSSupplierServiceHandler. Furthermore there is a so called "database" handler (OMSDbHandler) that encapsulates utility methods and data access functionality currently not covered by regular APIs.

Configuration

Configuration of the test framework is based on Microprofile Config. Primarily the framework should be configured via YAML file, in addition it is possible to set/override config properties via environment variables and system properties.

Defining the config file

By default the test framework will look for testframework-config.yaml in the current working directory. This can be overridden by defining a (relative/absolute) path to the yaml file and specifying it in the system property is.oms.testframework.configfile.

Example:

mvn test -Dis.oms.testframework.configfile=path/to/config.yaml

This "main" config file is supposed to hold all configurations that are valid across different environments (local, ci).

YAML structure - FULL example

The YAML contains a testframework block as root, with servicetype-specific service configurations as child nodes.

Example:

testframework:
  database:
    default:
      version: "V1"
      endpoint:
        host: "localhost:5432"
      username: "oms_user"
      password: "OmsDB"
      parameters:
        dbName: "oms_db"
  order-service:
    MyOrderServiceV1_2:
      version: "V1_2"
      username: "admin"
      password: "!InterShop00!"
      endpoint:
        host: "localhost"
        port: 58080
        protocol: "http"
    alternative:
      version: "V2_2"
      bearerAuthToken: "some.bearer.token"
      endpoint:
        host: "remotehost"
        port: 443
        protocol: "https"
  client-logging: True
  jwt-secret: "ABCDEF12345"

The example above includes:

• a DbHandler called "default", pointing to a local database
• an OrderHandler called "MyOrderServiceV1_2", pointing to a local Order Service versioned as "V1_2"
• an OrderHandler called "alternative", pointing to an SSL secured remote endpoint with bearer auth and service version "V2_2"

This is the general structure of the YAML:

Element	Description
testframework	root element
default-endpoint	default endpoint configuration to simplify the rest of the configuration
version	dummy placeholder - e.g. V1
username	default username for all services
password	default password for all services
bearerAuthToken	default bearer auth token for all services, as an alternative to BasicAuth via user/password // FIXME this has to be renamed, don't use this yet
endpoint	default endpoint
host	default hostname
port	default port (integer!)
default protocol	protocol - usually http / https
[service-type]	servicehandler type specific configurations
[config-id]	name of the specific configuration
version	version of the service handler
username	username for this service connection
password	password for this service connection
bearerAuthToken	bearer auth token for this service connection, as an alternative to BasicAuth via user/password // FIXME this has to be renamed, don't use this yet
endpoint	endpoint details
host	hostname
port	port (integer!)
protocol	protocol - usually http / https
parameters	additional implementation specific config parameters (key-value map)
client-logging	true/false - enable request and response logging for all ServiceHandlers supporting that feature
jwt-secret	JWT secret, allows to generate JWTs for REST APIs on the fly

The following values for [service-type] are available by default:

Service Type	Description
database	DbHandler
order-service	Order Service Handler
order-state-service	Order State Service
rma-service	RMA Service
schedule-service	Schedule Service (Jobs)
transmission-service	Transmission Service
supplier-service	Supplier Service (dispatches, returns, responses)
inventory-service	Inventory and Reservation Service

For a full reference please check the Service Handler Reference

Using parameter substitution at runtime

All configuration values can reference arbitrary system properties in the format ${some.system.prop} - they will be resolved automatically at runtime. This can be used to dynamically configure the default IOM endpoint in CI environments.

Example:

testframework:
  database:
    default:
      version: "V1"
      endpoint:
        host: "${db.host}"
      username: "oms_user"
      password: "OmsDB"
      parameters:
        dbName: "oms_db"
  order-service:
    MyOrderServiceV1_2:
      version: "V1_2"
      username: "admin"
      password: "!InterShop00!"
      endpoint:
        host: "${iom.host}"
        port: 58080
        protocol: "http"

Example to replace those properties at runtime:

mvn test -Ddb.host=dbhost.example -Diom.host=localhost

Defining a local / user config

In addition to the main testframework-config.yaml the testframework will attempt to load testframework-config.user.yaml. The file overrides configurations from the main config file, it's supposed to include user / host specific configurations like endpoint, port and database credentials.

YAML structure - user config example & default endpoint

The following user config example defines a default endpoint and environment specific database credentials:

testframework-config.user.yaml:

testframework:
  default-endpoint:
    version: "V1"
    endpoint:
      host: "localhost"
      port: 8080
      protocol: "http"
    username: "admin"
    password: "!InterShop00!"
  database:
    default:
      version: "V1"
      endpoint:
        host: "localhost:5432"
      username: "oms_user"
      password: "OmsDB"
      parameters:
        dbName: "oms_db"

Defining a default endpoint and database credentials in the user config can drastically reduce the size of the main config - the following example is sufficient to to enable two ServiceHandlers:

testframework-config.yaml:

testframework:
  order-service:
    MyOrderService:
      version: "V2_2"
  supplier-service:
    default:
      version: "V2_11"

Using custom stored procedures in test cases

In case you need to execute complex statements or functions / stored procedures on the database, you can use Flyway to get them into the testcases schema of the IOM database. You need to put your SQL files under testframework-sql on your classpath - e.g. into the directory src/test/resources/testframework-sql/. The file has to follow the Flyway naming conventions. Our recommendation is to only create "repeatable" (idempotent) migration scripts, i.e. functions/procedures that are created via CREATE OR REPLACE FUNCTION ...

Example file name with path:

src/test/resources/testframework-sql/R__my_custom_function.sql

Important / noteworthy classes

ServiceHandlerFactory

Package: com.intershop.oms.test.servicehandler

This is your entrypoint to instantiate / get ServiceHandlers that are required to create orders or trigger other business processes. Use the [config-id] defined in testframework-config.yaml to retrieve a preconfigured ServiceHandler of a specific type, e.g.

OMSOrderServiceHandler orderServiceHandler = ServiceHandlerFactory.getOrderServiceHandler("default");

*ServiceHandler interfaces

Packages: com.intershop.oms.test.servicehandler.*

Please check java-doc and sources to learn about the functionality the different ServiceHandlers provide.

SupplierServiceUtil

Package: com.intershop.oms.test.util

SupplierServiceUtil offers convenience methods to prepare dispatches, returns and order responses for previously created orders. It can either generate Lists of dispatches/returns/responses to fully dispatch/return/respond to all order positions, or use a predefined list of positions to create a single dispatch/return/response.

Examples

// TODO: Link to demo project or include simple examples

Extension concept

// TODO: not yet implemented