DEV Community

Cover image for RepoTrace — Make failing commands repeatable, inspectable, and testable
Biki Kc
Biki Kc

Posted on

RepoTrace — Make failing commands repeatable, inspectable, and testable

#cli #debugging #python #testing

Why it matters
When a command fails in your project or CI, “it failed” is rarely enough to act on. RepoTrace saves the exact argv, exit code, stdout/stderr, working directory, and interpreter metadata so a failure becomes a replayable artifact — a single-file, JSON bug report that you can rerun, render as Markdown, or convert into a standalone pytest regression test. That preserves the signal of the original failure and turns debugging into a repeatable, auditable process.

What RepoTrace is
RepoTrace is a small Python CLI and library (Python 3.12+) that captures command runs and produces:

  • Structured bug reports persisted as JSON files under a report store (.repotrace/reports by default).
  • Replay functionality to re-run recorded commands and compare results to the original trace.
  • Markdown rendering for human-friendly reports.
  • Generation of self-contained pytest regression tests that embed the command and expected output.

Core benefits

  • Reproducibility: replay a failure later (or on another machine) to confirm whether it still reproduces.

  • Traceability: keep a single-file record suitable for committing alongside a codebase or attaching to an issue.

  • CI friendliness: use capture/replay in pipelines to collect failing commands automatically and assert regressions as tests.

  • Fast triage: readable Markdown and tests remove context-switching and guesswork from debugging.

Quick highlights

  • Language: Python 3.12+
  • CLI: repotrace (Typer-based)
  • Notable libraries: Pydantic v2 (structured models), Rich (console output), Typer (CLI)
  • License: MIT

Why teams should try RepoTrace

  • Speed up debugging: capturing everything about a failing command means no more “works on my machine” guessing.
  • Create durable artifacts: JSON reports are easy to inspect, diff, and commit; generated tests are ready to land in CI.
  • Reduce friction between triage and fix: a report plus a generated test gives a precise spec of the problem that a reviewer or teammate can reproduce **locally.

Installation & Resources

ReproTrace is distributed under the MIT license and can be installed using standard Python package managers:

PyPI: https://pypi.org/project/repotrace/

GitHub Repository: https://github.com/BiTech5/repotrace
Enter fullscreen mode Exit fullscreen mode

Join the Journey
Join RepoTrace — short invite RepoTrace turns failing commands into replayable bug reports and ready-to-commit regression tests — help make debugging reproducible.

Quick start

Fork & clone https://github.com/BiTech5/repotrace
uv sync && source .venv/bin/activate
Run a focused test: .venv/bin/python -m pytest tests/test_replay.py -q
Enter fullscreen mode Exit fullscreen mode

Good first contributions

Fix small bugs, improve README examples, add edge-case tests, or generate CI/usage walkthroughs.
Enter fullscreen mode Exit fullscreen mode

Conclusion / Call to action

RepoTrace reduces the time and friction of turning an observed failure into a replayable, testable artifact. If your team spends time reproducing flaky or intermittent failures, trying RepoTrace on a representative failing command (or a CI job) can immediately pay dividends: you get a concrete, versionable report and the option to convert it into a regression test that prevents regressions from returning.

Would you like a short blog-ready version of this article (250–400 words), or a ready-made example demonstrating capture → generate → commit for a small sample project?

Top comments (0)