- Refactoring to support Docker pipeline execution

- Better handling of test execution timeout
- Extends tests for utils
- Adds a Docker-specific gradle task
- Better gitignore

Author: Alan Christie

.gitignore

@@ -12,3 +12,4 @@ work
 .nextflow.log*
 /tmp
 **/*.egg-info
+**/.DS_Store

README.md

@@ -54,10 +54,13 @@ of the number of test files and individual tests that were executed: -
     -------
     Summary
     -------
-    Test Files   :   20
-    Tests        :   30
-    Tests ignored:    0
-    Tests failed :    0
+    Test Files    :   20
+    Tests Found   :   30
+    Tests passed  :   30
+    Tests failed  :    0
+    Tests skipped :    0
+    Tests ignored :    0
+    Warnings      :    0
     -------
     Passed: TRUE
 
@@ -68,8 +71,27 @@ across all the repositories by running the tester from here. Simply
 run the following Gradle command from here: -
 
     $ ./gradlew runPipelineTester
+
+### In Docker
+You can run the pipeline tests in Docxker using their expected container
+image (defined in the service descriptor). Doing this gives you added
+confidence that your pipeline will work wen deployed.
+
+To run in Docker you need to add the `-d` or `--indocker` command-line
+argument. To pass these variables through Gradle into the pipeline tester
+run the tests like this: -
+
+    $ ./gradlew runPipelineTester -Pptargs=-d
+
+Or by using the Docker-specific gradle command:
+
+    $ ./gradlew runDockerPipelineTester
+    
+>   When you run _in docker_ only the tests that can run in Docker (those with
+    a defined image name) will be executed. Tests that cannot be executed in
+    Docker will be _skipped_.
 
-### Debugging test failures
+## Debugging test failures
 Ideally your tests will pass. When they don't the test framework prints
 the collected log to the screen as it happens but also keeps all the files
 generated (by all the tests) in case they are of use for diagnostics.
@@ -102,6 +124,13 @@ in order to create a set of tests for a new pipeline.
 >   At the moment the tester only permits one test file per pipeline so all 
     tests for a given pipeline need to be composed in one file. 
 
+## Testing the pipeline utilities
+The pipeline utilities consist of a number of Python-based modules
+that can be tested using `setup.py`. To test these modules run the
+following from the `src/python` directory: -
+
+    $ python setup.py test
+ 
 ---
 
 [Conda]: https://conda.io/docs/

build.gradle

@@ -34,3 +34,12 @@ task runPipelineTester(type: Exec) {
     commandLine 'groovy', 'PipelineTester.groovy', "$args"
 
 }
+
+task runDockerPipelineTester(type: Exec) {
+
+    description 'Runs the PipelineTester Docker tests'
+
+    workingDir 'src/groovy'
+    commandLine 'groovy', 'PipelineTester.groovy', '-indocker'
+
+}

pipeline.test.template

@@ -31,12 +31,19 @@
     //          file. Individual tests can define their own test-specific files
     //          with their own 'creates' block, discussed later in this file.
     //
+    // pin:     This property can be used to over-ride the automatically
+    //          generated data input path (which is typically the repository's
+    //          own data directory. This allows you to use date outside the
+    //          repository - maybe because it's a large file or an experimental
+    //          file.
+    //
     // There can only be one setup_collection section and it must be
     // the first section in the file.
 
     setup_collection = [
         timeout: 10,
-        creates: [ 'output.txt' ]
+        creates: [ 'output.txt' ],
+        pin: /Users/alan/data
     ],
 
     // Individual tests.
@@ -60,6 +67,8 @@
     //
     // If a test is not working an you want to keep it and avoid running it
     // then simply prefix the test section name with `ignore_`.
+    //
+    // The location of any input data you provide in your test
 
     test_1 = [
 

src/groovy/ContainerExecutor.groovy

@@ -0,0 +1,65 @@
+#!/usr/bin/env groovy
+
+/**
+ * Copyright (c) 2018 Informatics Matters Ltd.
+ *
+ * Licensed 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.
+ */
+
+/**
+ * The PipelineTester Container Executor class. The class is responsible for
+ * executing a pipeline command in the supplied Docker container image.
+ */
+class ContainerExecutor {
+
+    /**
+     * Executes the given command in the supplied container image.
+     *
+     * @param imageName The image to run the command in
+     * @param command The command to run
+     * @param timeoutSeconds The time to allow for the command to execute
+     * @return A list containing the STDOUT and STDERR encapsulated in a
+     *         StringBuilder(), an integer command exit code and a timeout
+     *         boolean (set if the program execution timed out)
+     */
+    static execute(String command, String imageName,
+                   String pin, String pout,
+                   int timeoutSeconds) {
+
+        StringBuilder sout = new StringBuilder()
+        StringBuilder serr = new StringBuilder()
+
+        String cmd = "docker run -v $pin:/data -v $pout:/output" +
+                     " -w /output -e PIN=/data -e POUT=/output $imageName" +
+                     " sh -c '$command'"
+
+        def proc = ['sh', '-c', cmd].execute(null, new File('.'))
+        proc.consumeProcessOutput(sout, serr)
+        proc.waitForOrKill((long)timeoutSeconds * 1000)
+        int exitValue = proc.exitValue()
+
+        // Timeout?
+        //
+        // Some exit codes have a special meaning.
+        //
+        // We can, for example, assume that the process was killed
+        // if the exit code is 143 as 143, which is 128 + 15, means
+        // the program died with signal 15 (SIGTERM).
+        // See http://www.tldp.org/LDP/abs/html/exitcodes.html.
+        boolean timeout = exitValue == 143 ? true : false
+
+        return [sout, serr, exitValue, timeout]
+
+    }
+
+}