hansken-extraction-plugin-sdk-documentation/0.7.3/_sources/dev/java/testing.md.txt

# Using the Test Framework in Java

.. _java testing:

This section assumes you use the same setup as is used in the
[Extraction Plugin Examples](https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples).

## Prerequisites

Java Plugins can use the `plugin-super-pom` as maven parent, which makes sure the
FLITS [Test Framework](../concepts/test_framework.md) is included in the build.

```xml

<parent>
    <groupId>org.hansken.plugin.extraction</groupId>
    <artifactId>plugin-super-pom</artifactId>
    <version>0.4.3</version>
</parent>
```

## Embedded Testing versus Remote Testing

There are ways of integration testing a plugin with the Test Framework:

* **Embedded testing**: Here the plugin is run directly from a JUnit test without using the gRPC layer.
* **Remote testing**: Here the test will start an ExtractionPluginServer that will serve the plugin. All communication
  is between server and plugin is done using gRPC.

See below for an example of each way of testing.
The [Extraction Plugin Examples](https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples) contains many
more examples.

### Embedded Testing example

Embedded tests can be run as a unit test.

```java
import static nl.minvenj.nfi.flits.util.FlitsUtil.srcPath;

import java.nio.file.Path;

import org.hansken.plugin.extraction.api.ExtractionPlugin;
import org.hansken.plugin.extraction.test.EmbeddedExtractionPluginFlits;

/**
 * An integration test for MyPlugin.
 */
class MyPluginIT extends EmbeddedExtractionPluginFlits {

    @Override
    protected ExtractionPlugin pluginToTest() {
        // MyPlugin is a class implementing the ExtractionPlugin interface, 
        // with pluginInfo() and process() methods. 
        return new MyPlugin();
    }

    @Override
    public Path testPath() {
        // Provide the folder containing input files. For examples, see 
        // https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.
        return srcPath("integration/inputs");
    }

    @Override
    public Path resultPath() {
        // Provide the folder containing result files. For examples, see 
        // https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.
        return srcPath("integration/results");
    }

    @Override
    public boolean regenerate() {
        // Returning false means the test will fail if the result files don't 
        // match the outcome of the=++ test. Returning true means the test create 
        // new result files .
        return false;
    }
}
```

### Remote Testing example

Note that the following example serves the plugin by using `ExtractionServer`.

```java
import static nl.minvenj.nfi.flits.util.FlitsUtil.srcPath;

import java.nio.file.Path;

import org.hansken.plugin.extraction.runtime.grpc.client.ExtractionPluginClient;
import org.hansken.plugin.extraction.runtime.grpc.server.ExtractionPluginServer;
import org.hansken.plugin.extraction.test.plugins.DataTransformationsPlugin;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;

public class RemoteTransformationPluginFlitsIT extends RemoteExtractionPluginFlits {

    private static ExtractionPluginServer _server;
    private static ExtractionPluginClient _client;

    @BeforeAll
    public static void init() throws Exception {
        final int port = 8999;

        // Serve MyPlugin.
        // MyPlugin is a class implementing the ExtractionPlugin interface, with PluginInfo and Process methods.
        _server = ExtractionPluginServer.serve(port, MyPlugin::new);

        // Create an ExtractionPluginClient
        _client = new ExtractionPluginClient("localhost", _server.getListeningPort());
    }

    @AfterAll
    public static void destruct() {
        // At the end of the test, make sure the server and client are closed.
        if (_server != null) {
            _server.close();
        }
        if (_client != null) {
            _client.close();
        }
    }

    @Override
    public Path testPath() {
        // Provide the folder containing input files. For examples, see https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.
        return srcPath("integration/inputs");
    }

    @Override
    public Path resultPath() {
        // Provide the folder containing result files. For examples, see https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.
        return srcPath("integration/results");
    }

    @Override
    protected ExtractionPluginClient pluginToTest() {
        // For Remote testing, the test won't talk directly to the plugin, but to the client. 
        // The client will use gRPC to communicate with the served plugin.
        return _client;
    }

    @Override
    public boolean regenerate() {
        // Returning false means the test will fail if the result files don't match the outcome of the test.
        // Returning true means the test create new result files.
        return false;
    }
}
```

.. note:: Note that with a `RemoteTransformationPluginFlitsIT` it is possible to start a docker image of a plugin and
   run remote tests against it using your own testdata. To do this, simply remove all `_server` code and manually start
   your plugin in a docker container. Then run the test against the docker container by setting the correct url and
   port, presumably `new ExtractionPluginClient("localhost", 8999)`.