You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@nifi.apache.org by peter-gergely-horvath <gi...@git.apache.org> on 2018/07/10 12:52:57 UTC
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
GitHub user peter-gergely-horvath opened a pull request:
https://github.com/apache/nifi/pull/2872
NIFI-5318 Implement NiFi test harness: initial commit of nifi-testharness
All issues are fixed from the previous pull request comments.
Thank you for submitting a contribution to Apache NiFi.
In order to streamline the review of the contribution we ask you
to ensure the following steps have been taken:
### For all changes:
- [x] Is there a JIRA ticket associated with this PR? Is it referenced
in the commit message?
- [x] Does your PR title start with NIFI-XXXX where XXXX is the JIRA number you are trying to resolve? Pay particular attention to the hyphen "-" character.
- [x] Has your PR been rebased against the latest commit within the target branch (typically master)?
- [x] Is your initial contribution a single, squashed commit?
### For code changes:
- [x] Have you ensured that the full suite of tests is executed via mvn -Pcontrib-check clean install at the root nifi folder?
- [ ] Have you written or updated unit tests to verify your changes?
- [ ] If adding new dependencies to the code, are these dependencies licensed in a way that is compatible for inclusion under [ASF 2.0](http://www.apache.org/legal/resolved.html#category-a)?
- [ ] If applicable, have you updated the LICENSE file, including the main LICENSE file under nifi-assembly?
- [ ] If applicable, have you updated the NOTICE file, including the main NOTICE file found under nifi-assembly?
- [ ] If adding new Properties, have you added .displayName in addition to .name (programmatic access) for each of the new properties?
### For documentation related changes:
- [ ] Have you ensured that format looks appropriate for the output in which it is rendered?
### Note:
Please ensure that once the PR is submitted, you check travis-ci for build issues and submit an update to your PR as soon as possible.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/peter-gergely-horvath/nifi master
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/nifi/pull/2872.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #2872
----
commit e4c08a17c6ecd81bbc2032cd7f0e799ab89bc7a4
Author: Peter G. Horvath <pe...@...>
Date: 2018-07-07T09:32:56Z
NIFI-5318 Implement NiFi test harness: initial commit of nifi-testharness
----
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by alopresto <gi...@git.apache.org>.
Github user alopresto commented on the issue:
https://github.com/apache/nifi/pull/2872
I think there should be a Maven module for the test harness which is disabled by default and can be activated with a flag like `mvn clean test -Ptest-harness`.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by lfrancke <gi...@git.apache.org>.
Github user lfrancke commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r201488527
--- Diff: nifi-testharness/src/main/java/org/apache/nifi/testharness/TestNiFiInstance.java ---
@@ -0,0 +1,485 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+
+package org.apache.nifi.testharness;
+
+import org.apache.nifi.testharness.api.FlowFileEditorCallback;
+import org.apache.nifi.EmbeddedNiFi;
+import org.apache.nifi.testharness.util.FileUtils;
+import org.apache.nifi.testharness.util.NiFiCoreLibClassLoader;
+import org.apache.nifi.testharness.util.XmlUtils;
+import org.apache.nifi.testharness.util.Zip;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.zip.ZipEntry;
+
+/**
+ * <p>
+ * An API wrapper of a "test" NiFi instance to which a flow definition is installed for testing.</p>
+ *
+ * <p>
+ * Due to NiFi design restrictions, {@code TestNiFiInstance} has to take <i>full command</i>
+ * of the current working directory: it installs a full NiFi installation to there. To ensure
+ * this is desired, <strong>it will only run if the current directory is called
+ * "nifi_testharness_nifi_home"</strong>. As such the JVM process has to be started inside a directory
+ * called "nifi_testharness_nifi_home" so that the following is true:
+ *
+ * <pre><tt>
+ * new File(System.getProperty("user.dir")).getName().equals("nifi_testharness_nifi_home")
+ * </tt></pre>
+ * </p>
+ *
+ * <p>
+ * Before {@code TestNiFiInstance} can be used, it has to be configured via its builder
+ * interface:
+ * <ul>
+ * <li>
+ * {@link Builder#setFlowXmlToInstallForTesting(File)} specifies the location of the NiFi binary
+ * distribution ZIP file to be used.
+ * </li>
+ * <li>
+ * {@link Builder#setFlowXmlToInstallForTesting(File)} specifies the location of the NiFi flow
+ * to install.
+ * </li>
+ * <li>
+ * {@link Builder#modifyFlowXmlBeforeInstalling(FlowFileEditorCallback)} allows on-the-fly
+ * changes to be performed to the Flow file before it is actually installed.
+ * </li>
+ * </ul>
+ *
+ * <h5>Sample</h5>
+ * <pre><tt>
+ * TestNiFiInstance testNiFiInstance = TestNiFiInstance.builder()
+ * .setNiFiBinaryDistributionZip(YourConstants.NIFI_ZIP_FILE)
+ * .setFlowXmlToInstallForTesting(YourConstants.FLOW_XML_FILE)
+ * .modifyFlowXmlBeforeInstalling(YourConstants.FLOW_FILE_CHANGES_FOR_TESTS)
+ * .build();
+ * </tt></pre>
+ *
+ * </p>
+ *
+ * <p>
+ * If the current working directory is called "nifi_testharness_nifi_home", the caller can
+ * {@link #install()} this {@code TestNiFiInstance}, which will
+ * <ol>
+ * <li>
+ * (as a first cleanup step) erase all content of the current working directory.
+ * (NOTE: this potentially destructive operation is the reason why we have the
+ * "nifi_testharness_nifi_home" directory name guard in place!)
+ * </li>
+ * <li>
+ * Extracts the contents of the NiFi binary distribution ZIP file specified in
+ * the configuration to a to a temporary directory.
+ * <li>
+ * Symlinks all files from the temporary directory to the current working
+ * directory, causing the to hold a fully functional
--- End diff --
missing word
causing the directory
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r228689270
--- Diff: nifi-testharness/src/test/java/org/apache/nifi/testharness/samples/Constants.java ---
@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.nifi.testharness.samples;
+
+import java.io.File;
+
+public final class Constants {
+
+ static final File OUTPUT_DIR = new File("./NiFiTest/NiFiReadTest");
+
+ // NOTE: you will have to have the NiFi distribution ZIP placed into this directory.
+ // Its version must be the same as the one referenced in the flow.xml, otherwise it will not work!
+ static final File NIFI_ZIP_DIR = new File(System.getProperty("user.home"), "Downloads");
--- End diff --
That folder evaluated to `$HOME/Downloads` for my user account when I ran it. Are you expecting the user to sudo or something?
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by lfrancke <gi...@git.apache.org>.
Github user lfrancke commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r201489086
--- Diff: nifi-testharness/src/main/java/org/apache/nifi/testharness/TestNiFiInstance.java ---
@@ -0,0 +1,485 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+
+package org.apache.nifi.testharness;
+
+import org.apache.nifi.testharness.api.FlowFileEditorCallback;
+import org.apache.nifi.EmbeddedNiFi;
+import org.apache.nifi.testharness.util.FileUtils;
+import org.apache.nifi.testharness.util.NiFiCoreLibClassLoader;
+import org.apache.nifi.testharness.util.XmlUtils;
+import org.apache.nifi.testharness.util.Zip;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.zip.ZipEntry;
+
+/**
+ * <p>
+ * An API wrapper of a "test" NiFi instance to which a flow definition is installed for testing.</p>
+ *
+ * <p>
+ * Due to NiFi design restrictions, {@code TestNiFiInstance} has to take <i>full command</i>
+ * of the current working directory: it installs a full NiFi installation to there. To ensure
+ * this is desired, <strong>it will only run if the current directory is called
+ * "nifi_testharness_nifi_home"</strong>. As such the JVM process has to be started inside a directory
+ * called "nifi_testharness_nifi_home" so that the following is true:
+ *
+ * <pre><tt>
+ * new File(System.getProperty("user.dir")).getName().equals("nifi_testharness_nifi_home")
+ * </tt></pre>
+ * </p>
+ *
+ * <p>
+ * Before {@code TestNiFiInstance} can be used, it has to be configured via its builder
+ * interface:
+ * <ul>
+ * <li>
+ * {@link Builder#setFlowXmlToInstallForTesting(File)} specifies the location of the NiFi binary
+ * distribution ZIP file to be used.
+ * </li>
+ * <li>
+ * {@link Builder#setFlowXmlToInstallForTesting(File)} specifies the location of the NiFi flow
+ * to install.
+ * </li>
+ * <li>
+ * {@link Builder#modifyFlowXmlBeforeInstalling(FlowFileEditorCallback)} allows on-the-fly
+ * changes to be performed to the Flow file before it is actually installed.
+ * </li>
+ * </ul>
+ *
+ * <h5>Sample</h5>
+ * <pre><tt>
+ * TestNiFiInstance testNiFiInstance = TestNiFiInstance.builder()
+ * .setNiFiBinaryDistributionZip(YourConstants.NIFI_ZIP_FILE)
+ * .setFlowXmlToInstallForTesting(YourConstants.FLOW_XML_FILE)
+ * .modifyFlowXmlBeforeInstalling(YourConstants.FLOW_FILE_CHANGES_FOR_TESTS)
+ * .build();
+ * </tt></pre>
+ *
+ * </p>
+ *
+ * <p>
+ * If the current working directory is called "nifi_testharness_nifi_home", the caller can
+ * {@link #install()} this {@code TestNiFiInstance}, which will
+ * <ol>
+ * <li>
+ * (as a first cleanup step) erase all content of the current working directory.
+ * (NOTE: this potentially destructive operation is the reason why we have the
+ * "nifi_testharness_nifi_home" directory name guard in place!)
+ * </li>
+ * <li>
+ * Extracts the contents of the NiFi binary distribution ZIP file specified in
+ * the configuration to a to a temporary directory.
+ * <li>
+ * Symlinks all files from the temporary directory to the current working
+ * directory, causing the to hold a fully functional
+ * NiFi installation.
+ * </li>
+ * <li>
+ * Installs the flow definition files(s) to the NiFi instance specified in
+ * the configuration.
+ * </li>
+ * </ol>
+ * </p>
+ *
+ * <p>
+ *
+ * The caller then can proceed to {@link #start()}} this {@code TestNiFiInstance},
+ * which will bootstrap the NiFi engine, which in turn will pick up and start processing
+ * the flow definition supplied by the caller in the configuration.
+ * </p>
+ *
+ * <p>
+ * Once the previous step is done, the caller can perform asserts regarding the observed behaviour
+ * of the NiFi flow, just like one would do it with standard Java test cases.
+ * </p>
+ *
+ * <p>
+ * To perform a clean shutdown of the hosted NiFi instance, the caller is required to call
+ * {@link #stopAndCleanup()}, which will shut down NiFi and remove all temporary files, including
+ * the symlinks created int current working directory.
--- End diff --
typo
int -> in the?
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on the issue:
https://github.com/apache/nifi/pull/2872
> Hi @MikeThomsen sorry for the delay, I have been just very busy.
Thanks. I've got a lot on my plate as well, but will try to find some time early this week to review.
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
That makes sense: I'll look into that... once I have a tiny bit of time...
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r218193985
--- Diff: nifi-docs/src/main/asciidoc/developer-guide.adoc ---
@@ -2296,6 +2296,32 @@ threads that should be used to run the Processor can
be set via the `setThreadCount(int)` method.
+=== Experimental NiFi Flow test harness
+
+NiFi now has an experimental feature for full end-to-end testing of flows. This allows us
+to take a NiFi flow, install it to a test NiFi instance, run it and make Java unit test
+like asserts regarding its behaviour.
+
+The class `org.apache.nifi.test.TestNiFiInstance` is a thin wrapper that allows us
+to manipulate a NiFi installation and deploy a flow with some adjustments
+to its configuration, including changing processor properties and replacing processor
+classes with mocks.
+
+In order to add the necessary classes to your project,
--- End diff --
Just to clarify, you mean external projects that use NiFi. To use this with NiFi's code base, a developer would have to add something to the end of the build system that would run the tests after the assembly is built based on what I've seen reviewing this. Is that right or am I missing something?
Just want to make sure in case we have to answer questions from people come in and try to use this to test their contributions.
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by lfrancke <gi...@git.apache.org>.
Github user lfrancke commented on the issue:
https://github.com/apache/nifi/pull/2872
Thanks! Unfortunately for some reason I can't see your new commit...
(I should maybe also add that I'm not a committer, I wast just interested in this PR)
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r216485286
--- Diff: nifi-testharness/src/test/java/org/apache/nifi/testharness/samples/Constants.java ---
@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.nifi.testharness.samples;
+
+import java.io.File;
+
+public final class Constants {
+
+ static final File OUTPUT_DIR = new File("./NiFiTest/NiFiReadTest");
+ static final File NIFI_ZIP_DIR = new File("../../nifi-assembly/target");
--- End diff --
Do these constants assume a particular location for the code that will instantiate the test harness? That `NIFI_ZIP_DIR` one looks particularly brittle.
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on the issue:
https://github.com/apache/nifi/pull/2872
@peter-gergely-horvath ok. I'm pretty sure that the surefire plugin can be disabled in the POM, but manually activated, so we'll need to look at that because those tests should be runnable if someone wants to modify the test harness and not roll their own test case.
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
Hi @MikeThomsen , hi @alopresto , OK, I've implemented my changes according your recommendations: we now have a dedicated profile for running tests, which is disabled by default.
(If you decide to make the squashed commit, please use the original `peter-gergely-horvath` as author)
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
@MikeThomsen This is kind of tricky: NiFi flows refer the precise version of NiFi within the flow XML file, so you have something like this for the processor definitions:
```
<class>org.apache.nifi.processors.standard.GetHTTP</class>
<bundle>
<group>org.apache.nifi</group>
<artifact>nifi-standard-nar</artifact>
<version>1.7.1</version>
</bundle>
```
When you export a flow file to test, I would expect the you to use precisely the same NiFi version as the one used to export the flow file.
I think there is a little bit of confusion here: please note that these tests do not test the test-harness. The test-harness itself is not tested (kind of a chicken-and-egg issue): these test cases are merely _samples_, which are referenced in the documentation: they demonstrate how an _end-user_ could create test cases for his/her own flows.
Please download the ZIP of NiFi 1.7.1 to the `Downloads` directory within your user home (referenced by `org.apache.nifi.testharness.samples.Constants#NIFI_ZIP_DIR` as
`new File(System.getProperty("user.home"), "Downloads")` ) and try running the test case again.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r218744472
--- Diff: nifi-docs/src/main/asciidoc/developer-guide.adoc ---
@@ -2296,6 +2296,32 @@ threads that should be used to run the Processor can
be set via the `setThreadCount(int)` method.
+=== Experimental NiFi Flow test harness
+
+NiFi now has an experimental feature for full end-to-end testing of flows. This allows us
+to take a NiFi flow, install it to a test NiFi instance, run it and make Java unit test
+like asserts regarding its behaviour.
+
+The class `org.apache.nifi.test.TestNiFiInstance` is a thin wrapper that allows us
+to manipulate a NiFi installation and deploy a flow with some adjustments
+to its configuration, including changing processor properties and replacing processor
+classes with mocks.
+
+In order to add the necessary classes to your project,
--- End diff --
Yes, absolutely. After reading the paragraph once again, I'm wondering if it would make sense to change `us` to `you` (referring to the user), but it is you call, really.
If you think it makes sense, can you do it while you merge/squash the commit?
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r216716909
--- Diff: nifi-testharness/src/test/java/org/apache/nifi/testharness/samples/Constants.java ---
@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.nifi.testharness.samples;
+
+import java.io.File;
+
+public final class Constants {
+
+ static final File OUTPUT_DIR = new File("./NiFiTest/NiFiReadTest");
+ static final File NIFI_ZIP_DIR = new File("../../nifi-assembly/target");
--- End diff --
No, these are in the test cases directory: they are there as a *sample* (referred to in the documentation), and will not be packaged to the actual API artifact.
The paths there refer the NiFi bundle produced during the NiFi build, which seems to be a good default in case you are working on the test harness itself.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by lfrancke <gi...@git.apache.org>.
Github user lfrancke commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r201489283
--- Diff: nifi-testharness/src/main/java/org/apache/nifi/testharness/TestNiFiInstance.java ---
@@ -0,0 +1,485 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+
+package org.apache.nifi.testharness;
+
+import org.apache.nifi.testharness.api.FlowFileEditorCallback;
+import org.apache.nifi.EmbeddedNiFi;
+import org.apache.nifi.testharness.util.FileUtils;
+import org.apache.nifi.testharness.util.NiFiCoreLibClassLoader;
+import org.apache.nifi.testharness.util.XmlUtils;
+import org.apache.nifi.testharness.util.Zip;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.zip.ZipEntry;
+
+/**
+ * <p>
+ * An API wrapper of a "test" NiFi instance to which a flow definition is installed for testing.</p>
+ *
+ * <p>
+ * Due to NiFi design restrictions, {@code TestNiFiInstance} has to take <i>full command</i>
+ * of the current working directory: it installs a full NiFi installation to there. To ensure
+ * this is desired, <strong>it will only run if the current directory is called
+ * "nifi_testharness_nifi_home"</strong>. As such the JVM process has to be started inside a directory
+ * called "nifi_testharness_nifi_home" so that the following is true:
+ *
+ * <pre><tt>
+ * new File(System.getProperty("user.dir")).getName().equals("nifi_testharness_nifi_home")
+ * </tt></pre>
+ * </p>
+ *
+ * <p>
+ * Before {@code TestNiFiInstance} can be used, it has to be configured via its builder
+ * interface:
+ * <ul>
+ * <li>
+ * {@link Builder#setFlowXmlToInstallForTesting(File)} specifies the location of the NiFi binary
+ * distribution ZIP file to be used.
+ * </li>
+ * <li>
+ * {@link Builder#setFlowXmlToInstallForTesting(File)} specifies the location of the NiFi flow
+ * to install.
+ * </li>
+ * <li>
+ * {@link Builder#modifyFlowXmlBeforeInstalling(FlowFileEditorCallback)} allows on-the-fly
+ * changes to be performed to the Flow file before it is actually installed.
+ * </li>
+ * </ul>
+ *
+ * <h5>Sample</h5>
+ * <pre><tt>
+ * TestNiFiInstance testNiFiInstance = TestNiFiInstance.builder()
+ * .setNiFiBinaryDistributionZip(YourConstants.NIFI_ZIP_FILE)
+ * .setFlowXmlToInstallForTesting(YourConstants.FLOW_XML_FILE)
+ * .modifyFlowXmlBeforeInstalling(YourConstants.FLOW_FILE_CHANGES_FOR_TESTS)
+ * .build();
+ * </tt></pre>
+ *
+ * </p>
+ *
+ * <p>
+ * If the current working directory is called "nifi_testharness_nifi_home", the caller can
+ * {@link #install()} this {@code TestNiFiInstance}, which will
+ * <ol>
+ * <li>
+ * (as a first cleanup step) erase all content of the current working directory.
+ * (NOTE: this potentially destructive operation is the reason why we have the
+ * "nifi_testharness_nifi_home" directory name guard in place!)
+ * </li>
+ * <li>
+ * Extracts the contents of the NiFi binary distribution ZIP file specified in
+ * the configuration to a to a temporary directory.
+ * <li>
+ * Symlinks all files from the temporary directory to the current working
+ * directory, causing the to hold a fully functional
+ * NiFi installation.
+ * </li>
+ * <li>
+ * Installs the flow definition files(s) to the NiFi instance specified in
+ * the configuration.
+ * </li>
+ * </ol>
+ * </p>
+ *
+ * <p>
+ *
+ * The caller then can proceed to {@link #start()}} this {@code TestNiFiInstance},
+ * which will bootstrap the NiFi engine, which in turn will pick up and start processing
+ * the flow definition supplied by the caller in the configuration.
+ * </p>
+ *
+ * <p>
+ * Once the previous step is done, the caller can perform asserts regarding the observed behaviour
+ * of the NiFi flow, just like one would do it with standard Java test cases.
+ * </p>
+ *
+ * <p>
+ * To perform a clean shutdown of the hosted NiFi instance, the caller is required to call
+ * {@link #stopAndCleanup()}, which will shut down NiFi and remove all temporary files, including
+ * the symlinks created int current working directory.
+ * </p>
+ *
+ *
+ * <h4>NOTES</h4>
+ * <ul>
+ * <li>
+ * {@code TestNiFiInstance} is NOT thread safe: if more than one thread uses it,
+ * external synchronisation is required.
+ * </li>
+ * <li>
+ * Only one {@code TestNiFiInstance} can be started in the same "nifi_testharness_nifi_home"
+ * directory at the same time.
+ * </li>
+ * <li>
+ * Currently, due to NiFi limitations, one {@TestNiFiInstance} can be started per JVM process.
--- End diff --
wrong javadoc tag
missing "code"
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath closed the pull request at:
https://github.com/apache/nifi/pull/2872
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
@MikeThomsen The pull request contains the latest changes; after @lfrancke had made his comments, I corrected the issues mentioned, nuked my whole fork and force-pushed my new version.
(I'm wondering what the preferred approach is for you, when there are some suggestions regarding a pull request: maybe it would be worth documenting this in NiFi dev manual?)
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r228511342
--- Diff: nifi-testharness/src/test/java/org/apache/nifi/testharness/samples/Constants.java ---
@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.nifi.testharness.samples;
+
+import java.io.File;
+
+public final class Constants {
+
+ static final File OUTPUT_DIR = new File("./NiFiTest/NiFiReadTest");
+
+ // NOTE: you will have to have the NiFi distribution ZIP placed into this directory.
+ // Its version must be the same as the one referenced in the flow.xml, otherwise it will not work!
+ static final File NIFI_ZIP_DIR = new File(System.getProperty("user.home"), "Downloads");
--- End diff --
Since this is an internal unit test, it should be pointing to the build output of nifi-assembly.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r216713844
--- Diff: nifi-testharness/src/main/java/org/apache/nifi/testharness/util/FileUtils.java ---
@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+
+package org.apache.nifi.testharness.util;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.FileVisitResult;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.nio.file.SimpleFileVisitor;
+import java.nio.file.attribute.BasicFileAttributes;
+import java.util.Arrays;
+
+public final class FileUtils {
+
+
+ private static final String MAC_DS_STORE_NAME = ".DS_Store";
+
+ private FileUtils() {
+ // no instances
+ }
+
+ public static void deleteDirectoryRecursive(Path directory) throws IOException {
+ Files.walkFileTree(directory, new SimpleFileVisitor<Path>() {
+ @Override
+ public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
+ Files.delete(file);
+ return FileVisitResult.CONTINUE;
+ }
+
+ @Override
+ public FileVisitResult postVisitDirectory(Path dir, IOException exc) throws IOException {
+ Files.delete(dir);
+ return FileVisitResult.CONTINUE;
+ }
+ });
+ }
+
+ public static void deleteDirectoryRecursive(File dir) {
+ try {
+ deleteDirectoryRecursive(dir.toPath());
+ } catch (IOException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ public static void createLink(Path newLink, Path existingFile) {
+ try {
+ Files.createSymbolicLink(newLink, existingFile);
--- End diff --
No, I have not tested this on Windows. I would expect it to work properly, since [Windows 10 does support symbolic links](https://blogs.windows.com/buildingapps/2016/12/02/symlinks-windows-10/). (you just need the [correct permission](https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links))
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on the issue:
https://github.com/apache/nifi/pull/2872
@peter-gergely-horvath can you push that commit?
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
Hi @MikeThomsen sorry for the delay, I have been just very busy. It turns out there have been some changes in the flow XML format, which I have fixed against the latest GA version: now all of the tests are executed properly.
I have also introduced strict version checking: the NiFi version referenced in the flow file is checked against the actual version of the NiFi distribution used so that we can avoid confusion in the future.
If a user tries to run the test harness with a flow created using a different version of NiFi than the one actually used, this will fail fast, preventing a non functioning installation leaving the user being confused why it does not work properly.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by lfrancke <gi...@git.apache.org>.
Github user lfrancke commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r201495972
--- Diff: nifi-testharness/src/test/java/org/apache/nifi/testharness/samples/TestUtils.java ---
@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+
+package org.apache.nifi.testharness.samples;
+
+import java.io.File;
+
+final class TestUtils {
+
+ private TestUtils() {
+ // no instances allowed
+ }
+
+ static File getBinaryDistributionZipFile(File binaryDistributionZipDir) {
+
+ File[] files = binaryDistributionZipDir.listFiles((dir, name) ->
--- End diff --
This can return `null` which makes the next `if` statement fail with a NPE. I think the condition can be extended to
```
if (files == null || files.length == 0)
```
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r216484221
--- Diff: nifi-testharness/pom.xml ---
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>org.apache.nifi</groupId>
+ <artifactId>nifi</artifactId>
+ <version>1.8.0-SNAPSHOT</version>
+ </parent>
+ <artifactId>nifi-testharness</artifactId>
+ <description>A test harness for running NiFi flow tests</description>
+ <packaging>pom</packaging>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.rat</groupId>
+ <artifactId>apache-rat-plugin</artifactId>
+ <configuration>
+ <excludes combine.children="append">
+ <exclude>nifi_testharness_nifi_home/NIFI_TESTHARNESS_README.txt</exclude>
+ <exclude>src/test/resources/sample_technology_rss.xml</exclude>
+ <exclude>src/test/resources/logback-test.xml</exclude>
+ <exclude>src/test/resources/flow.xml</exclude>
+ </excludes>
+ </configuration>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>compile</goal>
+ <goal>testCompile</goal>
+ </goals>
+ </execution>
+ </executions>
+ <configuration>
+ <source>1.8</source>
+ <target>1.8</target>
+ </configuration>
+ </plugin>
+
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>2.20.1</version>
+ <configuration>
+ <forkCount>1</forkCount>
+ <reuseForks>false</reuseForks>
+ <workingDirectory>nifi_testharness_nifi_home</workingDirectory>
+ </configuration>
+ </plugin>
+
+ </plugins>
+ </build>
+
+
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <org.slf4j.version>1.7.25</org.slf4j.version>
+ <jetty.version>9.4.3.v20170317</jetty.version>
+ </properties>
+
+ <dependencies>
--- End diff --
L&N looks good here.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r216484785
--- Diff: nifi-testharness/src/main/java/org/apache/nifi/testharness/util/FileUtils.java ---
@@ -0,0 +1,88 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+
+package org.apache.nifi.testharness.util;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.FileVisitResult;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.nio.file.SimpleFileVisitor;
+import java.nio.file.attribute.BasicFileAttributes;
+import java.util.Arrays;
+
+public final class FileUtils {
+
+
+ private static final String MAC_DS_STORE_NAME = ".DS_Store";
+
+ private FileUtils() {
+ // no instances
+ }
+
+ public static void deleteDirectoryRecursive(Path directory) throws IOException {
+ Files.walkFileTree(directory, new SimpleFileVisitor<Path>() {
+ @Override
+ public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IOException {
+ Files.delete(file);
+ return FileVisitResult.CONTINUE;
+ }
+
+ @Override
+ public FileVisitResult postVisitDirectory(Path dir, IOException exc) throws IOException {
+ Files.delete(dir);
+ return FileVisitResult.CONTINUE;
+ }
+ });
+ }
+
+ public static void deleteDirectoryRecursive(File dir) {
+ try {
+ deleteDirectoryRecursive(dir.toPath());
+ } catch (IOException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ public static void createLink(Path newLink, Path existingFile) {
+ try {
+ Files.createSymbolicLink(newLink, existingFile);
--- End diff --
Have you tried this on Windows?
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
Hi @lfrancke I've fixed the issues you noticed. Can you please review the current state?
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
@MikeThomsen OK, in the future, I will follow that approach. For this pull request, please review as it is, since the current state contains everything in a squashed commit.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r228606645
--- Diff: nifi-testharness/src/test/java/org/apache/nifi/testharness/samples/Constants.java ---
@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.nifi.testharness.samples;
+
+import java.io.File;
+
+public final class Constants {
+
+ static final File OUTPUT_DIR = new File("./NiFiTest/NiFiReadTest");
+
+ // NOTE: you will have to have the NiFi distribution ZIP placed into this directory.
+ // Its version must be the same as the one referenced in the flow.xml, otherwise it will not work!
+ static final File NIFI_ZIP_DIR = new File(System.getProperty("user.home"), "Downloads");
--- End diff --
This will be relative to the `nifi_testharness_nifi_home` directory, from which the test cases are executed. Since the test case should clear up that directory automatically, I think this should be fine.
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
Closed an created a new pull request for the same issue from a clean state: https://github.com/apache/nifi/pull/3165
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by MikeThomsen <gi...@git.apache.org>.
Github user MikeThomsen commented on the issue:
https://github.com/apache/nifi/pull/2872
@peter-gergely-horvath the consensus seems to be just keep pushing new commits and let us do a squashed commit for you because that helps GitHub maintain the context of feedback in a review.
---
[GitHub] nifi issue #2872: NIFI-5318 Implement NiFi test harness: initial commit of n...
Posted by peter-gergely-horvath <gi...@git.apache.org>.
Github user peter-gergely-horvath commented on the issue:
https://github.com/apache/nifi/pull/2872
Hi @MikeThomsen I _intentionally_ have no test configuration in the project (at least for now): they are merely *samples* of what can be done, but they should not be executed as part of the core NiFi build.
NiFi is a beast, starting and stopping it takes some time, I do not want to add that to the each NiFi build.
Please create a new Maven project quickstart project (that will have testing configuration enabled) and add the following (replacing `${nifi version}` with the current one) to the dependencies:
```
<dependency>
<groupId>org.apache.nifi:</groupId>
<artifactId>nifi-testharness</artifactId>
<version>${nifi version}</version>
</dependency>
```
once done, you can take the samples into your own project, where you can experiment with the test harness.
I understand piggybacking on the tests directory is maybe not the perfect place to deliver samples, but given the circumstances I think it is acceptable and could maybe be improved in the future.
---
[GitHub] nifi pull request #2872: NIFI-5318 Implement NiFi test harness: initial comm...
Posted by lfrancke <gi...@git.apache.org>.
Github user lfrancke commented on a diff in the pull request:
https://github.com/apache/nifi/pull/2872#discussion_r201485489
--- Diff: nifi-testharness/src/main/java/org/apache/nifi/testharness/TestNiFiInstance.java ---
@@ -0,0 +1,485 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+
+package org.apache.nifi.testharness;
+
+import org.apache.nifi.testharness.api.FlowFileEditorCallback;
+import org.apache.nifi.EmbeddedNiFi;
+import org.apache.nifi.testharness.util.FileUtils;
+import org.apache.nifi.testharness.util.NiFiCoreLibClassLoader;
+import org.apache.nifi.testharness.util.XmlUtils;
+import org.apache.nifi.testharness.util.Zip;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.zip.ZipEntry;
+
+/**
+ * <p>
+ * An API wrapper of a "test" NiFi instance to which a flow definition is installed for testing.</p>
+ *
+ * <p>
+ * Due to NiFi design restrictions, {@code TestNiFiInstance} has to take <i>full command</i>
+ * of the current working directory: it installs a full NiFi installation to there. To ensure
+ * this is desired, <strong>it will only run if the current directory is called
+ * "nifi_testharness_nifi_home"</strong>. As such the JVM process has to be started inside a directory
+ * called "nifi_testharness_nifi_home" so that the following is true:
+ *
+ * <pre><tt>
+ * new File(System.getProperty("user.dir")).getName().equals("nifi_testharness_nifi_home")
+ * </tt></pre>
+ * </p>
+ *
+ * <p>
+ * Before {@code TestNiFiInstance} can be used, it has to be configured via its builder
+ * interface:
+ * <ul>
+ * <li>
+ * {@link Builder#setFlowXmlToInstallForTesting(File)} specifies the location of the NiFi binary
--- End diff --
I think this should refer to `setNiFiBinaryDistributionZip` instead
---