Metadata-Version: 2.4
Name: testdoc-specer
Version: 0.1.0
Summary: Write structured test specs, run them manually in a local UI, export to PDF or Markdown, hand to AI for test generation
Project-URL: Repository, https://github.com/pkjrockzz/testdoc-specer
License: MIT
Keywords: bdd,gherkin,pdf,qa,test-documentation,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: gherkin-official>=29.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: markdown>=3.5.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: weasyprint>=61.0
Description-Content-Type: text/markdown

# 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)

```bash
# from PyPI
pip install testdoc-specer

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

**macOS only** — install Pango before first use:
```bash
brew install pango
```

---

## Quick start

```bash
# 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:

```markdown
# 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 "alice@example.com"
  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 "alice@example.com"
  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:

```bash
# 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

```bash
# 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:
```bash
sudo apt install libpango-1.0-0 libpangocairo-1.0-0
```

**Windows** — install GTK3 runtime from [gtk.org](https://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
```
