Test your Plugin

When developing plugins, it is recommended to use the provide Unit and Integration Test Harness (based on Arquillian.) Not only do your plugin’s Unit and Integration tests ensure that your plugin will function on your computer, but because tests are run when plugins are installed into a Forge runtime, they also ensure that your plugin will function on your users computers.

Install the Test Harness

This step should already have been completed if you used the ‘plugins setup’ command in the section titled: [Reference the Forge APIs]. If not, paste the following dependencies into your pom.xml file.

<dependency>
    <groupId>org.jboss.forge</groupId>
    <artifactId>forge-test-harness</artifactId>
    <version>${forge.api.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.jboss.forge</groupId>
    <artifactId>forge-shell</artifactId>
    <version>${forge.api.version}</version>
    <scope>test</scope>
</dependency>

Extend AbstractShellTest or SingletonAbstractShellTest

AbstractShellTest boots the Shell for each individual test method, while SingletonAbsractShellTest boots the Shell only once per test class, where each method operates on the same instance.

package com.example.plugin;

import javax.inject.Inject;

import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.forge.project.Project;
import org.jboss.forge.project.dependencies.DependencyResolver;
import org.jboss.forge.test.AbstractShellTest;
import org.jboss.shrinkwrap.api.spec.JavaArchive;
import org.junit.Assert;
import org.junit.Test;

public class ExamplePluginTest extends AbstractShellTest
{
   // Notice that you may use injection to do verification of the internal state of the system.
   // Or to perform additional operations.
   @Inject
   private DependencyResolver resolver;

   @Deployment
   public static JavaArchive getDeployment()
   {
      // The deployment method is where you must add references to your classes, packages, and
      // configuration files, via  Arquillian.
      return AbstractShellTest.getDeployment().addPackages(true, ExamplePlugin.class.getPackage());
   }

   @Test
   public void testInstallPrettyfaces() throws Exception
   {
      // Create a new barebones Java project
      Project p = initializeJavaProject();

      // Queue input lines to be read as the Shell executes.
      queueInputLines("y");

      // Execute a command. If any input is required, it will be read from queued input.
      getShell().execute("echo hi there");

      Assert.assertNotNull(resolver);
   }
}

Invoking commands in your test

In the above test, commands are invoked in the booted Shell through the invocation of getShell().execute(...) sequence. The Shell.execute(...) method accepts a shell command string with command options, as it’s parameter.

You may want to provide inputs during the execution of the command when you use the ShellPrompt API in your plugin. This is possible through the use of the queueInputLines(...) method. It accepts a variable number of String arguments. Each argument corresponds to an input line that is provided to the displayed prompt.

Note that queueInputLines(…) should be invoked prior to the execution of the Shell.execute(…) method. Arguments queued up before command invocation would then be provided as inputs when prompted. Queueing arguments after invoking Shell.execute(…) has no effect on the current command invocation context; the queued arguments will be used in the next command invocation.

Add other dependencies

Because of the modular structure of Forge, you may need to add additional test-scoped dependencies to your plugin. After all, not all commands are made available by adding the test harness artifact as a dependency.

For instance, if you want to invoke commands provided by the built-in Java EE plugin (like the persistence, entity, or rest commands), you’ll need to add the org.jboss.forge:forge-javaee-impl artifact as a test-scoped dependency, like so:

<dependency>
    <groupId>org.jboss.forge</groupId>
    <artifactId>forge-javaee-impl</artifactId>
    <scope>test</scope>
</dependency>

Such dependencies are expected to be CDI bean archives that contain the desired Forge plugins you wish to utilize during test execution.

Run your Build

If done properly, you should now see your test execute during the Plugin build lifecycle.

$ build

Write more tests

The more tests, the merrier! Tests make happy code.