What Kind of Testing Does Arc-Kit Encourage? A Guide to Architecture Verification

Arc-Kit promotes a continuous verification mindset that links every architecture artefact to concrete test evidence through automated CI pipelines, security compliance checks, accessibility validation, and specialized health commands.

The tractorjuice/arc-kit repository establishes a comprehensive testing framework designed to keep architecture artefacts, code, and governance evidence synchronized. Understanding what kind of testing Arc-Kit encourages helps teams implement a continuous verification strategy that treats documentation as testable code.

The Continuous Verification Philosophy

Arc-Kit is built around the principle that architecture governance requires artefact-to-test traceability. Rather than treating testing as an afterthought, the toolkit embeds verification into every stage of the architecture lifecycle, from initial requirements through deployment.

Core Testing Categories in Arc-Kit

Artefact-to-Test Traceability

The foundation of Arc-Kit's testing strategy is the traceability matrix. According to docs/guides/traceability.md, every requirement, design element, and operational document must link to concrete test artefacts.

Use the /arckit.traceability command to generate a matrix that lists Tests alongside each requirement:

/arckit.traceability Generate traceability matrix for my-project

The resulting ARC-xxx-TRAC-v1.0.md contains a "Tests" column; any empty cell triggers the "Missing tests?" checklist item.

Automated CI Testing

Arc-Kit mandates that CI pipelines run comprehensive test suites on every change. The docs/guides/devops.md file defines a CI Pipeline section requiring a "testing strategy" that includes unit, integration, security, and accessibility checks.

A typical GitHub Actions configuration follows this structure:

# .github/workflows/ci.yml

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with: { python-version: "3.12" }
      - name: Install ArcKit CLI (dev mode)
        run: pip install -e .
      - name: Run ArcKit health checks
        run: arckit health
      - name: Run Wardley map validation
        run: |
          cd tests/mermaid-wardley
          npm ci
          node validate.mjs

Security and Compliance Testing

Security verification is non-negotiable in Arc-Kit. The docs/guides/artifact-health.md demonstrates how new penetration test reports trigger re-runs of /arckit:secure and /arckit:dpia commands.

This ensures that security-by-design evidence and data-privacy impact assessments remain current with every architecture change.

Accessibility and Bias Testing

For public-sector and AI services, Arc-Kit requires WCAG compliance testing and AI bias metric validation. The docs/guides/service-assessment.md and docs/guides/uk-government/ai-playbook.md each list "accessibility testing evidence" and "bias testing documented with metrics" as mandatory checklist items.

Plugin Branch Testing

Contributors to Arc-Kit itself must follow the Testing Plugin Branches workflow defined in docs/guides/testing-plugin-branches.md. This involves spinning up a local test project and enabling the plugin from a feature branch via .claude/settings.json:

// .claude/settings.json (in a test repo)
{
  "enabledPlugins": { "arckit@arc-kit": true },
  "extraKnownMarketplaces": {
    "arc-kit": {
      "source": {
        "source": "github",
        "repo": "tractorjuice/arc-kit",
        "ref": "feat/my-new-command"
      }
    }
  }
}

After starting Claude Code, verify the loaded version with:

/arckit.health

Generated Artefact Validation

Arc-Kit treats generated documentation as testable code. The repository ships a stand-alone mermaid-wardley test suite that validates the syntax of generated Wardley maps. According to docs/superpowers/specs/2026-03-28-mermaid-wardley-testing-design.md, this suite lives in tests/mermaid-wardley/validate.mjs and ensures map artefacts remain syntactically valid across versions.

Health-Check Testing

Regular health commands surface version drift, stale artefacts, and missing tests. The docs/guides/health.md describes how /arckit.health checks for "Version-drift" and "Missing tests?" in its output, providing continuous verification of the architecture's current state.

Summary

Arc-Kit encourages a multi-layered testing approach that integrates verification into every aspect of architecture governance:

• Traceability linking every requirement to test evidence via the /arckit.traceability command
• Automated CI pipelines running unit, integration, security, and accessibility checks
• Security and compliance validation through /arckit:secure and /arckit:dpia commands
• Accessibility and bias testing for WCAG compliance and AI metrics
• Plugin branch testing for contributors validating feature branches
• Generated artefact validation using the mermaid-wardley test suite
• Continuous health monitoring via /arckit.health to detect drift and gaps

Frequently Asked Questions

Does Arc-Kit require specific testing frameworks?

No, Arc-Kit is framework-agnostic regarding your unit and integration tests. While it mandates that tests exist and link to artefacts via the traceability matrix, you can use pytest, Jest, JUnit, or any other testing framework. The docs/guides/devops.md only specifies that a "testing strategy" must exist in your CI pipeline, not the specific tools.

How does Arc-Kit handle testing for generated documentation?

Arc-Kit treats generated documentation as code requiring validation. The repository includes a stand-alone mermaid-wardley test suite located in tests/mermaid-wardley/validate.mjs that validates Wardley map syntax. According to docs/superpowers/specs/2026-03-28-mermaid-wardley-testing-design.md, this ensures that generated architecture artefacts remain syntactically valid and render correctly.

Can I test Arc-Kit plugin changes before submitting a pull request?

Yes, Arc-Kit provides a specific workflow for testing plugin branches outlined in docs/guides/testing-plugin-branches.md. Contributors create a local test project with a .claude/settings.json file pointing to their feature branch via the extraKnownMarketplaces configuration. After starting Claude Code, running /arckit.health confirms the correct version is loaded, allowing validation of new commands or fixes before merging.

What happens if the traceability matrix shows missing tests?

When the /arckit.traceability command generates a matrix with empty cells in the "Tests" column, Arc-Kit flags these via the "Missing tests?" checklist entry documented in docs/guides/traceability.md. This triggers the health-check system described in docs/guides/health.md, which surfaces version drift and coverage gaps. Teams should treat these warnings as blockers, ensuring every requirement links to concrete test evidence before considering the architecture verification complete.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}