testdoc-specer 0.1.0

Write structured test specs, run them manually in a local UI, export to PDF or Markdown, hand to AI for test generation

testdoc

Write structured test specs in plain English. Open them in a local UI to edit, preview, and run through manually. Export to PDF or Markdown. Hand the same file to an AI to generate test code.

---

What it does

• Write — structured .spec.md files with a consistent format (context, scenarios, notes)
• Edit & preview — local browser UI with a live split-pane editor
• Run — tick through scenarios, mark pass/fail/blocked, add notes
• Export — PDF for sharing and archiving, Markdown for committing test run records
• Generate tests — hand a .spec.md to Claude or any AI with a prompt to get test code

---

Install

Requirements: Python 3.10+, and on macOS: brew install pango (needed by the PDF renderer)

# from PyPI
pip install testdoc-specer

# or with pipx (recommended — keeps it isolated)
pipx install testdoc-specer

macOS only — install Pango before first use:

brew install pango

---

Quick start

# Open the UI in your specs folder
testdoc serve ./specs/

# Or open a single file
testdoc serve ./specs/login.spec.md

This opens http://localhost:8080 in your browser. From there you can create, edit, run, and export.

---

The .spec.md format

Every spec file follows this structure:

# Feature: Login
> One line description of what this feature does and why.

## Context
Explain why this feature exists. Add images or diagrams here.

## Scenarios

\`\`\`gherkin
# @priority: must
# @mocks:
#   - user database
#   - Redis rate limiter
# @edge-cases:
#   - wrong password → same error as unknown user (prevent enumeration)
# @notes:
#   - JWT expires in 1 hour
Scenario: Valid credentials return a JWT
  Given a user exists with email "[e-mail]"
  When login is called with that email and password
  Then a JWT token is returned
  And the HTTP status is 200
\`\`\`

\`\`\`gherkin
Scenario: Wrong password returns error
  Given a user exists with email "[e-mail]"
  When login is called with the wrong password
  Then the HTTP status is 401
  And the response contains error "invalid credentials"
\`\`\`

## Notes
Any decisions, gotchas, or links that don't fit above.

Sections (always in this order):

Section	Required	Content
# Feature:	Yes	Name + one-line > description
## Context	No	Free Markdown — prose, images, diagrams
## Scenarios	Yes	One or more fenced gherkin blocks
## Notes	No	Free Markdown

Custom annotation blocks (inside Gherkin blocks, as comments):

Block	Purpose
# @priority: must/should/could	MoSCoW priority
# @mocks:	Dependencies to stub
# @edge-cases:	Edge cases to cover
# @notes:	Non-obvious behavior

---

UI walkthrough

Writing a spec

1. Run testdoc serve <folder>
2. Click + in the sidebar — enter a name, hit Create
3. The editor opens with the full structure pre-filled
4. Edit the left pane, the right pane updates as you type
5. Changes save automatically on every keystroke

Running a test

1. Open a spec, click Run in the toolbar
2. Fill in Date, Tester, Build
3. Tick steps as you work through them
4. Set each scenario to Pass / Fail / Blocked / Skip
5. Add notes on what happened
6. Results auto-save — come back any time

Exporting

• Export MD — downloads a filled .run.md Markdown file, good for committing to git
• Export PDF — downloads a PDF with results and notes embedded

---

CLI commands

The UI covers most workflows, but all commands are also available headlessly:

# Open the UI (primary workflow)
testdoc serve ./specs/
testdoc serve ./specs/login.spec.md   # single file

# Render to PDF + Markdown without the UI
testdoc render ./specs/login.spec.md
testdoc render ./specs/               # all files in folder
testdoc render ./specs/ --pdf         # PDF only
testdoc render ./specs/ --md          # Markdown run doc only

# Generate a Markdown test run doc only
testdoc run ./specs/login.spec.md

# Re-render on every save
testdoc watch ./specs/

# Lint for common issues
testdoc check ./specs/login.spec.md

# List all specs in a folder
testdoc list ./specs/

# Scaffold a new spec file
testdoc new user-signup
testdoc new user-signup --dir ./specs/

testdoc --version

---

Using specs with AI for test generation

Hand a .spec.md file directly to Claude or any other AI:

"Generate Jest tests in src/auth/__tests__/login.test.ts for every scenario in this spec. Use the auth service at src/auth/service.ts."

The structured Given/When/Then steps map directly to test setup, action, and assertion phases. The @mocks and @edge-cases blocks give the AI everything it needs to write complete tests.

---

Setting up on a new machine

# 1. Install Python 3.10+ if needed
#    macOS:   brew install python
#    Ubuntu:  sudo apt install python3 python3-pip

# 2. Install Pango (macOS only — needed by the PDF renderer)
brew install pango

# 3. Install testdoc
pipx install testdoc-specer

# 4. Verify
testdoc --version

# 5. Start writing
mkdir my-specs
testdoc serve my-specs/

Ubuntu / Debian — install Pango system packages instead:

sudo apt install libpango-1.0-0 libpangocairo-1.0-0

Windows — install GTK3 runtime from gtk.org, which includes Pango.

---

Project structure

src/testdoc/
  cli.py            CLI entry point (Typer)
  spec_parser.py    .spec.md parser
  parser.py         Legacy .feature parser
  linter.py         testdoc check logic
  scaffolder.py     testdoc new template
  watcher.py        testdoc watch (watchdog)
  paths.py          Path helpers
  runner.py         Markdown run doc generator
  renderer/
    html.py         Spec → HTML
    pdf.py          HTML → PDF (WeasyPrint)
    styles.css      PDF stylesheet
    templates/      Jinja2 templates
  server/
    serve.py        Local HTTP server
    app.html        Browser UI