Configuration Pattern for AludraTest

Several Components of AludraTest can be configured, especially the AludraTest Services.

Every component has its own set of configuration properties. There are several Scopes for configuration:

  1. Default Scope: The default configuration for a component.
  2. Global Scope: Global configuration for a component, overriding some or all Defaults.
  3. Service Instance Scope: The configuration for a Service component when instantiated for a named purpose, overriding some or all Global settings. This named purpose is passed to getService() when requesting a service instance.
  4. Environment Scope: The configuration for a component when running inside a named Environment. This name can be set when starting AludraTest (when not set, it is LOCAL). Environment configuration overrides Global and Service Instance configuration elements.
  5. Environment Service Instance Scope: The configuration for a Service component when instantiated for a named purpose and when running inside a named Environment, overriding some or all Environment configuration elements.

Loading mechanism and order

All of these scopes (with the exception of the Default scope) can be configured using .properties files on the Classpath. Additionally, Java System Properties (e.g. specified on command line) can be used to further override configuration properties.

  1. Global Scope: This scope's settings are read from a file config/<COMPONENT_ID>.properties on the current Classpath. The COMPONENT_ID depends on the component / service, and in most cases, it is the name of the service interface, with the first letter in lower case (e.g. fileService.properties). Components will provide their ID in their documentation.
  2. Service Instance Scope: This scope's settings are read from a file config/<INSTANCE_NAME>/<COMPONENT_ID>.properties on the current Classpath. The INSTANCE_NAME would be the name of a Service Instance (see Scope description for details).
    The settings in such a file would override all settings in the Global properties file for the same COMPONENT_ID (but only for the given INSTANCE_NAME), if such a file exists.
  3. Environment Scope: This scope's settings are read from a file config/_<ENV_NAME>/<COMPONENT_ID>.properties on the current Classpath.

The ENV_NAME would be the name of an environment. This name is a startup parameter of AludraTest, and by default, it is LOCAL.
The settings in such a file would override all settings in the Global and in all Service Instance properties files for the same COMPONENT_ID (but only for the given ENV_NAME).

  1. Environment Service Instance Scope: This scope's settings are read from a file config/_<ENV_NAME>/<INSTANCE_NAME>/<COMPONENT_ID>.properties on the current Classpath.

The settings in such a file would override all settings in the Global, all Service Instance and all Environment settings for the same COMPONENT_ID (but only for the given ENV_NAME and INSTANCE_NAME combination).

  1. Environment Properties: If there is, for a given configuration property myprop, a System Property named ALUDRATEST_CONFIG/<COMPONENT_ID>/myprop, it overrides this configuration property for all previous scopes.
  2. Environment Service Instance Properties: If there is, for a given configuration property myprop, a System Property named ALUDRATEST_CONFIG/<COMPONENT_ID>/_<INSTANCE_NAME>/myprop, it overrides this configuration property for all previous scopes, but only for the given INSTANCE_ID.

Example Usage Scenario

To better understand this concept, let's first set up an example usage scenario which we will configure from the top-level to the most fine-grained scope:

We want to run a set of test cases which test a file based interface. These test cases will use the FileService service, which has its defined set of configuration properties. The requirements for the test cases are as follows:

  • By default, all file operations are local and are using the user's home directory as base. Writing operations are not permitted. File encoding UTF-8 is used.
  • For locally running test cases, we want to use the directory C:\\DEV\\testdata (on a Windows machine)

and ISO-8859-1 as encoding. Writing operations shall be permitted for these local executions.

  • For the test case purpose (Service Instance) "VerySpecialInterface", we want to use the file

encoding UTF-8. Writing operations shall be permitted for this test case purpose on all environments.

  • For all test cases running on server environments, we want to use the FTP server ftp.mycompany.int and on this server, the directory /var/tst/testdata. Writing operations shall initially be disabled.
  • For test cases running on server environment TESTSRV23, the FTP server ftp3.mycompany.int

shall be used instead.

Default configuration

The default configuration elements are specified by the component to configure, so this configuration is in effect when it is not overridden by other configuration scopes. Without any additional configuration, we can assume that all file operations are local, are using the user's home directory as base, and that writing operations are not permitted.

