Add nf-test unit coverage for critical fgbio processes

[Copilot]

This PR adds process-level nf-test coverage for critical non-Python steps, starting with groupreadsbyumi, callduplexconsensusreads, and filterconsensusreads. It also establishes reusable module-test infrastructure so additional process tests can be added with minimal friction.

• Process-level unit tests (nf-test)

  • Added new nf-test process suites for:
    • FGBIO_GROUPREADSBYUMI
    • FGBIO_CALLDUPLEXCONSENSUSREADS
    • FGBIO_FILTERCONSENSUSREADS
  • Added one additional fgbio process test:
    • FGBIO_COLLECTDUPLEXSEQMETRICS
  • Tests validate emitted channels/filenames and metadata propagation per process contract.

• Stub support for targeted critical modules

  • Added stub: blocks to the three requested critical process modules so unit tests can run in isolated mode without full runtime inputs/tooling.
  • Stub outputs mirror expected emitted artifacts and include versions.yml.

• Module test scaffolding

  • Added tests/modules/nextflow.config for local, self-contained process test execution.
  • Added lightweight fixtures under tests/test_data/modules/fgbio/ for deterministic module tests.

• Documentation updates

  • Updated tests/README.md with new module-test layout and direct commands for running process-level nf-test suites.

nextflow_process {
    script "../../../modules/nf-core/fgbio/groupreadsbyumi/main.nf"
    process "FGBIO_GROUPREADSBYUMI"

    test("stub run emits grouped BAM and histogram") {
        options "-stub"
        when {
            process {
                """
                input[0] = [[id: 'B5'], file(params.module_testdata_base + '/B5.tagged.bam', checkIfExists: true)]
                input[1] = 'paired'
                """
            }
        }
        then {
            assert process.out.bam[0][1].name == 'B5_umi-grouped.bam'
            assert process.out.histogram[0][1].name == 'B5_umi_histogram.txt'
        }
    }
}

• Fixes add unit tests #199

[FerriolCalvet]

@copilot can you expand the coverage to more modules?

[migrau]

(nextflow.24.10.4) [mgrau@irbccn27 deepUMIcaller_unitests]$ nf-test test tests/modules/fgbio/*.nf.test tests/modules/local/*.nf.test --tag real_data --update-snapshot

🚀 nf-test 0.9.5
https://www.nf-test.com
Please cite: https://doi.org/10.1093/gigascience/giaf130
(c) 2021 - 2026 Lukas Forer and Sebastian Schoenherr

Load .nf-test/plugins/nft-utils/0.0.3/nft-utils-0.0.3.jar
Warning: every snapshot that fails during this test run is re-recorded.

Test Process FGBIO_CALLDUPLEXCONSENSUSREADS

  Test [fde5bd70] 'real run on B5 subset matches snapshot' PASSED (16.067s)
  Snapshots:
    1 updated [real run on B5 subset matches snapshot]
    Obsolete snapshots can only be checked if all tests of a file are executed successful.

Test Process FGBIO_COLLECTDUPLEXSEQMETRICS

  Test [f1f42e2a] 'real run on B5 subset matches snapshot' PASSED (17.838s)
  Snapshots:
    1 updated [real run on B5 subset matches snapshot]
    Obsolete snapshots can only be checked if all tests of a file are executed successful.

Test Process FGBIO_FILTERCONSENSUSREADS

  Test [257b212e] 'real run on B5 subset matches snapshot' PASSED (21.267s)
  Snapshots:
    1 updated [real run on B5 subset matches snapshot]
    Obsolete snapshots can only be checked if all tests of a file are executed successful.

Test Process FGBIO_GROUPREADSBYUMI

  Test [9bb33094] 'real run on B5 subset matches snapshot' PASSED (15.912s)
  Snapshots:
    Obsolete snapshots can only be checked if all tests of a file are executed successful.

Test Process ASMINUSXS

  Test [8e3889e5] 'real run on B5 subset matches snapshot' PASSED (9.977s)
  Snapshots:
    Obsolete snapshots can only be checked if all tests of a file are executed successful.

Test Process MERGEBAM

  Test [48ba9055] 'real run on B5 subset parts matches snapshot' PASSED (9.583s)
  Snapshots:
    1 updated [real run on B5 subset parts matches snapshot]
    Obsolete snapshots can only be checked if all tests of a file are executed successful.

Test Process SAMTOOLS_FILTER

  Test [72b71ce9] 'real run on B5 subset matches snapshot' PASSED (9.856s)
  Snapshots:
    Obsolete snapshots can only be checked if all tests of a file are executed successful.

Test Process UNMAP_BAM

  Test [2f5c344b] 'real run on B5 subset matches snapshot' PASSED (9.739s)
  Snapshots:
    Obsolete snapshots can only be checked if all tests of a file are executed successful.


Snapshot Summary:
  4 updated

SUCCESS: Executed 8 tests in 110.382s

[migrau]

Summary

Adds process-level nf-test unit tests for the modules involved in the fgbio → fgumi migration, so a regression can be traced to a single module instead of only surfacing as a diff in the final VCF. Each covered module now has two test variants:

• -stub (fast, no real data): verifies process wiring — input/output channels, emitted file names. Runs in seconds, no containers or fixtures required.
• real_data (tagged real_data): runs the real tool against a small real slice of sample B5 and compares the output against a committed nf-test snapshot. This is what actually catches behavioral regressions.

New coverage

• fgbio/fgumi substitution points (both stub + real_data): FGBIO_GROUPREADSBYUMI, FGBIO_CALLDUPLEXCONSENSUSREADS, FGBIO_FILTERCONSENSUSREADS, FGBIO_COLLECTDUPLEXSEQMETRICS
• Downstream/control modules (both stub + real_data, shouldn't diverge — confirms the change stays contained): UNMAP_BAM, MERGEBAM, ASMINUSXS, SAMTOOLS_FILTER
• Previously fully untested (stub only): the VarDict calling chain (SPLIT_BED, CALLING_VARDICT_CHUNK, MERGE_VARDICT_RESULTS)

Real fixtures

real_data tests need a small real BAM subset of sample B5, generated locally (not committed — see .gitignore) via:

./tests/test_data/modules/generate_real_fixtures.sh
nf-test test tests/modules/fgbio/*.nf.test tests/modules/local/*.nf.test --tag real_data --update-snapshot
tests/test_data/modules/publish_intermediates.config is an optional helper to force-publish the intermediate BAMs from a fresh end-to-end run, for generating fixtures from a specific pipeline version instead of the existing reference run.

Test plan

• All 12 -stub tests pass (--tag stub)
• All 8 real_data tests pass against real B5 fixtures generated from a fresh end-to-end run on the IRB cluster
• Re-run --tag real_data on copilot/replace-fgbio-with-fgumi against the same fixtures/snapshots to confirm which module(s), if any, diverge