Java™ Functional Testing

Learn how to write Java™ functional tests for AEM as a Cloud Service

Getting Started with Functional Tests getting-started-functional-tests

Upon creation of a new code repository in Cloud Manager, an it.tests folder is automatically created with sample test cases.

Once you have the contents of the it.tests folder, you can use it as a basis for your own tests and then:

Writing Custom Functional Tests writing-functional-tests

The same tools that Adobe uses to write product functional tests can be used to write your custom functional tests. Use the product functional tests in GitHub as an example of how to write your tests.

The code for custom functional test is Java™ code in the it.tests folder of your project. It should produce a single JAR with all the functional tests. If the build produces more than one test JAR, which JAR is selected is non-deterministic. If it produces zero test JARs, the test step passes by default. See AEM Project Archetype for sample tests.

The tests are run on Adobe-maintained testing infrastructure including at least two author instances, two publish instances, and a Dispatcher configuration. This setup means that your custom functional tests run against the entire AEM stack.

Functional Tests Structure functional-tests-structure

Custom functional tests must be packaged as a separate JAR file produced by the same Maven build as the artifacts to be deployed to AEM. Generally, this build would be a separate Maven module. The resulting JAR file must contain all required dependencies and would generally be created using the maven-assembly-plugin using the jar-with-dependencies descriptor.

In addition, the JAR must have the Cloud-Manager-TestType manifest header set to integration-test.

The following is an example configuration for the maven-assembly-plugin.

<build>
    <plugins>
        <!-- Create self-contained jar with dependencies -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <version>3.1.0</version>
            <configuration>
                <descriptorRefs>
                    <descriptorRef>jar-with-dependencies</descriptorRef>
                </descriptorRefs>
                <archive>
                    <manifestEntries>
                        <Cloud-Manager-TestType>integration-test</Cloud-Manager-TestType>
                    </manifestEntries>
                </archive>
            </configuration>
            <executions>
                <execution>
                    <id>make-assembly</id>
                    <phase>package</phase>
                    <goals>
                        <goal>single</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Within this JAR file, the class names of the actual tests to be executed must end in IT.

For example, a class named com.myco.tests.aem.it.ExampleIT would be executed, but a class named com.myco.tests.aem.it.ExampleTest would not.

Furthermore, to exclude test code from the coverage check of the code scanning, the test code must be below a package named it (the coverage exclusion filter is **/it/**/*.java).

The test classes must be normal JUnit tests. The test infrastructure is designed and configured to be compatible with the conventions used by the aem-testing-clients test library. Developers are encouraged to use this library and follow its best practices.

See aem-testing-clients GitHub repo for more details.

Prerequisites prerequisites

Dependencies

Upcoming changes to the containerized infrastructure for executing functional tests require updating the aem-cloud-testing-clients library in your custom functional tests to version 1.2.1 or higher. Ensure that the dependency in your it.tests/pom.xml file is updated accordingly.

<dependency>
   <groupId>com.adobe.cq</groupId>
   <artifactId>aem-cloud-testing-clients</artifactId>
   <version>1.2.1</version>
</dependency>

Local Test Execution local-test-execution

Before activating functional tests in a Cloud Manager pipeline, it’s recommended to run the functional tests locally using the AEM as a Cloud Service SDK or an actual AEM as a Cloud Service instance.

Running in an IDE running-in-an-ide

Because test classes are JUnit tests, they can be run from mainstream Java ™ IDEs like Eclipse, IntelliJ, and NetBeans. Because both product functional tests and custom functional tests are based on the same technology, both can be run locally by copying the product tests into your custom tests.

However, when running these tests, it is necessary to set various system properties expected by the aem-testing-clients (and the underlying Sling Testing Clients) library.

The system properties are as follows.

Running All Tests Using Maven using-maven

mvn verify -Plocal \
    -Dit.author.url=https://author-<program-id>-<environment-id>.adobeaemcloud.com \
    -Dit.author.user=<user> \
    -Dit.author.password=<password> \
    -Dit.publish.url=https://publish-<program-id>-<environment-id>.adobeaemcloud.com \
    -Dit.publish.user=<user> \
    -Dit.publish.password=<password>