Skip to content

docs(test): document local harness and act usage - #86

Merged
chrissweet merged 1 commit into
mainfrom
docs/local-testing-and-act
Jul 16, 2026
Merged

docs(test): document local harness and act usage#86
chrissweet merged 1 commit into
mainfrom
docs/local-testing-and-act

Conversation

@Omegaice

Copy link
Copy Markdown
Member

Documents how to run the test harness and the CI workflow locally without the spurious failures a template-development checkout produces, and adds the guidance as a dev-only Claude rule.

What

  • scripts/test/README.md: a Python-dependencies subsection (the kg-frontmatter-graph test asserts yaml/rdflib/pyshacl rather than skipping), a warning against pointing MVP_TEMPLATE_LOCAL at a working tree containing gitignored artifacts, and a "Running the CI workflow locally with act" section.
  • .claude/rules/local-testing.md: the same guidance in agent-facing form for template contributors.
  • scripts/instantiate.sh: the new rule joins observe-the-failure.md in DEV_ONLY_RULES so it never ships to derived projects.
  • instantiate-strips-dev-rules smoke test: precondition + strip assertions for the new rule.

Why

Three local failure modes motivated this, all invisible in CI's clean checkouts:

  1. MVP_TEMPLATE_LOCAL at a dev checkout copies the dogfooded wiki/<template>.wiki/ into the sandbox via cp -R, and init-wiki.sh fails with "multiple wikis ... name is ambiguous".
  2. The kg test's Python deps are asserted, so a bare local run fails 6 assertions.
  3. act --bind writes root-owned scripts/kg/build/ and scripts/kg/.cache/ into the host checkout (the kg pipeline writes into the repo, not the test sandbox) and leaks the same gitignored artifacts into the workflow's MVP_TEMPLATE_LOCAL=$GITHUB_WORKSPACE. act's default copy mode avoids both, since --use-gitignore makes the container see the equivalent of a clean checkout.

Verification

  • The new strip assertion was observed red before the DEV_ONLY_RULES change (rule shipped and survived instantiation) and green after; a precondition assertion guards against a vacuous pass.
  • Full harness on this tree: 991 pass, 0 fail (989 + the 2 new assertions).
  • act -j test --matrix os:ubuntu-latest --rm runs the workflow's ubuntu leg green with no writes to the host tree.

Local runs failed spuriously three ways: MVP_TEMPLATE_LOCAL at a dirty working tree copies gitignored artifacts into the sandbox, the kg test asserts its Python deps rather than skipping, and act --bind both writes root-owned files into the checkout and leaks the same artifacts into the workflow run.
The new .claude/rules/local-testing.md is template-development-only, so instantiate.sh strips it at instantiation like observe-the-failure.md.
@chrissweet
chrissweet merged commit 1f21a38 into main Jul 16, 2026
14 checks passed
@Omegaice
Omegaice deleted the docs/local-testing-and-act branch July 17, 2026 20:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants