specweave

SpecWeave translates between canonical Gherkin behavior specs, plain pytest enforcement, and normalized execution evidence.

It is not a task ledger, architecture ledger, or CI system.

Canonical layout

specweave.toml
specs/behavior/README.md
specs/behavior/manifest.json
specs/behavior/features/<area>/<feature>.feature
specs/behavior/evidence/*.json
specs/behavior/mappings/taskledger/*.json
tests/test_<area>_<feature>.py
specs/behavior/reports/*.xml
specs/behavior/reports/specweave/*.json

Hidden .specweave.toml is still discovered for existing projects, but specweave.toml is the default config file and classic .feature is the only canonical feature format.

Behavior workflow

specweave init
specweave doctor
specweave create gherkin --from-tests tests --out specs/behavior/features
specweave review specs
specweave review coverage --view both --show gaps
specweave behavior index
specweave behavior generate-tests --features specs/behavior/features --tests-dir tests
pytest --junitxml=specs/behavior/reports/pytest-junit.xml
specweave behavior import-report specs/behavior/reports/pytest-junit.xml --format junit-xml

Classic Gherkin only

Canonical specs use classic Gherkin:

@area-auth @feature-password-login
Feature: Password login
  Users authenticate with a password.

  @rule-invalid-password
  Rule: Invalid passwords are rejected

    @bdd-password-login-invalid-password @ac-0001
    Example: Reject invalid password
      Given a registered user exists
      When the user submits an invalid password
      Then login is rejected
      And no authenticated session is created

Legacy .feature.md files are no longer supported as canonical specs.

Evidence and mappings

• normalized evidence: specs/behavior/evidence
• Taskledger mapping artifacts: specs/behavior/mappings/taskledger
• generated runner output: specs/behavior/reports
• SpecWeave runner summaries: specs/behavior/reports/specweave

Import pytest/JUnit evidence with:

specweave behavior import-report \
  specs/behavior/reports/pytest-junit.xml \
  --format junit-xml \
  --out specs/behavior/evidence/pytest-evidence.json

Optional Taskledger integration

Taskledger exchange is file-based:

specweave behavior import-taskledger \
  specs/behavior/mappings/taskledger/task-0123.json \
  --out specs/behavior/features/task-management/plan-gates.feature

specweave create taskledger-task \
  --feature specs/behavior/features/task-management/plan-gates.feature \
  --out specs/behavior/mappings/taskledger/draft.json

Trace and cross-ledger diagnostics remain read-only:

specweave trace @bdd-login-success --format json
specweave combi check --json specs/behavior/reports/specweave/combi-check.json

Installation

pip install specweave
pip install specweave[gherkin]   # optional official Cucumber parser
pip install -e ".[dev]"          # development tools

Development

pytest -q
ruff check .
ruff format --check .
mypy specweave

License

Apache 2.0