This is a project to support FirstSpirit module developers with writing unit tests for FirstSpirit components. It can help you testing your executeables, services, runnable gui elements and the deployment descriptors by providing an easy way to get handy mock objects.

To get the FS Test Tools, you can choose between two options:

Get the GitHub release and install it. Use this command to make sure maven installs the jars correctly (see official Maven mini guide for more information):

mvn install:install-file -Dfile=<path-to-file> -DpomFile=<path-to-pomfile-of-file>

For version 1.2.3 the complete installation would look like this:

mvn install:install-file -Dpackaging=pom -Dfile=fstesttools-parent-1.2.3.pom -DpomFile=fstesttools-parent-1.2.3.pom
mvn install:install-file -Dfile=mocking-1.2.3.jar -DpomFile=mocking-1.2.3.pom
mvn install:install-file -Dclassifier=javadoc -Dfile=mocking-1.2.3-javadoc.jar -DpomFile=mocking-1.2.3.pom
mvn install:install-file -Dfile=rules-1.2.3.jar -DpomFile=rules-1.2.3.pom
mvn install:install-file -Dclassifier=javadoc -Dfile=rules-1.2.3-javadoc.jar -DpomFile=rules-1.2.3.pom
mvn install:install-file -Dfile=tests-1.2.3.jar -DpomFile=test-1.2.3.pom
mvn install:install-file -Dclassifier=javadoc -Dfile=tests-1.2.3-javadoc.jar -DpomFile=tests-1.2.3.pom

Building from source is quiet easy. Just clone the project and build the FirstSpirit Test Tools parent. To do this, just execute the following command:

mvn clean install -Drevision=<your-version>

The build will create the following artifacts:

• mocking-Your-Version.jar
• rules-Your-Version.jar
• tests-Your-Version.jar

With -Drevision=<your-version> you can change the version you are building. By default, the version is 1.0_DEV.123. Feel free to change it.

After installation, you can add the dependencies inside your own project's pom.xml (e.g. for the mocking artifact). You can replace Your-Version with LATEST if you have access to e-Spirit's artifactory.

	...
	<dependencies>
		...
		<dependency>
			<groupId>com.espirit.moddev.fstesttools</groupId>
			<artifactId>mocking</artifactId>
			<version>Your-Version</version>
			<scope>test</scope>
		</dependency>
		...
	</dependencies>
	...

You are now ready to use the FS Test Tools. This section will show you how to correctly do that.

The following example will show you how to use a MockingBaseContext inside your own unit test. Other mock context classes work similar to this. See Javadoc for further information about each context.

public class MyTest {
    ...
    private BaseContext context;

    @Before
    public void setUp() throws Exception {
        context = new MockingBaseContext(Locale.ENGLISH, BaseContext.Env.PREVIEW);
        ...
    }
    
    @Test
    public void testSomething() throws Execption {
        // Use normal FS API to get mocks of classes such as agents:
        FormAgent formAgent = context.requireSpecialist(FormAgent.TYPE);
        // Use Mockito to tell what the mock should do
        when(formAgent.anyMethod()).thenReturn(...);
        ...
    }
    ...
}

For this section, you need to know a little bit about JUnit rules. If you are not familiar with JUnit Rules, have a look at this. At the moment there are two types of custom Junit Rules available:

• Two rules to support you with logging
• One rule to support you with FirstSpirit client actions

Logging rules can help you with managing your logging. They are usefull if there are many log lines and it is needed to know where a test starts and stops. If both logging rules are used, then the logging system is initialized (InitLog4jLoggingRule) and in the logged lines there is a message at the beginning and at the end of each test (LogTestMethodNameRule). The example shows how you can use the rules:

public class MyTest {
    
    @ClassRule
    public static InitLog4jLoggingRule loggingRule = new InitLog4jLoggingRule();
    
    @Rule
    public LogTestMethodNameRule rule = new LogTestMethodNameRule();
    
    @Test
    public void testSomething() throws Execption {
        
        ...
    }
    ...
}

Example log output:

1 [main] INFO MyTest  - Start of 'testSomething'...
...
5 [main] INFO MyTest  - Successful termination of 'testSomething'!

