nf-core/nf-test guide

sites/docs/src/content/docs/tutorials/tests_and_test_data/components/01_installation.md

@@ -0,0 +1,69 @@
+---
+title: "1. Installation"
+subtitle: Setting up nf-test in your development environment
+weight: 10
+---
+
+## Installing nf-test
+
+**For nf-core pipeline development and testing, you need to install nf-test separately.** nf-core tools only provides test commands for the `nf-core/modules` repository context.
+
+### Prerequisites
+
+Before installing nf-test, ensure you have:
+
+- **Java 11 or higher**
+- **Nextflow** (latest stable version recommended)
+
+### Recommended Installation: Using Conda/Mamba
+
+```bash
+conda create -n nf-core -c bioconda nf-core nf-test
+conda activate nf-core
+# or
+mamba create -n nf-core -c bioconda nf-core nf-test
+mamba activate nf-core
+
+### Alternative Installation Methods
+
+For a standalone binary install: 
+
+```bash
+curl -fsSL https://get.nf-test.com | bash
+```
+
+Move the `nf-test` file to a directory accessible by your `$PATH` variable:
+
+```bash
+# Make it executable and move to PATH
+chmod +x nf-test
+sudo mv nf-test /usr/local/bin/
+```
+
+#### Install specific version
+
+For installing a specific version of nf-test, you can specify this as an option to the install script.
+
+```bash
+curl -fsSL https://get.nf-test.com | bash -s 0.9.0
+```
+
+> **For complete installation instructions and troubleshooting**, visit the [official nf-test installation documentation](https://www.nf-test.com/docs/getting-started/).
+
+### Verification
+
+Verify your installation worked correctly, you can check the version is printed.
+
+```bash
+nf-test version
+```
+
+You can also list all available tests in a repository already with:
+
+```bash
+nf-test list
+```
+
+## Next Steps
+
+Once you have nf-test installed, proceed to [nf-test Commands & Integration](./02_commands_integration.md) to learn the essential commands.

sites/docs/src/content/docs/tutorials/tests_and_test_data/components/02_commands_integration.md

@@ -0,0 +1,107 @@
+---
+title: "2. nf-test Commands & Integration"
+subtitle: Essential commands and nf-core integration
+weight: 20
+---
+
+## Prerequisites
+
+Before running these commands, ensure you have:
+
+- nf-test installed (see [Installation Guide](./01_installation.md))
+- An nf-core pipeline or nf-core/modules repo set up
+- Access to (nf-core) test data (local or remote)
+
+## Understanding Testing Contexts
+
+There are **two main contexts** for running nf-test commands in the nf-core ecosystem:
+
+### 1. nf-core/modules Repository Context
+
+When working in the **nf-core/modules repository**, use `nf-core` tools commands if you are:
+
+- Testing individual modules and subworkflows
+- Contributing to the shared nf-core modules library
+- Use `nf-core modules test` and `nf-core subworkflows test`
+
+nf-core tools modules and subworkflow testing has extra functionality that aids setting up the tests and snapshots (e.g. automatically running a second test to check stability of the output files of a module).
+
+### 2. Individual Pipeline Context
+
+When developing **individual nf-core pipelines**, use `nf-test` commands directly, if you are:
+
+- Testing complete pipeline workflows
+- Pipeline-specific test configurations
+- Use `nf-test test` commands
+
+nf-core tools does not currently provide additional functionality for testing pipeline level tests.
+
+---
+
+## nf-core/modules Repository Reference Commands
+
+> **Note**: These commands only work within the nf-core/modules repository
+
+
+### Module Testing
+
+These commands will tell nf-core to run the test files of `bedtools/bamtobed` module twice, and compare the results to see if they change.
+By giving `--update`, this will update the 'snapshot' that records the state of the results files (in cases where you have made changes to the module).
+By giving `--verbose`, the command will print the Nextflow logging information to console, which is useful for debugging.
+
+```bash
+# Test a specific module
+nf-core modules test bedtools/bamtobed --profile docker
+
+# Update module test snapshots
+nf-core modules test bedtools/bamtobed --profile docker --update
+
+# Test with verbose output
+nf-core modules test bedtools/bamtobed --profile docker --verbose
+```
+
+### Subworkflow Testing
+
+These commands are functionally the same as above, but with subworkflows.
+
+```bash
+# Test a subworkflow
+nf-core subworkflows test vcf_impute_glimpse --profile docker
+
+# Update subworkflow snapshots
+nf-core subworkflows test vcf_impute_glimpse --profile docker --update
+```
+
+---
+
+## Individual Pipeline Commands
+
+> **Note**: Use these commands when working on individual nf-core pipelines. You can use `nf-core/sarek`, `nf-core/methylseq`, `nf-core/rnaseq` as examples.
+
+### Basic Testing
+
+```bash
+# List all available tests
+nf-test list
+
+# Run all available tests (modules, workflow, pipeline etc.) within the repository
+nf-test test --profile test,docker
+
+# Run specific test file
+nf-test test tests/default.nf-test --profile test,docker
+
+# Update snapshots
+nf-test test --profile test,docker --update-snapshot
+
+# Run tests with verbose output
+nf-test test --profile test,docker --verbose
+
+# Run specific test by tag
+nf-test test --tag pipeline --profile test,docker
+```
+
+---
+
+## Next Steps
+
+Continue to [Project Setup](./03_project_setup.md) to configure your testing environment.

sites/docs/src/content/docs/tutorials/tests_and_test_data/components/03_project_setup.md

@@ -0,0 +1,148 @@
+---
+title: "3. Repository Setup"
+subtitle: Configuring your nf-core pipeline repository for testing with nf-test
+weight: 30
+---
+
+## Example nf-core Repository Structure
+
+Here is an example of an nf-core pipeline project with nf-test:
+
+```
+my-pipeline/
+├── main.nf                          # Main pipeline script
+├── nextflow.config                  # Main pipeline configuration
+├── nextflow_schema.json            # Pipeline parameter schema
+├── nf-test.config                  # nf-test configuration
+├── modules.json                    # Module dependencies
+├── tests/                          # Pipeline-level tests
+│   ├── default.nf.test            # Main pipeline test
+│   ├── params-1.nf.test           # Pipeline param-1 test
+|   ├── params-2.nf.test           # Pipeline param-2 test
+│   ├── nextflow.config            # Test-specific config
+│   └── .nftignore                 # Files to ignore in snapshots
+├── conf/                           # Configuration profiles
+│   ├── test.config                # Test profile
+│   ├── test_full.config           # Full test profile
+│   ├── base.config                # Base configuration
+│   └── igenomes.config            # Reference genome configurations
+├── assets/                         # Pipeline assets
+│   ├── samplesheet.csv            # Test samplesheet
+│   └── schema_input.json          # Input validation schema
+├── modules/nf-core/               # Module tests
+│   └── */tests/main.nf.test      # Individual module tests
+├── subworkflows/nf-core/          # Subworkflow tests
+│   └── */tests/main.nf.test      # Individual subworkflow tests
+└── .nf-test/                      # nf-test working directory
+```
+
+### 1. Key Configuration Files
+
+#### `nf-test.config` (Main Configuration)
+
+**Purpose**: Controls nf-test global settings
+
+```groovy
+config {
+    testsDir "."
+    workDir System.getenv("NFT_WORKDIR") ?: ".nf-test"
+    configFile "tests/nextflow.config"
+    ignore 'modules/nf-core/**/*', 'subworkflows/nf-core/**/*'
+    profile "test"
+    triggers 'nextflow.config', 'nf-test.config', 'conf/test.config', 'tests/nextflow.config', 'tests/.nftignore'
+    plugins {
+        load "[email protected]"
+        // Add plugins based on your pipeline needs:
+        // load "[email protected]"    // For BAM file testing
+        // load "[email protected]"    // For VCF file testing
+        // load "[email protected]"  // For FASTQ file testing
+    }
+}
+```
+
+> **For complete configuration options**, see the [official nf-test configuration documentation](https://www.nf-test.com/docs/configuration/).
+
+### Available nf-test Plugins
+
+For nf-core pipeline testing, plugins provide additional functionality to help validate different output file types and ensure data integrity during testing.
+
+Plugins can be customized - like nft-utils, which has been tailored by the nf-core community for automating the capture and validation of pipeline-level outputs.
+
+
+| Plugin Name      | Description/Use                                                                                                              |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **nft-utils**    | Essential utility functions like `getAllFilesFromDir()` and `removeNextflowVersion()` - widely used across nf-core pipelines |
+| **nft-bam**      | Helper functionality for handling SAM/BAM/CRAM files during tests - critical for genomics pipelines                          |
+| **nft-vcf**      | Support for VCF files - utilities for testing variant call format files                                                      |
+| **nft-fasta**    | Support for FASTA files - enables validation and testing of FASTA file formats                                               |
+| **nft-fastq**    | Support for FASTQ files - validation and testing utilities for sequencing data files                                         |
+| **nft-csv**      | Support for CSV files - utilities for testing comma-separated value files                                                    |
+| **nft-compress** | Support for ZIP files - enables testing of compressed file handling                                                          |
+| **nft-anndata**  | Support for AnnData (h5ad) files - utilities for testing single-cell analysis data formats                                   |
+| **nft-tiff**     | Support for TIFF files - enables testing of Tagged Image File Format files                                                   |
+
+> **Note:** For the complete list of available plugins and their latest versions, visit the [nf-test plugins registry](https://plugins.nf-test.com/).
+
+#### `tests/nextflow.config` (Test-Specific Settings)
+
+**Purpose**: Defines parameters and settings specifically for test execution
+This is very similar to your typical nf-core test profiles.
+However one change is the `aws.client.anonymous` option that <XYZ>
+```groovy
+params {
+    modules_testdata_base_path   = 's3://ngi-igenomes/testdata/nf-core/modules/'
+    pipelines_testdata_base_path = 'https://raw.githubusercontent.com/nf-core/test-datasets/PIPELINE_NAME/'
+    input       = "${projectDir}/assets/samplesheet.csv"
+    outdir      = 'results'
+}
+
+process {
+    resourceLimits = [
+        cpus: 2,
+        memory: '3.GB',
+        time: '2.h'
+    ]
+}
+
+aws.client.anonymous = true
+```
+
+## Test Data Integration
+
+nf-core tools 3.3+ includes a command for discovering test datasets, making it easier to refer to these within your tests:
+
+```bash
+# List all available test datasets
+nf-core test-datasets list
+
+# List datasets for a specific branch
+nf-core test-datasets list --branch mag
+
+# Search for specific datasets
+nf-core test-datasets search --branch mag minigut_reads
+
+# Generate download URLs for datasets
+nf-core test-datasets list --branch mag --generate-dl-url
+
+# Generate nf-test compatible paths
+nf-core test-datasets list --branch mag --generate-nf-path
+```
+
+> **Note:** This feature requires [nf-core/tools 3.3+](https://nf-co.re/blog/2025/tools-3_3#new-nf-core-test-datasets-command).
+
+## Generating Tests (Optional)
+
+Most nf-core pipelines already have tests generated. If needed:
+
+```bash
+# Generate test template for a process
+nf-test generate process path/to/main.nf
+
+# Generate test for workflow
+nf-test generate workflow path/to/main.nf
+```
+
+
+## Next Steps
+
+With your project properly configured, proceed to [Testing Modules](./04_testing_modules.md) to start writing comprehensive module tests.