Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new requirements for stub in module guidelines #2621

Merged
merged 7 commits into from
Jul 4, 2024
37 changes: 37 additions & 0 deletions sites/docs/src/content/docs/guidelines/components/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -324,6 +324,43 @@ See the [Bash manual on file operators](https://tldp.org/LDP/abs/html/fto.html)

Alternate suggestions include using `grep -c` to search for a valid string match, or other tool which will appropriately error when the expected output is not successfully created.

### Stubs

#### Stub block must exist

[A stub block](https://www.nextflow.io/docs/latest/process.html#stub) MUST exist for all modules. This is a block of code that replaces the `script` command when the option `-stub` is set. This enables quick testing of the workflow logic, as a "dry-run".

#### Stub block prefix and versions

The stub block MUST include the same variables (e.g. `prefix`) and HEREDOC code as the main script block.

#### Stub files for all output channels
jfy133 marked this conversation as resolved.
Show resolved Hide resolved

The stub block MUST include the creation of at least one file for every output channel (both mandatory and optional), generated with touch, e.g.

```groovy
stub:
"""
touch ${prefix}.txt
"""
mashehu marked this conversation as resolved.
Show resolved Hide resolved
```

jfy133 marked this conversation as resolved.
Show resolved Hide resolved
Ideally, the stub block should reproduce as much as possible the number of, and filenames structure, of the files expected as output.

#### Stub gzip files must use echo and pipe

Stub files that should be output as gzip compressed, MUST use the syntax in the following example:

```bash
echo "" | gzip > ${prefix}.txt.gz
```

:::info{title="Rationale" collapse}
Simply touching a file with the file name ending in `.gz` will break nf-test's Gzip file parser, as the file is not actually gzipped and thus cannot be read.

Therefore we must make sure we generate a valid gzipped file for nf-test to accept it during tests.
:::

## Naming conventions

### Name format of module files
Expand Down
Loading