Update landing page and documentation (#114)

* Improve docs and landing page * Update index and add some icons * Update docs for snapshot testing * Fix typos in documentation
askimed · Aug 30, 2023 · f55b2f8 · f55b2f8
1 parent e267865
commit f55b2f8
Show file tree

Hide file tree

Showing 31 changed files with 404 additions and 112 deletions.
diff --git a/docs/about.md b/docs/about.md
@@ -1 +1,28 @@
-nf-test has been created by [Lukas Forer](https://twitter.com/lukfor) and [Sebastian Schönherr](https://twitter.com/seppinho).  
+---
+hide:
+  - navigation
+  - toc 
+---
+
+# About
+
+nf-test has been created by [Lukas Forer](https://twitter.com/lukfor) and [Sebastian Schönherr](https://twitter.com/seppinho) and is MIT Licensed.
+
+
+[![@lukfor](https://avatars.githubusercontent.com/u/210220?s=64&v=4)](https://github.com/lukfor)
+[![@seppinho](https://avatars.githubusercontent.com/u/1942824?s=64&v=4)](https://github.com/seppinho)
+
+## Contributors
+
+[![@aaron-fishman-achillestx](https://avatars.githubusercontent.com/u/114482275?s=64&v=4)](https://github.com/aaron-fishman-achillestx)
+[![@ivopieniak](https://avatars.githubusercontent.com/u/44971105?s=64&v=4)](https://github.com/ivopieniak)
+[![@byb121](https://avatars.githubusercontent.com/u/3796450?s=64&v=4)](https://github.com/byb121)
+[![@AstrobioMike](https://avatars.githubusercontent.com/u/13923308?s=64&v=4)](https://github.com/AstrobioMike)
+[![@Emiller88](https://avatars.githubusercontent.com/u/20095261?s=64&v=4)](https://github.com/Emiller88)
+
+
+## Statistics
+
+**GitHub**: <br/> ![release downloads](https://img.shields.io/github/downloads/askimed/nf-test/total)
+
+**Bioconda**: <br/> ![conda downloads](https://anaconda.org/bioconda/nf-test/badges/downloads.svg)
diff --git a/docs/assets/example.png b/docs/assets/example.png
diff --git a/docs/assertions/assertions.md → docs/docs/assertions/assertions.md b/docs/assertions/assertions.md → docs/docs/assertions/assertions.md
diff --git a/docs/assertions/fasta.md → docs/docs/assertions/fasta.md b/docs/assertions/fasta.md → docs/docs/assertions/fasta.md
diff --git a/docs/assertions/files.md → docs/docs/assertions/files.md b/docs/assertions/files.md → docs/docs/assertions/files.md
diff --git a/docs/assertions/libraries.md → docs/docs/assertions/libraries.md b/docs/assertions/libraries.md → docs/docs/assertions/libraries.md
diff --git a/docs/assertions/regular-expressions.md → docs/docs/assertions/regular-expressions.md b/docs/assertions/regular-expressions.md → docs/docs/assertions/regular-expressions.md
diff --git a/docs/assertions/snapshots.md → docs/docs/assertions/snapshots.md b/docs/assertions/snapshots.md → docs/docs/assertions/snapshots.md
@@ -10,19 +10,19 @@ A typical snapshot test case takes a snapshot of the output channels or any othe
 
 The `snapshot` keyword creates a snapshot of the object and its `match` method can then be used to check if its contains the expected data from the snap file. The following example shows how to create a snapshot of a workflow channel:
 
-```
+```Groovy
 assert snapshot(workflow.out.channel1).match()
 ```
 
 You can also create a snapshot of all output channels of a process:
 
-```
+```Groovy
 assert snapshot(process.out).match()
 ```
 
 Even the result of a function can be used:
 
-```
+```Groovy
 assert snapshot(function.result).match()
 ```
 
@@ -42,19 +42,19 @@ nf-test test tests/main.nf.test --update-snapshot
 
 It is also possible to include multiple objects into one snapshot:
 
-```
+```Groovy
 assert snapshot(workflow.out.channel1, workflow.out.channel2).match()
 ```
 
 Every object that is serializable can be included into snapshots. Therefore you can even make a snapshot of the complete workflow or process object. This includes stdout, stderr, exist status, trace etc.  and is the easiest way to create a test that checks for all of this properties:
 
-```
+```Groovy
 assert snapshot(workflow).match()
 ```
 
 You can also include output files to a snapshot (e.g. useful in pipeline tests where no channels are available):
 
-```
+```Groovy
 assert snapshot(
     workflow,
     path("${params.outdir}/file1.txt"),
@@ -63,16 +63,21 @@ assert snapshot(
 ).match()
 ```
 
-By default the snapshot has the same name as the test. You can also store a snapshot under a user defined name. This enables you to use multiple snapshots in one single test and to separate them in a logical way. In the following example a workflow snapshot is created, stored under the name "workflow". The second example, creates a snaphot of two files and saves it under "files".
+By default the snapshot has the same name as the test. You can also store a snapshot under a user defined name. This enables you to use multiple snapshots in one single test and to separate them in a logical way. In the following example a workflow snapshot is created, stored under the name "workflow".
 
-```
+```Groovy
 assert snapshot(workflow).match("workflow")
+```
+
+The next example creates a snaphot of two files and saves it under "files".
+
+```Groovy
 assert snapshot(path("${params.outdir}/file1.txt"), path("${params.outdir}/file2.txt")).match("files")
 ```
 
 You can also use helper methods to add objects to snapshots. For example, you can use the `list()`method to add all files of a folder to a snapshot:
 
-```
+```Groovy
  assert snapshot(workflow, path(params.outdir).list()).match()
 ```
 

diff --git a/docs/cli/clean.md → docs/docs/cli/clean.md b/docs/cli/clean.md → docs/docs/cli/clean.md
diff --git a/docs/cli/generate.md → docs/docs/cli/generate.md b/docs/cli/generate.md → docs/docs/cli/generate.md
diff --git a/docs/cli/init.md → docs/docs/cli/init.md b/docs/cli/init.md → docs/docs/cli/init.md
@@ -10,5 +10,5 @@ The `init` command set ups nf-test in the current directory.
 
 The `init` command creates the following files: `nf-test.config` and `tests/nextflow.config`. It also creates a folder `tests` which is the home directory of your test code.
 
-In the [configuration](configuration.md) section you can learn more about these files and how to customize the directory layout.
+In the [configuration](/configuration.md) section you can learn more about these files and how to customize the directory layout.
 
diff --git a/docs/cli/list.md → docs/docs/cli/list.md b/docs/cli/list.md → docs/docs/cli/list.md
diff --git a/docs/cli/test.md → docs/docs/cli/test.md b/docs/cli/test.md → docs/docs/cli/test.md
diff --git a/docs/configuration.md → docs/docs/configuration.md b/docs/configuration.md → docs/docs/configuration.md
diff --git a/docs/getting-started.md → docs/docs/getting-started.md b/docs/getting-started.md → docs/docs/getting-started.md
@@ -15,7 +15,7 @@ cd nf-test-examples
 
 The pipeline consists of three modules (`salmon.index.nf`, `salmon_align_quant.nf`,`fastqc.nf`). Here, we use the [`salmon.index.nf`]() process to create a test case from scratch. This process takes a reference as an input and creates an index using salmon.
 
-## Init
+## Init new project
 
 Before creating test cases, we use the `init` command to setup nf-test.
 

diff --git a/docs/nftest_pipelines.md → docs/docs/nftest_pipelines.md b/docs/nftest_pipelines.md → docs/docs/nftest_pipelines.md
diff --git a/docs/plugins/developing-plugins.md → docs/docs/plugins/developing-plugins.md b/docs/plugins/developing-plugins.md → docs/docs/plugins/developing-plugins.md
diff --git a/docs/plugins/using-plugins.md → docs/docs/plugins/using-plugins.md b/docs/plugins/using-plugins.md → docs/docs/plugins/using-plugins.md
diff --git a/docs/running-tests.md → docs/docs/running-tests.md b/docs/running-tests.md → docs/docs/running-tests.md
diff --git a/docs/testcases/global_variables.md → docs/docs/testcases/global_variables.md b/docs/testcases/global_variables.md → docs/docs/testcases/global_variables.md
diff --git a/docs/docs/testcases/index.md b/docs/docs/testcases/index.md
@@ -0,0 +1 @@
+# Documentation
diff --git a/docs/testcases/nextflow_function.md → docs/docs/testcases/nextflow_function.md b/docs/testcases/nextflow_function.md → docs/docs/testcases/nextflow_function.md
diff --git a/docs/testcases/nextflow_pipeline.md → docs/docs/testcases/nextflow_pipeline.md b/docs/testcases/nextflow_pipeline.md → docs/docs/testcases/nextflow_pipeline.md
diff --git a/docs/testcases/nextflow_process.md → docs/docs/testcases/nextflow_process.md b/docs/testcases/nextflow_process.md → docs/docs/testcases/nextflow_process.md
diff --git a/docs/testcases/nextflow_workflow.md → docs/docs/testcases/nextflow_workflow.md b/docs/testcases/nextflow_workflow.md → docs/docs/testcases/nextflow_workflow.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,75 +1,166 @@
-# Welcome to nf-test 🚀
+---
+hide:
+  - navigation
+  - toc 
+---
 
-nf-test is a simple test framework for Nextflow pipelines.
+![](assets/example.png){ .right .image}
 
+# Simple testing framework for Nextflow pipelines
 
-[:fontawesome-solid-book: Getting Started](getting-started.md){ .md-button .md-button--primary} [:fontawesome-solid-download: Installation](installation.md){ .md-button } [:fontawesome-brands-github: Source](https://github.com/askimed/nf-test){ .md-button }
 
-## Test your pipeline
-Let's start with a simple example to test the [Hello World](https://github.com/nextflow-io/hello) Nextflow pipeline. To run it, copy/paste the code into a text file (e.g. `hello-world.test`) and run it with `nf-test test hello-world.test`.
+Test your production ready Nextflow pipelines in an efficient and automated way. 🚀
 
-```Groovy
-nextflow_pipeline {
 
-  name "Test Hello World"
-  script "nextflow-io/hello"
+[:fontawesome-solid-book: Getting Started](docs/getting-started.md){ .md-button .md-button--primary} [:fontawesome-solid-download: Installation](installation.md){ .md-button } [:fontawesome-brands-github: Source](https://github.com/askimed/nf-test){ .md-button }
 
-  test("hello world example should start 4 processes") {
+---
 
-    expect {
-      with(workflow){
-        assert success
-        //analyze Nextflow trace file
-        assert trace.tasks().size() == 4
-        //Verify if strings have been written to stdout object
-        assert "Ciao world!" in stdout
-        assert "Bonjour world!" in stdout
-        assert "Hello world!" in stdout
-        assert "Hola world!" in stdout
+[:material-check-circle:]() A DSL language **similar to Nextflow**  <br/>
+[:material-check-circle:]() Describes expected behavior using 'when' and 'then' blocks <br/>
+[:material-check-circle:]() Abundance of functions for writing **elegant and readable assertions** <br/>
+[:material-check-circle:]() Utilizes **snapshots** to write tests for complex data structures <br/>
+[:material-check-circle:]() Provides commands for **generating boilerplate** code <br/>
+[:material-check-circle:]() Includes a **test-runner** that executes these scripts <br/>
+[:material-check-circle:]() Easy installation on **CI systems** <br/>
+
+---
+
+## :material-check-all: Unit testing
+
+nf-test enables you to test all components of your data science pipeline: from end-to-end testing of the entire pipeline to specific tests of processes or even custom functions. This ensures that all testing is conducted consistently, promoting reliability across your project.
+
+=== ":fontawesome-solid-diagram-project: Pipeline"
+
+    ```Groovy
+    nextflow_pipeline {
+
+      name "Test Hello World"
+      script "nextflow-io/hello"
+
+      test("hello world example should start 4 processes") {
+        expect {
+          with(workflow) {
+            assert success
+            assert trace.tasks().size() == 4
+            assert "Ciao world!" in stdout
+            assert "Bonjour world!" in stdout
+            assert "Hello world!" in stdout
+            assert "Hola world!" in stdout
+          }
+        }
       }
+
     }
-  }
-}
-```
-## Test your process
-In the nf-test script below we add some basic checks to a process of a [recently published pipeline](https://github.com/GoekeLab/bioinformatics-workflows/tree/master/nextflow).
+    ```
+
+=== ":material-square-circle: Process"
 
-```Groovy
-nextflow_process {
+    ```Groovy
+    nextflow_process {
 
-    name "Test Process SALMON_INDEX"
-    script "modules/local/salmon_index.nf"
-    process "SALMON_INDEX"
+        name "Test Process SALMON_INDEX"
+        script "modules/local/salmon_index.nf"
+        process "SALMON_INDEX"
 
-    test("Should create channel index files") {
+        test("Should create channel index files") {
 
-        when {
-            process {
-                """
-                input[0] = file("test_data/transcriptome.fa")
-                """
+            when {
+                process {
+                    """
+                    input[0] = file("test_data/transcriptome.fa")
+                    """
+                }
             }
-        }
 
-        then {
-            //check if test case succeeded
-            assert process.success
-            //analyze trace file
-            assert process.trace.tasks().size() == 1
-            with(process.out) {
-                // check if emitted output has been created
-                assert index.size() == 1
-                // count amount of created files
-                assert path(index.get(0)).list().size() == 16
-                // parse info.json file
-                def info = path(index.get(0)+'/info.json').json
-                assert info.num_kmers == 375730
-                assert info.seq_length == 443050
-                //verify md5 checksum
-                assert path(index.get(0)+'/info.json').md5 == "80831602e2ac825e3e63ba9df5d23505"
+            then {
+                //check if test case succeeded
+                assert process.success
+                //analyze trace file
+                assert process.trace.tasks().size() == 1
+                with(process.out) {
+                    // check if emitted output has been created
+                    assert index.size() == 1
+                    // count amount of created files
+                    assert path(index.get(0)).list().size() == 16
+                    // parse info.json file
+                    def info = path(index.get(0)+'/info.json').json
+                    assert info.num_kmers == 375730
+                    assert info.seq_length == 443050
+                    //verify md5 checksum
+                    assert path(index.get(0)+'/info.json').md5 == "80831602e2ac825e3e63ba9df5d23505"
+                }
             }
+
         }
+
     }
-}
+    ```
+
+=== ":material-square-root: Functions"
+    ```Groovy
+    nextflow_function {
+
+        name "Test functions"
+        script "functions.nf"
+
+        test("Test function1") {
+          function "function1"
+          ...
+        }
+
+        test("Test function2") {
+          function "function2"
+          ...
+        }
+    }
+    ```
+
+:material-arrow-right: Learn more about [pipeline tests](docs/testcases/nextflow_pipeline), [workflow tests](docs/testcases/nextflow_workflow), [process tests](docs/testcases/nextflow_process) and [function tests](docs/testcases/nextflow_function) in the documentation.
+
+---
+
+## :material-content-save-check: Snapshot testing
+
+nf-test supports **snapshot testing** and automatically **generates a baseline set of unit tests** to safeguard against regressions caused by changes.</br>nf-test captures a snapshot of output channels or any other objects and subsequently compares them to reference snapshot files stored alongside the tests. If the two snapshots do not match, the test will fail
+
+:material-arrow-right: [Learn more](docs/assertions/snapshots)
+
+---
+
+## :material-power-plug-outline: Highly extendable
+
+nf-test supports the **inclusion of third-party libraries** (e.g., jar files) or functions from Groovy files. This can be done to either extend its functionality or to prevent code duplication, thus maintaining simplicity in the logic of test cases. Given that many assertions are specific to use cases, nf-test incorporates a **plugin system** that allows for the extension of existing classes with custom methods. For example [FASTA file support](docs/assertions/fasta).
+
+:material-arrow-right: [Learn more](docs/assertions/libraries)
+
+---
+
+## :material-star: Support us
+
+We love stars as much as we love rockets! So make sure you [star us on GitHub](https://github.com/askimed/nf-test).
+
+<!-- Place this tag where you want the button to render. -->
+<a class="github-button" href="https://github.com/askimed/nf-test" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star askimed/nf-test on GitHub">Star</a>
+
+Show the world your Nextflow pipeline is using nf-test and at the following badge to your `REAMDE.md`:
+
+[![nf-test](https://img.shields.io/badge/tested_with-nf--test-337ab7.svg)](https://code.askimed.com/nf-test)
 
 ```
+[![nf-test](https://img.shields.io/badge/tested_with-nf--test-337ab7.svg)](https://code.askimed.com/nf-test)
+```
+
+----
+
+## :material-account-supervisor: About
+
+nf-test has been created by [Lukas Forer](https://twitter.com/lukfor) and [Sebastian Schönherr](https://twitter.com/seppinho) and is MIT Licensed.
+
+
+[![@lukfor](https://avatars.githubusercontent.com/u/210220?s=64&v=4)](https://github.com/lukfor)
+[![@seppinho](https://avatars.githubusercontent.com/u/1942824?s=64&v=4)](https://github.com/seppinho)
+
+Thanks to all the [contributors](about.md) to help us maintaining and improving nf-test!
+
+---
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,3 +1,5 @@
+
+
 # Installation
 
 nf-test has the same requirements as Nextflow and can be used on POSIX compatible systems like Linux or OS X. You can install nf-test using the following command:
@@ -14,6 +16,8 @@ wget -qO- https://code.askimed.com/install/nf-test | bash
 
 It will create the `nf-test` executable file in the current directory. Optionally, move the `nf-test` file to a directory accessible by your `$PATH` variable.
 
+### Verify installation
+
 Test the installation with the following command:
 
 ```sh
@@ -47,7 +51,12 @@ If you want to install a specific version pass it to the install script as so
 curl -fsSL https://code.askimed.com/install/nf-test | bash -s 0.7.0
 ```
 
-### Nextflow Binary not found
+### Manual installation
+
+All releases are also available on [Github](https://github.com/askimed/nf-test/releases).
+
+
+### Nextflow Binary not found?
 
 If you get an error message like this, then nf-test was not able to detect your Nextflow installation.
 
@@ -73,12 +82,10 @@ To update an existing nf-test installtion to the latest version, run the followi
 nf-test update
 ```
 
-## Manual installation
-
-All releases are also available on [Github](https://github.com/askimed/nf-test/releases).
-
 ## Compiling from source
+
 To compile nf-test from source you shall have maven installed. This will produce a `nf-test/target/nf-test.jar` file.
+
 ```
 git clone [email protected]:askimed/nf-test.git
 cd nf-test