The FirstSpirit Connection rule is a FirstSpirit client for integration tests. The rule maintains the connection, e.g. opens and close it according to test life cycle. The prerequisite is a running FirstSpirit server. By default the host localhost with port 8000 and user Admin with password Admin is used, but can be changed at any time.

Then the rule can be used to execute a schedule task, to import zip files (e.g. exported templates) or to modify the content of templates. The feature set of the rule is not final or complete but can be extended easliy. If you wish to have some new functionality you are welcome to provide it by adding a so-called command (see paragraph below). This example starts a connection to a FirstSpirit server and invokes a command:

public class MyTest {
    
    @Rule
    public FirstSpiritConnectionRule rule = new FirstSpiritConnectionRule();
    
    @Test
    public void testSomeThing() throws Execption {
        MyParameters parameters = new MyParameters(...);
        MyResult result = rule.invokeCommand("nameOfCommand", parameters);
        ...
    }
    ...
}

All available commands can be found in the package com.espirit.moddev.fstesttools.rules.firstspirit.commands.

As mentioned above, it is not that hard to write your own commands. Basically you only need to implement three interfaces (FsConnRuleCmdParamBean, FsConnRuleCmdResultBean and FsConnRuleCommand) where the command class must be in the package com.espirit.moddev.fstesttools.rules.firstspirit.commands or below (the rule will scan for commands):

public class MyParameters implements FsConnRuleCmdParamBean {
    
    @javax.inject.Inject
    private Connection firstSpiritConnection;
    
    // Or:
    //@Inject
    //private BaseContext baseContext;
    
    // Or:
    //@Inject
    //private SpecialistBroker broker;
    
    ...

    @Override
    public String getProjectName() {
        //If no project is needed return here null
        return null;
    }

    ...
}

public class MyResult implements FsConnRuleCmdResultBean {
    ...
}

public class MyCommand implements FsConnRuleCommand<MyParameters, MyResult>{
    
    @Override
    public String name() {
        return "Foobar";
    }

    @Override
    public MyResult execute(final MyParameters parameters) {
        ...
        return new MyResult(...);
    }
}

With dependency injection (see JSR 330 or @javax.inject.Inject annotation above) the FirstSpirit Connection Rule will provide a Connection, a BaseContext, a SpecialistBroker or a GenerationContext which will be the foundation of your command.

Each FirstSpirit module needs to have a deployment descriptor called module.xml. Testing your module.xml is a practice to make sure, your module is properly descripted and configured. For developers it is easy to forget to update the module.xml. By using this test class you can prevent those careless mistakes.

The parent class AbstractModuleXmlTest expects a module.xml in the root of the class path. Futhermore there must be a file called moduleXmlTest.properties in the test resource which must be filtered too:

name=${project.groupId}.${project.artifactId}
displayName=${project.name}
description=${project.name} (${project.artifactId})
version=${project.version}
vendor=${organization.name}

If the pom's variables or properties do not apply at your project because you use static strings then use static values inside the moduleXmlTest.properties. The basic idea behind the pom's variables is to have one place to maintain a module's name, display name etc. To enable filtering just add this to your pom.xml:

<project>
    ...
    <build>
        <testResources>
            <testResource>
                <directory>src/test/resources</directory>
                <filtering>true</filtering>
                <includes>
                    <include>*.properties</include>
                </includes>
            </testResource>
            <testResource>
                <directory>src/test/resources</directory>
                <filtering>false</filtering>
                <excludes>
                    <exclude>*.properties</exclude>
                </excludes>
            </testResource>
        </testResources>
        ...
    </build>
    ...
</project>

After this you need to subclass the AbstractModuleXmlTest with a ModuleXmlTest and implement the class loader method:

public class ModuleXmlTest extends AbstractModuleXmlTest {

    @Override
    protected ClassLoader getTestClassLoader() {
        return getClass().getClassLoader();
    }

    // Additional Tests are possible, for instance
    @Test
    public void testThatConstanceValuesEqualsNamesInModuleXml() throws Exception {
        assertThat("Expected specific value", getModuleXML(),
                   hasXPath("/module/components/project-app/name", equalTo("MyTechnicalProjectAppName")));

    }
}

When you have done this you get some basic tests without doing anything for it:

• Name
• Display name
• Version
• Vendor
• Existance of full qualified class names of class and configurable XML tags

