0.6.3

0.6.3/_sources/dev/java/testing.md.txt

@@ -0,0 +1,156 @@
+# 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)`.