@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/implement-galaxy-workflow-test/_provenance.json

@@ -0,0 +1,201 @@
+{
+  "provenance_schema_version": 4,
+  "cast_target": "claude",
+  "mold": {
+    "name": "implement-galaxy-workflow-test",
+    "path": "content/molds/implement-galaxy-workflow-test/index.md",
+    "revision": 8,
+    "content_hash": "966c486ccda2eb1e0f06afa674c5d6b85a7e7bfcc9b1545309e3ef8b1016f931",
+    "commit": "63a3f9cf9c97a637fe1628d298e524f35709e289"
+  },
+  "cast_at": "2026-09-13T20:58:28.168Z",
+  "cast_date": "2026-07-20",
+  "cast_revision": 1,
+  "cast_history": [
+    {
+      "rev": 1,
+      "date": "2026-07-20",
+      "note": "planemo 0.75.45"
+    }
+  ],
+  "refs": [
+    {
+      "kind": "cli-command",
+      "mode": "sidecar",
+      "ref": "[[validate-tests]]",
+      "src": "content/cli/gxwf/validate-tests.md",
+      "dst": "references/cli/validate-tests.json",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Run the cheap static workflow-test validation and workflow-label cross-check before Planemo execution.",
+      "trigger": "After authoring or editing a Galaxy workflow test file and before Planemo invocation.",
+      "src_hash": "7157ef7750ead142086e0597d52d2ef6ef072e8ec2939f2ac6965bdccf04849d",
+      "dst_hash": "973184698733ffb86bb5a15781902846afec311047f5684f779f8ad023e5d24c",
+      "source": "deterministic"
+    },
+    {
+      "kind": "cli-tool",
+      "mode": "verbatim",
+      "ref": "[[planemo]]",
+      "src": "content/cli/planemo/index.md",
+      "dst": "references/cli/planemo.md",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "corpus-observed",
+      "purpose": "Runtime for workflow_test_init / workflow_test_on_invocation; install before authoring tests against a live invocation.",
+      "src_hash": "12e8cac3ffb4ab7f007ced7a8d4f01e6b3785d06a55926496bbacc0a8f3fc5c5",
+      "dst_hash": "12e8cac3ffb4ab7f007ced7a8d4f01e6b3785d06a55926496bbacc0a8f3fc5c5",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[galaxy-workflow-testability-design]]",
+      "src": "content/research/galaxy-workflow-testability-design/index.md",
+      "dst": "references/notes/galaxy-workflow-testability-design.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Revise workflow inputs, outputs, labels, checkpoints, and collection identifiers so meaningful tests can be authored.",
+      "trigger": "When test authoring reveals missing labels, omitted workflow-level outputs, unstable collection identifiers, weakly assertable final outputs, or fixture-shape pressure on workflow inputs.",
+      "src_hash": "81b01801ec3d14810d570dd2d7815da2bb11e41a562af9182c29fd2974f4b855",
+      "dst_hash": "81b01801ec3d14810d570dd2d7815da2bb11e41a562af9182c29fd2974f4b855",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[iwc-shortcuts-anti-patterns]]",
+      "src": "content/research/iwc-shortcuts-anti-patterns/index.md",
+      "dst": "references/notes/iwc-shortcuts-anti-patterns.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Flag assertion shortcuts that are acceptable in IWC versus shortcuts that should be avoided.",
+      "trigger": "When considering existence-only, size-only, image-only, checksum, output-label, or negative-test patterns.",
+      "src_hash": "14cc27c6a3e01588b06151535afdcb671cadd8e10dc960a248934e9133ebc8ab",
+      "dst_hash": "14cc27c6a3e01588b06151535afdcb671cadd8e10dc960a248934e9133ebc8ab",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[iwc-test-data-conventions]]",
+      "src": "content/research/iwc-test-data-conventions/index.md",
+      "dst": "references/notes/iwc-test-data-conventions.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Assemble job input fixtures, remote URLs, hashes, collection shapes, and test-data layout in IWC style.",
+      "trigger": "When writing or revising the job/input side of a Galaxy workflow test file.",
+      "src_hash": "1921e939703444604440e0768caca6e6b834a73dcfa964f450fa081143e008d3",
+      "dst_hash": "1921e939703444604440e0768caca6e6b834a73dcfa964f450fa081143e008d3",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[planemo-asserts-idioms]]",
+      "src": "content/research/planemo-asserts-idioms/index.md",
+      "dst": "references/notes/planemo-asserts-idioms.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Choose assertion families, tolerance magnitudes, and the static/Planemo validation loop.",
+      "trigger": "When writing or revising output assertions for a Galaxy workflow test file.",
+      "src_hash": "81b8feeccd891642572e587a494d1e4d3a1b369a19d92947626230494fd92beb",
+      "dst_hash": "81b8feeccd891642572e587a494d1e4d3a1b369a19d92947626230494fd92beb",
+      "source": "deterministic"
+    },
+    {
+      "kind": "research",
+      "mode": "verbatim",
+      "ref": "[[planemo-workflow-test-architecture]]",
+      "src": "content/research/planemo-workflow-test-architecture/index.md",
+      "dst": "references/notes/planemo-workflow-test-architecture.md",
+      "used_at": "runtime",
+      "load": "on-demand",
+      "evidence": "corpus-observed",
+      "purpose": "Write tests with stable labels and artifacts that Planemo can connect back to Galaxy invocations, jobs, and outputs.",
+      "trigger": "When adding or revising workflow tests that will be iterated with Planemo or generated from existing invocations.",
+      "src_hash": "d6ac347c8361d6c312c64c1197426673e53aa1c5577e1c72f1c80a20ccd1cce3",
+      "dst_hash": "d6ac347c8361d6c312c64c1197426673e53aa1c5577e1c72f1c80a20ccd1cce3",
+      "source": "deterministic"
+    },
+    {
+      "kind": "schema",
+      "mode": "verbatim",
+      "ref": "[[galaxy-workflow-test-plan]]",
+      "src": "package://@galaxy-foundry/gxwf-foundry#galaxyWorkflowTestPlanSchema",
+      "dst": "references/schemas/galaxy-workflow-test-plan.schema.json",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "hypothesis",
+      "purpose": "Input contract: read the schema-valid Galaxy test plan (job inputs, expected outputs, assertion intent, tolerances, label assumptions, unresolved mappings, omissions) and convert it into tests-format output, reconciling assumed labels and fixtures against the real draft.",
+      "verification": "Consume a cast test plan from a *-test-to-galaxy-test-plan Mold and confirm tests-format output can be authored from it without re-reading the source summary.",
+      "license": "MIT",
+      "src_hash": "325e9cf1bb5e075fa818dc68868647de95389ca8df8581ee8cf1e2be61196e37",
+      "dst_hash": "325e9cf1bb5e075fa818dc68868647de95389ca8df8581ee8cf1e2be61196e37",
+      "source": "deterministic"
+    },
+    {
+      "kind": "schema",
+      "mode": "verbatim",
+      "ref": "[[tests-format]]",
+      "src": "package://@galaxy-foundry/gxwf-foundry#testsFormatSchema",
+      "dst": "references/schemas/tests-format.schema.json",
+      "used_at": "runtime",
+      "load": "upfront",
+      "evidence": "corpus-observed",
+      "purpose": "JSON Schema contract for the Galaxy workflow test format. Output of this Mold must validate against it.",
+      "license": "MIT",
+      "license_file": "LICENSES/galaxy-tool-util-ts.LICENSE",
+      "src_hash": "ff0de5041f4c3de0ab7abe9e7555c5a7120665b077f42661461301b0fb26f372",
+      "dst_hash": "ff0de5041f4c3de0ab7abe9e7555c5a7120665b077f42661461301b0fb26f372",
+      "source": "deterministic",
+      "license_file_hash": "383450c494c01c466bcf22df102540a39ac89da50563fd7be686ba06772f96b3"
+    }
+  ],
+  "artifacts": {
+    "produces": [
+      {
+        "id": "galaxy-workflow-test",
+        "kind": "yaml",
+        "default_filename": "galaxy-workflow.gxwf-tests.yml",
+        "description": "Galaxy workflow test file (tests-format) with job inputs, expected outputs, assertions; passes static schema + label cross-check. Named as the workflow basename + `-tests.yml` so Planemo discovers it as the companion of `galaxy-workflow.gxwf.yml`."
+      }
+    ],
+    "consumes": [
+      {
+        "id": "galaxy-test-plan",
+        "description": "Schema-valid Galaxy test plan ([[galaxy-workflow-test-plan]]) from a *-test-to-galaxy-test-plan Mold; carries job inputs, expected outputs, assertion intent, fixture provenance, label assumptions, unresolved mappings, and omissions.",
+        "inherited_schema": "[[galaxy-workflow-test-plan]]",
+        "producers": [
+          "changeset-to-galaxy-test-plan",
+          "cwl-test-to-galaxy-test-plan",
+          "freeform-summary-to-galaxy-test-plan",
+          "nextflow-test-to-galaxy-test-plan"
+        ]
+      },
+      {
+        "id": "galaxy-workflow",
+        "description": "Concrete gxformat2 workflow being tested — the loop-endstate `galaxy-workflow.gxwf.yml` from [[advance-galaxy-draft-step]] (`class: GalaxyWorkflow`); provides the real input/output labels, outputs, and collection shapes the test must assert against.",
+        "producers": [
+          "advance-galaxy-draft-step",
+          "mature-galaxy-workflow-for-iwc"
+        ]
+      },
+      {
+        "id": "test-data-refs",
+        "description": "Resolved test data references (URLs, paths, expected shapes) from paper-to-test-data or find-test-data.",
+        "producers": [
+          "cwl-to-test-data",
+          "find-test-data",
+          "nextflow-to-test-data",
+          "paper-to-test-data"
+        ]
+      }
+    ]
+  }
+}

