Merge pull request #45 from LUMC/release_0.4.0

Release 0.4.0

docs/examples.rst

@@ -0,0 +1,62 @@
+==================
+Examples
+==================
+
+Snakemake example
+-----------------
+
+An example yaml file that could be used to test a snakemake pipeline is listed
+below.
+
+.. code-block:: yaml
+
+    - name: test-dry-run
+      command: snakemake -n -r -p -s Snakefile
+    - name: test-full-run
+      command: snakemake -r -p -s Snakefile
+      files:
+        - "my_output.txt"
+      stderr:
+        contains:
+         - "(100%) done"
+
+WDL with Cromwell example
+-------------------------
+
+Below an example yaml file is explained which can be used to test a WDL
+pipeline run through Cromwell.
+
+One problem with Cromwell is the way it handles relative paths and how it
+handles the input file:
+
++ Relative paths are written only within the ``cromwell-executions`` folder.
+  If you want to write outside this folder you need absolute paths. This is
+  fine but for testing your pipeline ``pytest-workflow`` creates a temporary
+  folder from which the pipeline is run. You don't know beforehand which path
+  this is, but you could use the environment variable ``$PWD``.
++ However the second problem is that inputs can only be supplied to Cromwell in
+  a json file, not on the command line. So you cannot dynamically choose an
+  output folder. You have to rewrite the input file.
+
+To fix this problem you can write ``command`` to be a bash script that injects
+``$PWD`` into the inputs.json.
+
+.. code-block:: yaml
+
+  - name: My pipeline
+    command: >-
+      bash -c '
+      TEST_JSON=tests/inputs/my_pipeline_test1.json ;
+      sed -i "2i\"my_pipeline.output_dir\":\"$PWD/test-output\"," $TEST_JSON ;
+      cromwell run -i $TEST_JSON simple.wdl'
+    files:
+      - path: test-output/moo.txt.gz
+        md5sum: 173fd8023240a8016033b33f42db14a2
+    stdout:
+      contains:
+        - "WorkflowSucceededState"
+
+``sed -i "2i\"my_pipeline.output_dir\":\"$PWD/test-output\"," $TEST_JSON``
+inserts ``"my_pipeline.output_dir":"</pytest/temporary/dir>/test-output",`` on
+the second line of ``$TEST_JSON``. This solves the problem. File paths can now
+be traced from ``test-output`` as demonstrated in the example.

docs/index.rst

@@ -14,7 +14,11 @@ pytest-workflow
 
 .. include:: installation.rst
 
-.. include:: manual.rst
+.. include:: writing_tests.rst
+
+.. include:: running_pytest_workflow.rst
+
+.. include:: examples.rst
 
 .. include:: known_issues.rst
 

docs/running_pytest_workflow.rst

@@ -0,0 +1,74 @@
+=======================
+Running pytest-workflow
+=======================
+Run ``pytest`` from an environment with pytest-workflow installed or
+``python3 -m pytest`` if using a system-wide or user-wide installation.
+Pytest will automatically gather files in the ``tests`` directory starting with
+``test`` and ending in ``.yaml`` or ``.yml``.
+
+The workflows are run automatically. Each workflow gets its own temporary
+directory to run. These directories are cleaned up after the tests are
+completed. If you wish to inspect the output of a failing workflow you can use
+the ``--keep-workflow-wd`` flag to disable cleanup. This will also make sure
+the logs of the pipeline are saved in the temporary directory. When
+``--keep-workflow-wd`` is set, the paths to the logs and the temporary
+directory are reported in pytest's output. The `--keep-workflow-wd`` flag is
+highly recommended when debugging pipelines.
+
+If you wish to change the temporary directory in which the workflows are run
+use ``--basetemp <dir>`` to change pytest's base temp directory.
+
+.. container:: warning
+
+  WARNING: When a directory is passed to ``--basetemp`` some of the directory
+  contents will be deleted. For example: if your workflow is named
+  ``"my workflow"`` then any file or directory named ``my_workflow`` will be
+  deleted. This makes sure you start with a clean slate if you run pytest
+  again with the same ``basetemp`` directory.
+  DO NOT use ``--basetemp`` on directories where none of the
+  contents should be deleted.
+
+To run multiple workflows simultaneously you can use
+``--workflow-threads <int>`` or ``--wt <int>`` flag. This defines the number
+of workflows that can be run simultaneously. This will speed up things if
+you have enough resources to process these workflows simultaneously.
+
+Running specific workflows
+----------------------------
+To run a specific workflow use the ``--tag`` flag. Each workflow is tagged with
+its own name and additional tags in the ``tags`` key of the yaml.
+
+.. code-block:: yaml
+
+  - name: moo
+    tags:
+      - animal
+    command: echo moo
+  - name: cock-a-doodle-doo
+    tags:
+      - rooster sound
+      - animal
+    command: echo cock-a-doodle-doo
+  - name: vroom vroom
+    tags:
+      - car
+    command: echo vroom vroom
+
+With the command ``pytest --tag moo`` only the workflow named 'moo' will be
+run. With ``pytest --tag 'rooster sound'`` only the 'cock-a-doodle-doo'
+workflow will run. Multiple tags can be used like this:
+``pytest --tag 'rooster sound' --tag animal`` This will run all workflows that
+have both 'rooster sound' and 'animal'.
+
+Internally names and tags are handled the same so if the following tests:
+
+.. code-block:: yaml
+
+  - name: hello
+    command: echo 'hello'
+  - name: hello2
+    command: echo 'hello2'
+    tags:
+      - hello
+
+are run with ``pytest --tag hello`` then both ``hello`` and ``hello2`` are run.