Global configuration

We now have to think a little bit about what of the example usage scenario has to be covered with "global" configuration. Notice that the "locally running test cases" requirement may seem to require the Global configuration scope, but it is not. You can clearly specify these test cases as the ones executed within the LOCAL environment (assumed by AludraTest by default).

So, instead we should configure the "all test cases running on server environments" element as global. To set the global configuration for the FileService, there must be a file config/fileService.properties on the Classpath. So, in your Java project, you would normally create a file src/main/resources/fileService.properties, with the following contents (for the example usage scenario):

protocol=ftp
user=myuser
password=topsecret
host=ftp.mycompany.int
base.url=/var/tst/testdata
writing.enabled=false

Notice that the last line is not completely necessary, as writing is disabled by default, and there is no higher configuration scope which could have enabled it. Still, you can re-specify it to make the fact clear.

Service Instance Configuration

To specify the configuration for a named Service Instance (in our case, "VerySpecialInterface"), a file named config/VerySpecialInterface/fileService.properties is searched on the classpath. Again, you would create this structure in your src/main/resources directory, with the following file contents:

writing.enabled=true
encoding=UTF-8

Notice that the encoding settings does not have that much effect, again because it is the default value and there is no higher configuration scope which changes it (the Global scope could have changed it). So we could have left it out as well, but now it gets interesting...

Environment Configuration

We have some elements needing environment specific configuration in our example usage scenario. First of all, the requirement for locally executed test cases. As AludraTest assumes an environment named LOCAL by default, we can use this and specify our configuration for this environment.

To get the configuration for this environment, a file named config/_LOCAL/fileService.properties is searched on the Classpath. Notice the underscore prefix, which indicates an environment name instead of a Service Instance name.

The contents of this file (src/main/resources/config/_LOCAL/fileService.properties) would look as follows:

writing.enabled=true
encoding=ISO-8859-1

protocol=file
base.url=c:/DEV/testdata

Notice that these settings do override even the Service Instance configuration provided for the VerySpecialInterface instance! So, when stopping here with configuration, the VerySpecialInterface instance on the LOCAL environment would run with encoding ISO-8859-1, which is not what we want!

See the next section on how to resolve this; there is one more environment specific thing to configure:

src/main/resources/config/_TESTSRV23/fileService.properties:

host=ftp3.mycompany.int

Environment Service Instance Configuration

There is still one requirement left: We need the VerySpecialInterface to use UTF-8 encoding instead of ISO-8859-1 when running on the local environment. For this purpose, create a configuration file src/main/resources/config/_LOCAL/VerySpecialInterface/fileService.properties with the following contents:

encoding=UTF-8

That's it! Now we have successfully covered all configuration requirements for the example usage scenario. But there is something more...

System Property Configuration

You can also specify all of these configuration elements via Java System Properties, e.g. on the command line. These System Properties will always override the according configuration property in the configuration files.

There are two levels of System Properties overrides:

  • Properties overriding configuration for the whole environment
  • Properties overriding configuration for a given Service Instance on the current environment.

There is no need (and no possibility) to specify the environment in the System Properties, as it is always assumed to be the current enviroment (why would you specify the configuration for another environment on the command line?).

Environment Configuration System Properties

Let's say, we want to really make sure no test case can write on our current environment. Then we would specify a System Property with this name and value:

ALUDRATEST_CONFIG/fileService/writing.enabled=false

This would also override a write enablement which has been specified for a given Service Instance on exactly this environment via configuration file!

Environment Service Instance Configuration System Properties

If we do not want to be that restrictive as in the last example and only want to prevent one Service Instance (UnsafeInterface) from being able to write, we can use a system property like this:

ALUDRATEST_CONFIG/fileService/_UnsafeInterface/writing.enabled=false

Notice the underscore, now being used to prefix a Service Instance instead of an environment name. This is necessary to differentiate between Service Instance names and possibly complex configuration structures being used by the service.

When you invoke a Java program, e.g. the AludraTest Runner, you can set the property via command line:

java org.aludratest.AludraTest com.acme.MySuite -DALUDRATEST_CONFIG/fileService/_UnsafeInterface/writing.enabled=false