package/extensions/orbit/vendor/skills/implement-galaxy-workflow-test/_required_tools.json

@@ -0,0 +1,28 @@
+[
+  {
+    "tool": "gxwf",
+    "origin": "npm",
+    "package": "@galaxy-tool-util/cli",
+    "package_version": "^1.8.1",
+    "invoke": "gxwf",
+    "invoke_fallback": "npx --yes --package @galaxy-tool-util/cli@1.8.1 gxwf",
+    "availability_check": "gxwf --help | grep -q draft-validate",
+    "docs_url": "https://github.com/jmchilton/galaxy-tool-util-ts/tree/main/packages/cli",
+    "source": "implied",
+    "implied_by": [
+      "gxwf validate-tests"
+    ]
+  },
+  {
+    "tool": "planemo",
+    "origin": "pypi",
+    "package": "planemo",
+    "package_version": "0.75.47",
+    "invoke": "planemo",
+    "invoke_fallback": "uvx --from planemo==0.75.47 planemo",
+    "availability_check": "planemo --version",
+    "docs_url": "https://planemo.readthedocs.io/",
+    "reference": "references/cli/planemo.md",
+    "source": "referenced"
+  }
+]

package/extensions/orbit/vendor/skills/implement-galaxy-workflow-test/_verify.json

