TheRock/rocm-systems/experimental/python/perfxpert/docs/contributing/fixtures.md

Contributing: new test fixture

What you're adding

A SQLite database (.db) that represents a rocpd trace, paired with documentation (.md) describing what it contains and how to regenerate it. Fixtures are used across unit, integration, and benchmarking tests.

File locations

• Database: tests/fixtures/<name>.db or tests/fixtures/<category>/<name>.db
• Documentation: tests/fixtures/<name>.md or tests/fixtures/<category>/<name>.md
• Generator (if synthetic): tests/fixtures/_build_<name>.py or _generators/<name>.py

Size constraint

Each fixture .db must be < 1 MB. Larger traces should be:

• Downsampled (keep only hottest kernels)
• Synthetic (generated from parameters)
• Hosted externally with a download script

Documentation template

# Fixture: <name>

## What it contains

<Description of the GPU, kernel, workload, and metrics represented.>

## How to regenerate

<Step-by-step command or script to rebuild the .db from scratch.>

```bash
# SKIP-SAMPLE — template placeholder (<name> not a real path)
python3 tests/fixtures/_generators/<name>.py

Baseline

Built on: <GPU model, ROCm version, hardware date> MD5: <hash of the .db file>

## Schema requirements

All rocpd fixtures follow the rocpd UUID-based trace schema:
- Tables: `rocpd_data`, `metrics`, `kernel_events`
- ID columns: UUIDs (string)
- Metadata: creation timestamp, ROCm version, GPU ID

See `CLAUDE.md` §SQLite + rocpd for the full schema reference.

## Tests that use it

- List any existing tests that consume this fixture
- Example: `tests/test_tools/test_classifier.py::test_classify_compute_bound`

## Common pitfalls

- If real trace: sanitize kernel names (remove proprietary project names)
- If synthetic: keep DB size small (compress via VACUUM)
- Don't commit large binaries; use generators instead
- Update MD5 in docs if you regenerate

## Checklist before commit

- [ ] `.db` file < 1 MB
- [ ] `.md` file with regeneration steps
- [ ] Generator script in `_generators/` (if synthetic)
- [ ] Generator produces byte-identical output (deterministic)
- [ ] Fixture used by ≥ 1 test (no orphans)

## Related docs

- rocpd schema: https://github.com/ROCm/rocprofiler-sdk
- Real trace capture: `rocprofv3` CLI reference