Of course you can add own test cases as you like by using the Hamcrest XPath Matchers (see above).

If you need help, please read this section. It provides a subsection for troubleshooting and a subsection with examples which may be handy in some cases. If you want to contribute, please read the contribution section below. If there are any further questions regarding the FS Test Tools please go to the FirstSpirit Community Developers Section and post them there.

coming soon(ish).

If you are getting an error that the dependency fs-access could not be resolved then please follow the instructions below. To enable the source code to be compiled successfully, the fs-access.jar file of the FirstSpirit Server needs to be installed in the local Maven repository first. The fs-access.jar file is located in the directory:

<FirstSpirit Server installation directory>/data/fslib

It is installed by entering the following command into the command line:

mvn install:install-file -Dfile=<path-to-access.jar> -DgroupId=de.espirit.firstspirit -DartifactId=fs-access -Dversion=<first-spirit-version> -Dpackaging=jar

Within this command, the parameters used for the path to the fs-access.jar file and the FirstSpirit version must be substituted accordingly:

mvn install:install-file -Dfile=C:\fs-access.jar -DgroupId=de.espirit.firstspirit -DartifactId=fs-access -Dversion=5.1.2 -Dpackaging=jar

Note: Running the installation command within the directory in which the pom.xml file has been saved leads to an error. The installation must therefore be performed outside this directory.

During installation, the local Maven repository has been automatically created in the user directory under <user's home>.m2/repository. After the fs-access.jar file has been successfully installed, it should be located in this directory (see figure below):

There is a dedicated sub module with code examples in this Maven project. The unit tests can be executed with Maven. The next paragraphs discuss the examples in detail.

Each FirstSpirit module must have a deployment descriptor called module.xml which tells FirstSpirit what to expect inside the FirstSpirit module file (*.fsm). To avoid careless mistakes by developers and ensures a certain formalism, it can covered by a simple unit test. In detail this is discussed under Using The Module-Xml-Test. The example unit test is called ModuleXmlTest. The unit test checks for standard tags like name, version etc. as well as full qualified class names.

This example shows how to write a unit test with a MockingBaseContext for a FirstSpirit executable Java class called MyExecutables. The use case is quite simple, it shows a yes/no dialog to a user for both clients, ContentCreator (web) and SiteArchitect (UI). The corresponding unit test for this FirstSpirit Executables is MyExecutablesTest. It simulates both FirstSpirit clients ContentCreator and SiteArchitect with two languages.

The next example deals with FirstSpirit serverside services and implements a function to retrieve the FirstSpirit version string. Again, the MockingBaseContext plays a central role. The service implementation class MyServiceIml implements the Java interfaces MyService and Service<MyService> (FirstSpirit Community for login information). The unit test is called MyServiceImlTest.

Besides the more general FirstSpirit Executables there are toolbar buttons and context menu items to extend the FirstSpirit clients with own functionality. Here as well, the MockingBaseContext plays a central role. There are two examples, a toobar item called MyToolbarItem and a context menu item called MyContextMenuItem. Both implementations show the current selection or item under focus. The correponding untit tests are MyToolbarItemTest and MyContextMenuItemTest.

There is a small example whithin the test package com/espirit/moddev/fstesttools/rules/firstspirit/commands how to write your own custom command. The example mentioned above is used by the unit test FirstSpiritConnectionRuleTest.

The FirstSpirit Test Tools are built with Maven and compiled against the following libraies:

• FirstSpirit Access API
• JSR 330 (javax.inject)
• JUnit 4
• Hamcrest
• Mockito
• Reflections
• Apache Commons IO
• Apache Log4J 1.2
• SLF4J API

• Needle4J

Regarding unit test philosophy the MockingBaseContext is a fake which produces mocks (of agent or service implementations) with the help of the Mockito library. So it acts as a test drop-in replacement for the real FirstSpirit BaseContext and its decendants. It is not only a simple mock factory because it returns always the same mock object instance by using FirstSpirit API calls. So the mocks are always singletons for the current test.

FirstSpirit and this project are developed by the e-Spirit AG. The head office of the e-Spirit AG is in Dortmund, Germany.

Use this project and provided binaries at your own risk.

Apache License Version 2.0 January 2004 http://www.apache.org/licenses/