Metadata-Version: 2.4
Name: pytest-traceoptix
Version: 0.4.0
Summary: Opt-in, policy-aware pytest publishing for TraceOptix
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pytest<10,>=8.4
Provides-Extra: requests
Requires-Dist: requests<3,>=2.32; extra == "requests"
Provides-Extra: test
Requires-Dist: build; extra == "test"
Requires-Dist: ruff; extra == "test"
Requires-Dist: pytest-xdist<4,>=3; extra == "test"
Requires-Dist: pytest-rerunfailures<17,>=16; extra == "test"
Requires-Dist: requests<3,>=2.32; extra == "test"
Requires-Dist: pytest-bdd<9,>=8; extra == "test"

# 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`](docs/USER_GUIDE.md)  
Internal design: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)

**Not released to PyPI.** Install directly from the repository.

---

## Quick start

```bash
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](examples/bookshop/README.md) | Plain pytest, no imports | No |
| [bookshop-steps](examples/bookshop-steps/README.md) | `step()` + `requests_session()` | Yes — explicit |
| [bookshop-bdd](examples/bookshop-bdd/README.md) | 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`](docs/USER_GUIDE.md) for the full table.

### pytest.ini example

```ini
[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

```bash
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](docs/USER_GUIDE.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Plugin framework baseline PRD](../../docs/prds/14-plugin-framework.md)
- [pytest plugin PRD](../../docs/prds/15-pytest-plugin.md)
- [Plugin protocol reference](../../plugins/PROTOCOL.md)
