Document mutation-testing workflow contract tests - #362
Open
leynos wants to merge 1 commit into
Open
Conversation
Add a "Workflow contract tests" subsection under the existing "Mutation-Testing Reusable Workflows" section of the developer's guide. It documents the two drift guards specific to this host repository: the caller contract test (test_mutation_testing_caller.py), analogous to a downstream consumer's, and the workflow-shape test (test_mutation_workflow_shape.py), which pins the self-checkout relocation invariant in the reusable workflow definitions themselves. It records the local run command and cross-links the helper-script unit tests and the act integration tests.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Summary
WalkthroughThe developer guide adds a “Workflow contract tests” subsection documenting caller and reusable-workflow structural checks, local commands, dependencies, and separate execution-path coverage. ChangesWorkflow contract documentation
Possibly related PRs
Suggested labels: Poem
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 inconclusive)
✅ Passed checks (19 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/developers-guide.md`:
- Around line 442-443: Update the sentence in the developers guide by removing
the comma immediately before “because” after the `module-prefix-strip: ""`
clause, leaving the surrounding wording unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 87a4a422-6e96-495a-b3c1-a4c0e6ed55d8
📒 Files selected for processing (1)
docs/developers-guide.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
leynos/polythene(auto-detected) → reviewed against open PR#35docs/mutation-contract-testsinstead of the default branch
Comment on lines
+442
to
+443
| `module-prefix-strip: ""`, because the repository's own Python source | ||
| is mutated as a flat-layout package. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the comma before “because”.
The clause is essential to the sentence, so remove the comma to follow the repository’s grammar standard.
Triage: [type:grammar]
- module-prefix-strip: ""`, because the repository's own Python source
+ module-prefix-strip: ""` because the repository's own Python source🧰 Tools
🪛 LanguageTool
[formatting] ~442-~442: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...ripts/"and module-prefix-strip: ""`, because the repository's own Python source is...
(COMMA_BEFORE_BECAUSE)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/developers-guide.md` around lines 442 - 443, Update the sentence in the
developers guide by removing the comma immediately before “because” after the
`module-prefix-strip: ""` clause, leaving the surrounding wording unchanged.
Sources: Path instructions, Linters/SAST tools
This was referenced Jul 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
### Workflow contract testssubsection under the existing## Mutation-Testing Reusable Workflowssection ofdocs/developers-guide.md. This host repository both defines thereusable mutation workflows and, via
workflow_scripts/, consumesmutation-mutmut.yml, so its contract tests differ from a downstreamconsumer's. The new subsection documents both drift guards:
workflow_scripts/tests/test_mutation_testing_caller.py— the callercontract test (analogous to a consumer repo's): shape-only
USES_RESHA pin, least-privilege permissions, empty default token scope,
per-ref non-cancelling
concurrency, schedule + plainworkflow_dispatchtriggers, and the exactwith:block(
paths: "workflow_scripts/",module-prefix-strip: ""). Self-skipswhen
.github/is absent (mutmut'smutants/sandbox).workflow_scripts/tests/test_mutation_workflow_shape.py— with noconsumer analogue: pins the self-checkout relocation invariant in the
reusable workflow definitions themselves (issue workflow-src checkout pollutes the caller's tree during mutation runs #343 regression
guard).
It records the local run command and cross-links the helper-script unit
tests and the
actintegration tests (Workflow Test Harness).Framing / permutation
Host-repo special case (per brief's
shared-actionsnote). Notpermutations A–E. Combined single subsection, framing confirmed by the
orchestrator before opening this PR. The repository already had a
developer's guide and a mutation section, so this is a
###subsectionrather than a new
##section, and no new-guide work was needed.Local run command documented
uv run --with pyyaml --with pytest \ pytest workflow_scripts/tests/test_mutation_testing_caller.py \ workflow_scripts/tests/test_mutation_workflow_shape.py -vVerified: 10 passed against up-to-date
origin/main.Cross-link
No TOC/index exists near the top of the guide, so no TOC entry was
added. Added an in-section cross-link to the "Workflow Test Harness"
heading using the GitHub slug
#workflow-test-harness-testsworkflowsconftestpy.Roadmap / execplan tracking
No roadmap/execplan tracking applies to this docs task. (The mutation
work's execplan,
docs/execplans/add-mutation-testing-workflows.md,covers the workflows themselves, not this developer-guide documentation.)
Docs lint
markdownlint-cli2on the file: 0 errors.typos(repotypos.toml): passes after correctingserialises→serializesper en-GB Oxford (-ize) spelling.Docs-only change; the Rust/Python test suites were not run.