pytest-traceoptix

Opt-in, policy-aware pytest publishing for TraceOptix. Collects test outcomes, step timelines, BDD steps, HTTP call details, and framework-produced evidence (screenshots, videos, traces) without requiring any test-code changes.

Full developer reference: docs/USER_GUIDE.md
Internal design: docs/ARCHITECTURE.md

Not released to PyPI. Install directly from the repository.

---

Quick start

pip install ./plugins/traceoptix-pytest

export TRACEOPTIX_URL=https://traceoptix.example.com
export TRACEOPTIX_TOKEN=td_...
export TRACEOPTIX_PROJECT=my-project

pytest --traceoptix

No test-code changes needed. Outcomes, durations, markers, and captured output are published automatically. --junitxml is not required.

---

Example projects

Example	Pattern	Steps
bookshop	Plain pytest, no imports	No
bookshop-steps	step() + requests_session()	Yes — explicit
bookshop-bdd	pytest-bdd, no step()	Yes — Given/When/Then auto-collected

The bookshop suite targets a fictional API at bookshop.example.com and is intended as readable documentation, not a runnable fixture.

---

What's collected

Without any test changes:

• All test outcomes (passed / failed / skipped / errored)
• Duration, captured stdout/stderr/log
• Custom markers as JUnit properties
• @p0–@p3 priority markers → TestPriorityDeclaration
• @pytest.mark.issue / @pytest.mark.ticket keys → TestIssueDeclaration
• Evidence from the pytest-playwright output dir (screenshots, videos, traces)

With from pytest_traceoptix import step:

• Named step timeline entries with duration, status, and annotations

With pytest-bdd installed:

• Given/When/Then steps auto-collected as bdd.step timeline entries

With from pytest_traceoptix import requests_session:

• HTTP calls inside step() blocks as http child entries with sanitized cURL

---

Configuration

Variable	Description
TRACEOPTIX_TOKEN	API token — environment only, never ini/CLI
TRACEOPTIX_URL	Server origin (https://…)
TRACEOPTIX_PROJECT	Project key
TRACEOPTIX_BUNDLE_MODE	always (default) | on-failure | off
TRACEOPTIX_BUNDLE_DIR	Directory for local ZIP bundle (default: CWD)
TRACEOPTIX_ORG	Organisation slug for run URL output
TRACEOPTIX_RUN_NAME	Display name prefix (default: pytest run)
TRACEOPTIX_ENVIRONMENT	Deployment environment label
TRACEOPTIX_BRANCH / TRACEOPTIX_COMMIT_SHA	Source revision overrides
TRACEOPTIX_CI_*	Per-field CI context overrides

TRACEOPTIX_URL and TRACEOPTIX_PROJECT can also be set via --traceoptix-url, --traceoptix-project CLI flags, or traceoptix_url / traceoptix_project in pytest.ini. See docs/USER_GUIDE.md for the full table.

pytest.ini example

[pytest]
traceoptix_url = https://traceoptix.example.com
traceoptix_project = my-project
traceoptix_bundle_mode = on-failure

---

Local ZIP bundle (PLG-01)

A portable {bundleId}.traceoptix-run.zip is written after every session (bundle mode always). It contains:

manifest.json    Schema v2 — run metadata, priorities, issues
results.xml      Merged JUnit XML
steps/           Step timeline JSON per test (full mode only)
evidence/        Screenshots, videos, traces from the playwright output dir

When publication fails, the terminal prints the ZIP path and recovery command:

TraceOptix: recovery bundle: /path/to/{id}.traceoptix-run.zip
  (import with: traceoptix import /path/to/{id}.traceoptix-run.zip)

---

CI auto-detection

GitHub Actions, GitLab CI, Jenkins, CircleCI, Buildkite, Azure Pipelines, Bitbucket Pipelines, and TeamCity are detected automatically. Override any field with TRACEOPTIX_CI_PROVIDER, TRACEOPTIX_CI_BUILD_NUMBER, etc.

---

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/ruff check src tests
.venv/bin/ruff format --check src tests
.venv/bin/pytest -q
.venv/bin/python -m build

The integration suite uses an ephemeral localhost HTTP server and real pytest subprocesses. No tenant credentials or databases are required.

---

References

• User guide
• Architecture
• Plugin framework baseline PRD
• pytest plugin PRD
• Plugin protocol reference