JarCastingAppMap Maven plugin
Quickstart
First, ensure you have a properly configured appmap.yml in your root project directory. A basic configuration may look like:
# appmap.yml
name: my_organization/my_application
packages:
# List the packages you'd like to record here.
- path: com.myorganization.myapplication
# Individual classes or methods can be chosen as well.
#
# - path: com.myorganization.myapplication.MyClass
# - path: com.myorganization.myapplication.MyClass#myInstanceMethod
# - path: com.myorganization.myapplication.MyClass.myStaticMethod
#
# Optionally, include paths of packages, classes
# or methods that you'd like to exclude from recording
#
# - exclude: com.myorganization.myapplication.util
# - exclude: com.myorganization.myapplication.MyClass
# - exclude: com.myorganization.myapplication.MyClass#myInstanceMethod
# - exclude: com.myorganization.myapplication.MyClass.myStaticMethod
Next, add the following plugin definition to your pom.xml:
<!-- the plugin element goes to build/plugins -->
<!-- AppMap agent, default parameters -->
<plugin>
<groupId>com.appland</groupId>
<artifactId>appmap-maven-plugin</artifactId>
<executions>
<execution>
<phase>process-test-classes</phase>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
</executions>
</plugin>
That's all! The AppMap agent will automatically record your tests when you run mvn test. By default, AppMap files are output to target/appmap.
Using Visual Studio Code? Download the AppMap extension to view AppMap files in your IDE.
About
The AppMap Maven Plugin provides simple method for recording AppMaps in running tests in Maven projects and a seamless integration into CI/CD pipelines. The recording agent requires appmap.yml configuration file, see appmap-java for details.
Plugin goals
prepare-agent- adds the AppMap Java agent to the JVM
Plugin configuration
configFilePath to theappmap.ymlconfig file. Default: ./appmap.ymloutputDirectoryOutput directory for.appmap.jsonfiles. Default: ./target/appmapskipAgent won't record tests when set to true. Default: falsedebugEnable debug flags as a comma separated list. Accepts:info,hooks,http,localsDefault: infodebugFileSpecify where to output debug logs. Default: target/appmap/agent.logeventValueSizeSpecifies the length of a value string before truncation occurs. If set to 0, truncation is disabled. Default: 1024
Notes
Configuring Surefire
Some configuration parameters of the Surefire plugin may prevent the appmap plugin from being activated when the tests are run:
forkCountmay not be set to0. Please set it to a value larger than0or remove this configuration parameter frompom.xml- If
argLineis specified, it must include@{argLine}
Example:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${maven-surefire-plugin.version}</version>
<configuration>
<forkCount>1</forkCount>
<reuseForks>true</reuseForks>
<argLine>
@{argLine} --illegal-access=permit
</argLine>
</configuration>
</plugin>
Troubleshooting
I have no target/appmap directory
It's likely that the agent is not running. Double check the prepare-agent goal is being run. If the JVM is being forked at any point, make sure the javaagent argument is being propagated to the new process. Additionally check that the Surefire plugin configuration is not preventing the agent from running. See "Configuring Surefire" for more information.
*.appmap.json files are present, but appear empty or contain little data
Double check your appmap.yml. This usually indicates that the agent is functioning as expected, but no classes or methods referenced in the appmap.yml configuration are being executed. You may need to adjust the packages being recorded. Follow this link for more information: https://github.com/applandinc/appmap-java#configuration
My tests aren't running or I'm seeing The forked VM terminated without properly saying goodbye.
Check the agent log (defaults to target/appmap/agent.log) and/or the Maven Surefire dumpstream (target/surefire-reports/${DATETIME}.dumpstream). This is typically indicative of an invalid appmap.yml configuration.
I have a test failure that only occurs while the agent is attached
Please open an issue at applandinc/appmap-java. Attach a link to the source code or repository (if available), as well as any other relevant information including:
- the contents of
appmap.yml - the run command used (such as
mvn test) - output of the run command
- any Maven Surefire dumpstreams generated (
target/surefire-reports/${DATETIME}.dumpstream)
Running without modifying pom.xml
By specifying the fully-qualified goal, the agent can be run without any additional configuration:
mvn com.appland:appmap-maven-plugin:prepare-agent test