Debugging and Integration Testing in Alfresco SDK 3.0

Alfresco has updated its SDK!

See our articles here and here about the basics.

In its current state, SDK 3.0 doesn’t support unit testing. It does, however, have a robust Integration Testing framework which, in many ways, covers the same ground and then some.

In this article I’ll be going into the basics of Integration Testing in SDK 3.0. This will include how to set up debugging in your IDE, as well as setting up hotswapping for easier test writing.

Debugging in your IDE:

For IntelliJ:

  1. Go to Run>Edit-Configurations.
  2. Hit the green plus sign in the top left corner and scroll down to “Remote”.
  3. Name the connection whatever you like.
  4. Set the port to 8000 (maven’s debug port).

For Eclipse:

  1. Go to Run Configurations>Debug Configurations.
  2. Hit the green plus sign and add “Remote Java Application”.
  3. Name the connection.
  4. For “Project” click Browse, and select your platform jar project.
  5. Set the host:port to localhost:8000.
  6. Click “Apply”.

You can now run your Alfresco “mvn” commands as “mvnDebug” and you will get a message that maven is waiting to connect. This works with previous SDKs as well.

To run the SDK, make sure the debug configuration is set to the connection you created and
hit “debug” in your IDE. You can set a breakpoint just about anywhere, even in non project files. Just
be aware that Alfresco does not generally take well to being paused while any sort of transaction is taking place, and you may get some Authentication or Timeout exceptions.

Hotswapping in SDK 3.0:

Hotswapping is a useful tool for RAD (Rapid Application Development), allowing you to make changes to your tests on the fly without having to restart the system. Hotswapping is not required for the creation of Integration Tests, but it is suggested. Otherwise, you’ll have to wait for the entire Alfresco instance to spin up before the test is executed.

  1. Download the DCEVM jar from here.
  2. Run the jar (java -jar) as an admin.
  3. Select your JVM from the list and click “install DCEVM as altjvm”. This modification allows you to use the DCEVM when executing a command. It does not actually alter the JVM it is applied to.
  4. Download the HotswapAgent jar from here. Make sure to get the latest 1.0 release.
  5. Now, either modify the current ./ script or make a new one, which replaces the standard maven opts statement with:
export MAVEN_OPTS="-Xms1G -Xmx3G -XXaltjvm=dcevm -javaagent:[full path to your hotswap jar]

As a suggestion, you may want to turn HotswapAgent debugging,  found in /src/test/resources to “info”. It’s a bit too verbose otherwise.

Now, tests can be rebuilt on the fly, without having to restart the SDK! A build command in your IDE or “mvn compile” should produce an output in your Alfresco log that the altered classes were rebuilt.

Integration Tests

Creating new tests:

In order to create a new test, you’ll need to create a file in integration-tests/src/test/java that follows any of the following naming conventions:


For best practices, it’s best to put these tests in same package as the components they’re testing.

The class must also have the following annotation before the class declaration:

 @RunWith(value = AlfrescoTestRunner.class)

It also must extend the AbstractAlfrescoIT class, which gives you access to the application context and service registry.

Services are instantiated as follows:

nodeService = (NodeService) getApplicationContext().getBean("NodeService");


nodeService = getServiceRegistry().getNodeService;

Beyond that, it acts as a standard JUnit test. You have full access to the global-properties bean, as well as logging. Outputs will display in the window where you ran Alfresco, and not the window in which you called the tests.

Running Tests:

In order to run integration tests against an already running local Alfresco instance on your local machine, open a new terminal and navigate the project folder, then use the command:

mvn integration-test

or, for a specific test

mvn -Dit.test=[your test class] verify

More documentation on the Maven failsafe plugin can be found here. The plugin comes pre-configured in the integration-tests pom.xml file.

To run tests against a running Alfresco instance elsewhere, you’ll need to set the @Remote for a test to target “endpoint = http://host:port/alfresco”.

The default value is:

@Remote(endpoint = "http://localhost:8080/alfresco")

This line is optional. The test will run with the default value if this line is not included in the test.

The IT test commands can also spin up a local instance of the SDK if it doesn’t detect an Alfresco instance on @Remote. This method usually ends with the following errors. This is a known issue.

Exception in thread "Thread-4" java.lang.NoClassDefFoundError: org/apache/commons/io/FileUtils
Caused by: java.lang.ClassNotFoundException:
  at org.codehaus.plexus.classworlds.strategy.SelfFirstStrategy.loadClass(
  at org.codehaus.plexus.classworlds.realm.ClassRealm.unsynchronizedLoadClass(
  at org.codehaus.plexus.classworlds.realm.ClassRealm.loadClass(
  at org.codehaus.plexus.classworlds.realm.ClassRealm.loadClass(
  ... 1 more
java.lang.NoClassDefFoundError: de/schlichtherle/truezip/fs/FsLockController$1Sync
  at de.schlichtherle.truezip.fs.FsLockController.sync(
  at de.schlichtherle.truezip.fs.FsDecoratingController.sync(
  at de.schlichtherle.truezip.fs.FsFalsePositiveArchiveController.sync(
  at de.schlichtherle.truezip.fs.FsManager.sync(
  at de.schlichtherle.truezip.fs.FsDefaultManager.sync(
  at de.schlichtherle.truezip.fs.FsSyncShutdownHook$
Caused by: java.lang.ClassNotFoundException: de.schlichtherle.truezip.fs.FsLockController$1Sync
  at org.codehaus.plexus.classworlds.strategy.SelfFirstStrategy.loadClass(
  at org.codehaus.plexus.classworlds.realm.ClassRealm.unsynchronizedLoadClass(
  at org.codehaus.plexus.classworlds.realm.ClassRealm.loadClass(
  at org.codehaus.plexus.classworlds.realm.ClassRealm.loadClass(
  ... 7 more


That’s it for the basics of Integration Testing in SDK 3.0. I hope this saves you some time and effort. Happy testing!




Leave a Reply

Your email address will not be published. Required fields are marked *

From our Blog...

Managing Digital Risk

Leveraging Content Management Systems to Mitigate Digital Risk The convenience of the digital world is not freely given. It is hard to imagine a world where you can’t think of an item and purchase it online within a few minutes. As we bask in the glow of endless catalogs of online goods, the thought of online… Read more »

Read More

Configuring Alfresco SAML SSO Module with Okta IdP

Alfresco recently released a new patch for their SAML Single Sign On solution module. This module allows Alfresco user’s to configure their Alfresco installation with their Single Sign On (SSO) Identity Provider. In this tutorial, I’ll explain the process of configuring Okta to be used with the module. Note: This tutorial is assuming you’ve followed… Read more »

Read More

Content Migration: Being Prepared

Much like negotiating a treaty between two countries who do not share a common language, someone will be faced with the task of translating. If that translator is not properly prepared the outcome might create more problems than it solves.

Read More