Add integration test framework: plan, workload binary, harness scaffolding

- INTEGRATIONTESTS-PLAN.md: full design for e2e integration tests
- integrationtests/cmd/ioworkload: standalone binary with 13 I/O scenarios
- integrationtests/expectations.go: ExpectedEvent type and assertion helpers
- integrationtests/parse.go: .ior.zst parser producing TestResult
- Export IterRecord and LoadFromFile in flamegraph package
- Fix TraceId -> TraceID, StringByName returns error instead of panic

Amp-Thread-ID: https://ampcode.com/threads/T-019c8031-c106-757a-95a0-7a5457163ce7
Co-authored-by: Amp <amp@ampcode.com>

1 files changed, 30 insertions, 0 deletions

diff --git a/integrationtests/README.md b/integrationtests/README.md
new file mode 100644
index 0000000..741d14d
--- /dev/null
+++ b/integrationtests/README.md
@@ -0,0 +1,30 @@
+# Integration Tests
+
+End-to-end integration tests for ior. A standalone I/O workload binary performs
+deterministic syscalls, ior traces the workload by PID via BPF, and the test
+harness asserts the captured `.ior.zst` output matches expectations.
+
+## Prerequisites
+
+- Built `ior` binary and `ior.bpf.o` (`mage all`)
+- Root privileges or `CAP_BPF` (required for BPF tracepoint attachment)
+
+## Running
+
+```bash
+mage integrationTest
+```
+
+This builds everything (ior, ioworkload) and runs the test suite with `sudo`.
+
+Tests automatically skip with `t.Skip` when not running as root.
+
+## Structure
+
+- `cmd/ioworkload/` — Standalone binary performing known I/O patterns
+- `harness.go` — Test orchestration (start ior + workload, collect output)
+- `parse.go` — Parse `.ior.zst` into assertable `TestResult`
+- `expectations.go` — `ExpectedEvent` type and assertion helpers
+- `*_test.go` — One file per syscall family
+
+See `../INTEGRATIONTESTS-PLAN.md` for the full design.