tfs-test-runner

Convert Azure DevOps / TFS test case xlsx exports into a self-contained HTML test execution kit with screenshot capture, status tracking, notes, and PDF evidence export. No server, works offline. Optional GPT translation.

📖 Full docs: luizhcrs.github.io/tfs-test-runner (PT-BR)

Dark theme (default)	Light theme

Settings panel (theme + PDF options)	Case detail with evidence

More screenshots — failures filter, PDF evidence, PDF with status badges, full plan, mobile, empty state

Filter "Failures"	PDF evidence (default)

PDF with status pills (toggle ON)	Mobile / narrow viewport

Empty state	Full plan (long screenshot)
	03-full-plan.png

Quick start

pip install tfs-test-runner

# Scaffold a fresh QA plan directory with templates
tfs-test-runner init my-qa-plan
cd my-qa-plan
# … fill in cases.xlsx …

# Validate the schema
tfs-test-runner validate cases.xlsx

# Generate the HTML execution kit
tfs-test-runner plan cases.xlsx -o plan.html

Open plan.html in any browser. The tester pastes screenshots (Ctrl+V) at each step, marks PASS/FAIL/N/A, writes notes, then clicks PDF for an evidence deliverable.

No Azure DevOps? Use init

tfs-test-runner init scaffolds a directory with a blank xlsx template (cell comments documenting each column) plus example phases.yaml and glossary.yaml. Fill the xlsx manually — same schema as Azure DevOps Test Plans → Export to Excel.

Subcommands

tfs-test-runner --help                    # full command list
tfs-test-runner plan cases.xlsx           # generate HTML kit
tfs-test-runner validate cases.xlsx       # check schema, print stats
tfs-test-runner init my-plan              # scaffold new plan
tfs-test-runner screenshots               # regen docs prints (maintainers)

Common flags

# GPT translation (paid, best quality)
export OPENAI_API_KEY=sk-...
tfs-test-runner plan cases.xlsx --llm --lang pt-BR -o plan.html

# Argos translation (free, offline; auto-installs language pair)
pip install 'tfs-test-runner[argos]'
tfs-test-runner plan cases.xlsx --argos --lang pt-BR -o plan.html

# Phase grouping + custom title + logo
tfs-test-runner plan cases.xlsx \
    --phases phases.yaml \
    --title "Sprint 42 — Acceptance" \
    --logo company.png -o plan.html

# Validate before generating
tfs-test-runner validate cases.xlsx --strict

Features

• Phase / case / step tree, search (/), filter chips, expand/collapse
• Per-step PASS / FAIL / N/A, notes textarea, paste/drop/pick screenshot
• Per-image captions, lightbox zoom
• Per-case PDF (evidence-only) and full-plan PDF with cover sheet
• Settings panel (gear icon): light/dark/auto theme + status-in-PDF toggle
• JSON backup/restore (state + images)
• Keyboard: / search, Ctrl+P PDF, Esc close lightbox/settings

💡 In the print dialog, uncheck "Headers and footers" so the browser doesn't inject file:///… and date/time at every page.

Documentation

• docs/USAGE.md · PT-BR — full walkthrough for testers
• docs/ARCHITECTURE.md · PT-BR — pipeline, data shapes, design choices
• CONTRIBUTING.md — dev setup
• CHANGELOG.md — release notes

YAML configs (examples in examples/)

# phases.yaml — group cases
phases:
  - id: p1
    title: "Phase 1 — Smoke"
    level: easy
    case_ids: ["101", "104"]
  - id: p2
    title: "Phase 2 — Failures"
    match: ["failure", "invalid", "error"]

# glossary.yaml — refine LLM translation (optional)
preserve: ["Sign In", "Save", "Cancel"]
notes: "Domain: web QA. Tone: technical, imperative."

Python API

from tfs_test_runner import parse_xlsx, translate_cases, assign_phases, render

cases = parse_xlsx("cases.xlsx")
translate_cases(cases, backend="llm", target_lang="pt-BR")
render(assign_phases(cases), "plan.html", page_title="My Plan")

Development

pip install -e .[dev]
pytest -q

CI matrix: Ubuntu / macOS / Windows × Python 3.10 / 3.11 / 3.12.

License

MIT — © 2026 luizhcrs. PRs welcome.