@@ -0,0 +1,17 @@
+{
+  "verify_schema_version": 1,
+  "entries": [
+    {
+      "artifact_id": "galaxy-test-plan",
+      "direction": "input",
+      "kind": "yaml",
+      "default_filename": "galaxy-test-plan.yml",
+      "schema": "[[galaxy-workflow-test-plan]]",
+      "validator_bin": "foundry",
+      "args": [
+        "validate-galaxy-workflow-test-plan",
+        "{artifact_path}"
+      ]
+    }
+  ]
+}

package/extensions/orbit/vendor/skills/implement-galaxy-workflow-test/references/cli/planemo.md

@@ -0,0 +1,44 @@
+---
+type: cli-tool
+tool: planemo
+origin: pypi
+package: planemo
+package_version: "0.75.47"
+invoke: planemo
+invoke_fallback: "uvx --from planemo==0.75.47 planemo"
+availability_check: "planemo --version"
+docs_url: "https://planemo.readthedocs.io/"
+tags:
+  - cli/planemo
+status: draft
+created: 2026-05-10
+revised: 2026-09-13
+revision: 6
+summary: "Galaxy tool/workflow runtime testing CLI; used by run-workflow-test and friends."
+---
+
+# planemo
+
+Galaxy's runtime testing and authoring CLI. Foundry Molds invoke `planemo test`, `planemo lint`, and friends for end-to-end workflow validation; the cast skill consumes structured JSON output from `--test_output_json` and validates it against planemo-test-report.
+
+## Pin
+
+`package_version` pins to the released `planemo==0.75.47` from PyPI — base upstream planemo, no fork. It is the single source of truth: the sync scripts carry no pin of their own and stamp whichever planemo they invoked, and `make check-planemo-pin` fails if any recorded copy of the version disagrees with this field.
+
+[galaxyproject/planemo#1636](https://github.com/galaxyproject/planemo/pull/1636) merged 2026-05-14 and first shipped in released **0.75.42**, so `planemo cli_metadata` and `planemo output_schema` are available in every release at or above this pin. Every Foundry consumer runs off this base pin: the workflow-test phases (run-workflow-test, implement-galaxy-workflow-test) which need only `planemo test --test_output_json`, the convergence loop in convert-nfcore-module-to-galaxy-tool, and the vendored-artifact regeneration story (`packages/planemo-cli-meta/`, `packages/planemo-test-report-schema/`). No fork pin is required.
+
+The floor is now 0.75.46 for a packaging reason, not a feature one. `galaxy-tool-util` declares its `galaxy-tool-util-models` dependency unconstrained, so a fresh resolve of an older planemo pairs a 25.1.x `galaxy-tool-util` with a 26.x `galaxy-tool-util-models` and dies at import (`cannot import name 'ToolOutputCollectionStructure'`). [galaxyproject/planemo#1674](https://github.com/galaxyproject/planemo/pull/1674) constrains the transitive dependency and first shipped in 0.75.46. Any pin below that needs `galaxy-tool-util-models<26` installed alongside it.
+
+## Install
+
+```sh
+uvx --from planemo==0.75.47 planemo --version
+```
+
+For a persistent install:
+
+```sh
+uv tool install planemo==0.75.47
+```
+
+Contributor laptops only need planemo when **regenerating** vendored artifacts (the schema JSON in `packages/planemo-test-report-schema/`, the planemo CLI manual pages under `content/cli/planemo/`). Normal Foundry development — `npm run validate`, `npm run test`, `npm run packages-test` — builds against the vendored JSON and does not invoke planemo.

package/extensions/orbit/vendor/skills/implement-galaxy-workflow-test/references/cli/validate-tests.json

@@ -0,0 +1,40 @@
+{
+  "type": "cli-command",
+  "tool": "gxwf",
+  "command": "validate-tests",
+  "summary": "Validate Galaxy workflow test files and optionally cross-check labels against their workflow.",
+  "source_path": "content/cli/gxwf/validate-tests.md",
+  "source_revision": 3,
+  "package": "@galaxy-tool-util/cli",
+  "description": "Validate a workflow-test file (*-tests.yml, *.gxwf-tests.yml) against the Galaxy Tests schema",
+  "synopsis": "gxwf validate-tests [options] <file>",
+  "args": [
+    {
+      "raw": "file",
+      "name": "file",
+      "required": true,
+      "variadic": false,
+      "description": "Tests file (*-tests.yml)"
+    }
+  ],
+  "options": [
+    {
+      "flags": "--json",
+      "name": "json",
+      "description": "Output structured JSON report",
+      "takesArgument": false,
+      "optionalArgument": false,
+      "negatable": false
+    },
+    {
+      "flags": "--workflow <path>",
+      "name": "workflow",
+      "description": "Cross-check job inputs + output assertions against a workflow (.ga / .gxwf.yml)",
+      "takesArgument": true,
+      "argumentPlaceholder": "<path>",
+      "optionalArgument": false,
+      "negatable": false
+    }
+  ],
+  "body": "# `gxwf validate-tests`\n\nValidate a Galaxy workflow test file (`*-tests.yml` or `*.gxwf-tests.yml`) against the Galaxy tests schema. Optionally cross-check the test file against a workflow so missing input labels, missing output labels, and type mismatches fail before a slow Planemo run.\n\n`<file>` is a workflow test YAML file, usually named `<workflow>-tests.yml` or `<workflow>.gxwf-tests.yml`.\n\n## Output\n\nDefault output is human-readable validation diagnostics.\n\nWith `--json`, the command emits a structured report describing schema errors and, when `--workflow` is supplied, workflow-coherence errors such as missing labels or incompatible input values.\n\n## Examples\n\n```bash\ngxwf validate-tests workflow-tests.yml\ngxwf validate-tests workflow-tests.yml --json\ngxwf validate-tests workflow-tests.yml --workflow workflow.gxwf.yml --json\n```\n\n## Gotchas\n\n- This is the cheap static gate before Planemo. It does not execute the workflow and does not prove assertions pass on real outputs.\n- Use `--workflow` whenever the workflow file is available. Schema-valid tests can still reference stale input/output labels after workflow edits.\n- Run this before `planemo workflow_test_on_invocation` or full `planemo test`; it catches authoring mistakes without starting Galaxy.\n- The assertion vocabulary itself comes from tests-format; strategy for choosing assertions lives in planemo-asserts-idioms."
+}

package/extensions/orbit/vendor/skills/implement-galaxy-workflow-test/references/notes/galaxy-workflow-testability-design.md

@@ -0,0 +1,136 @@
+---
+type: research
+tags:
+  - target/galaxy
+status: draft
+created: 2026-05-03
+revised: 2026-05-06
+revision: 2
+related_notes:
+  - "iwc-workflow-testability-survey"
+  - "iwc-test-data-conventions"
+  - "planemo-asserts-idioms"
+  - "iwc-shortcuts-anti-patterns"
+  - "planemo-workflow-test-architecture"
+  - "implement-galaxy-workflow-test"
+  - "gxformat2-schema"
+  - "gxformat2-workflow-inputs"
+  - "galaxy-datatypes-conf"
+summary: "Design guidance for Galaxy workflow inputs, outputs, and checkpoints that make IWC-style workflow tests possible."
+---
+
+# Galaxy workflow testability design
+
+Use this note when authoring or translating a Galaxy workflow **before** the `-tests.yml` file exists. It covers workflow structure choices that make later IWC-style tests meaningful: labels, promoted checkpoints, collection identifiers, and fixture-compatible inputs.
+
+This is not a `content/patterns/` page. It is cross-cutting design guidance for Molds that need testable Galaxy workflows. Assertion syntax lives in planemo-asserts-idioms. Test YAML fixture shapes live in iwc-test-data-conventions. Accepted shortcut vs smell calls live in iwc-shortcuts-anti-patterns. Corpus evidence trail lives in iwc-workflow-testability-survey.
+
+## 1. Treat labels as API
+
+Workflow input and output labels are not cosmetic. Planemo and IWC tests address workflow inputs and outputs by label, and the survey found exact label matches for every asserted output across 114 matched workflow/test pairs. A generated workflow should therefore pick stable, descriptive labels before test authoring starts.
+
+Rules:
+
+- Label every output that may need a test assertion.
+- Treat input/output renames as breaking changes requiring sibling `-tests.yml` updates.
+- Prefer stable domain names over tool-step defaults or positional names.
+- Do not rely on unlabeled or positional outputs for tests.
+
+Evidence:
+
+- Scanpy exposes outputs such as `Initial Anndata General Info`, `UMAP of louvain`, `Ranked genes with Wilcoxon test`, and `Dotplot of top genes on clusters` (`$IWC_FORMAT2/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy.gxwf.yml:105-147`). The sibling test keys assertions by those exact labels (`$IWC/workflows/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy-tests.yml:27-205`).
+- VGP scaffolding uses punctuation-heavy labels such as `Hi-C duplication stats on scaffolds: Raw`, `Hi-C duplication stats on scaffolds: MultiQc`, and `Merged Alignment stats` (`$IWC_FORMAT2/VGP-assembly-v2/Scaffolding-HiC-VGP8/Scaffolding-HiC-VGP8.gxwf.yml:170-196`). The test asserts those exact labels (`$IWC/workflows/VGP-assembly-v2/Scaffolding-HiC-VGP8/Scaffolding-HiC-VGP8-tests.yml:218-245`).
+
+## 2. Promote assertable checkpoints
+
+IWC workflow tests assert workflow-level outputs. Intermediate step results are invisible unless promoted to top-level workflow outputs. When final reports are weakly assertable, expose intermediate checkpoints that carry deterministic content or structure.
+
+Rules:
+
+- Promote intermediate outputs when they are the best deterministic or structural checkpoint.
+- Prefer a checkpoint table/text/HDF5 object that can prove content over a final plot/report that can only prove existence.
+- Accept some output-list clutter when it buys meaningful tests.
+- Do not promote every intermediate by default; expose checkpoints that map to concrete assertion intent.
+
+Evidence:
+
+- Scanpy exposes 21 workflow outputs and the sibling test asserts all 21. These include initial AnnData summaries, intermediate plots, ranked-gene tables, final AnnData, cluster-count tables, and final plots (`$IWC_FORMAT2/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy.gxwf.yml:105-147`; `$IWC/workflows/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy-tests.yml:27-205`).
+- RNA-seq paired-end exposes mapped reads, stranded/unstranded coverage, abundance estimates, expression tables, counts tables, and MultiQC reports (`$IWC_FORMAT2/transcriptomics/rnaseq-pe/rnaseq-pe.gxwf.yml:90-112`). The sibling test asserts sizes for coverage/read outputs and stronger regex/line checks for expression/count outputs (`$IWC/workflows/transcriptomics/rnaseq-pe/rnaseq-pe-tests.yml:48-97`).
+- MGnify complete exposes 83 workflow outputs; 38 are asserted in the sibling test, including MultiQC reports, FASTA collections, taxonomic classifications, OTU tables, and HDF5/JSON outputs (`$IWC_FORMAT2/amplicon/amplicon-mgnify/mgnify-amplicon-pipeline-v5-complete/mgnify-amplicon-pipeline-v5-complete.gxwf.yml:163-329`; `$IWC/workflows/amplicon/amplicon-mgnify/mgnify-amplicon-pipeline-v5-complete/mgnify-amplicon-pipeline-v5-complete-tests.yml:15-120`).
+
+## 3. Stabilize collection output identifiers
+
+Collection tests key assertions by element identifier. If a workflow emits collections with unstable or opaque identifiers, the test cannot target elements cleanly.
+
+Rules:
+
+- Preserve biologically or sample-meaningful identifiers through map-over and collection reshaping.
+- When generating or relabeling collections, make the identifier derivation deterministic and visible in workflow structure.
+- For nested collections, ensure each axis has predictable identifiers.
+- Quote special identifiers in tests when YAML requires it, but do not simplify identifiers merely for YAML convenience.
+
+Evidence:
+
+- 59 of 115 IWC test files use `element_tests:`, with 227 `element_tests:` blocks in the corpus survey.
+- 10x CellPlex tests nested collection outputs by `subsample`, then inner `matrix`, `barcodes`, and `genes` elements (`$IWC/workflows/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex-tests.yml:82-128`). The workflow exposes the corresponding collection outputs (`$IWC_FORMAT2/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex.gxwf.yml:73-91`).
+- HyPhy collection outputs are tested by generated gene identifiers such as `NC_001477.1|capsid_protein_C|95-394_DENV1` (`$IWC/workflows/comparative_genomics/hyphy/hyphy-core-tests.yml:31-71`). The workflow exposes collection outputs for MEME, PRIME, BUSTED, and FEL (`$IWC_FORMAT2/comparative_genomics/hyphy/hyphy-core.gxwf.yml:26-38`).
+
+## 4. Choose checkpoints by assertion strength
+
+Assertion choice is not only a test-file decision. It should feed back into workflow output design. If the only exposed output is a stochastic plot or binary file, the best possible test may be a weak size check. Exposing a sibling table, report, HDF5 structure, or summary line can make the same workflow much more testable.
+
+Rules:
+
+- For image-heavy workflows, expose data or summary outputs behind the plot when possible.
+- For stochastic statistical outputs, expose structural checkpoints and stable summary tokens.
+- For binary outputs, expose a text/table report or stats file when the tool can produce one.
+- Use planemo-asserts-idioms to select the assertion family after choosing the checkpoint.
+
+Evidence:
+
+- Scanpy image outputs are mostly smoke-tested with `has_size`, `has_image_width`, and `has_image_height`, but the same workflow also exposes AnnData HDF5 keys and cluster-count table checks (`$IWC/workflows/scRNAseq/scanpy-clustering/Preprocessing-and-Clustering-of-single-cell-RNA-seq-data-with-Scanpy-tests.yml:33-205`).
+- RNA-seq paired-end pairs coarse size checks for coverage/mapped-read outputs with stronger regex and exact-line checks for expression/count tables (`$IWC/workflows/transcriptomics/rnaseq-pe/rnaseq-pe-tests.yml:48-97`).
+- VGP scaffolding tests combine stable text checks for scaffold/report stats with size checks for map/alignment artifacts (`$IWC/workflows/VGP-assembly-v2/Scaffolding-HiC-VGP8/Scaffolding-HiC-VGP8-tests.yml:173-245`).
+
+## 5. Design inputs with fixtures in mind
+
+Workflow input labels and types constrain the eventual `job:` block. Fixture planning is not only a test-file activity: it should influence whether the workflow exposes a file input, a collection input, a string data-table input, or a typed parameter.
+
+Rules:
+
+- Choose input labels that will be readable as test `job:` keys.
+- Match workflow input collection types to realistic fixture shapes.
+- Decide early whether reference data should be a portable remote file or a CVMFS/data-table string.
+- Keep typed parameters explicit when tests need to set them (`int`, `boolean`, `string`) rather than burying them in step defaults.
+
+Evidence:
+
+- 10x CellPlex job inputs include `fastq PE collection GEX`, `reference genome`, `gtf`, `cellranger_barcodes_3M-february-2018.txt`, `fastq PE collection CMO`, `sample name and CMO sequence collection`, and `Number of expected cells` (`$IWC/workflows/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex-tests.yml:2-75`). The workflow declares matching collection, data, string, boolean, and int inputs (`$IWC_FORMAT2/scRNAseq/fastq-to-matrix-10x/scrna-seq-fastq-to-matrix-10x-cellplex.gxwf.yml:4-72`).
+- HyPhy accepts a `list` collection of unaligned sequences and preserves accession-like fixture identifiers through to output element assertions (`$IWC/workflows/comparative_genomics/hyphy/hyphy-core-tests.yml:7-30`; `$IWC_FORMAT2/comparative_genomics/hyphy/hyphy-core.gxwf.yml:14-25`).
+
+## 6. Know what a gxformat2 output entry contains
+
+Top-level gxformat2 `outputs:` is the public workflow-output surface. It is separate from per-step `out:` declarations and from step post-job actions such as `change_datatype` or `rename`.
+
+Authoring rules:
+
+- Use `label` as the stable public name tests and users will address.
+- Use `outputSource` to point at the producing step output; do not rely on positional output order.
+- Use `doc` for short user-facing context when the label is not self-explanatory.
+- Keep `type` aligned with the exposed value (`data`, `collection`, or scalar vocabulary from gxformat2-workflow-inputs) when the schema needs it.
+- Apply `change_datatype` at the producing step output when Galaxy needs a stronger datatype than the tool reports; choose values from galaxy-datatypes-conf.
+- Use `rename` only for generated dataset names inside Galaxy histories. It is not a substitute for stable workflow-output `label`.
+- Treat `add_tags` and `remove_tags` as metadata helpers, not as the test API. IWC tests key by labels and collection element identifiers, not tags.
+- Avoid `hide` or `delete_intermediate_datasets` on outputs that are promoted as test checkpoints.
+
+Design inference: a workflow-output promotion decision should pick both the public `outputs:` entry and any producer-side post-job action needed to make that output useful. For example, a synthesized BED checkpoint needs a stable output `label` plus a producer-side `change_datatype: bed`; one without the other is incomplete for a testable workflow.
+
+## Cross-references
+
+- iwc-workflow-testability-survey — corpus survey and distribution rationale.
+- iwc-test-data-conventions — job/input YAML shapes, remote fixtures, hashes, collection fixture syntax.
+- planemo-asserts-idioms — assertion-family choice after an output is exposed.
+- iwc-shortcuts-anti-patterns — accepted shortcut vs smell calls for weak assertions and label coupling.
+- planemo-workflow-test-architecture — Planemo execution, output-problem ambiguity, and structured artifacts.
+- gxformat2-schema — structural vocabulary for top-level workflow outputs and step post-job actions.
+- galaxy-datatypes-conf — valid Galaxy datatype extensions for `format` and `change_datatype` choices.