Add Python tracer test design

Author: tzanko-matev

docs/py-test-design-001.md

@@ -0,0 +1,60 @@
+# Python sys.monitoring Tracer Test Design
+
+## Overview
+This document outlines a test suite for validating the Python tracer built on `sys.monitoring` and `runtime_tracing`. Each test item corresponds to roughly 1–10 lines of implementation and exercises tracer behavior under typical and edge conditions.
+
+## Setup
+- Establish a temporary directory for trace output and source snapshots.
+- Install the tracer module and import helper utilities for running traced Python snippets.
+- Provide fixtures that clear the trace buffer and reset global state between tests.
+
+## Tool Initialization
+- Acquire a monitoring tool ID and ensure subsequent calls reuse the same identifier.
+- Register callbacks for all enabled events and verify the resulting mask matches the design.
+- Unregister callbacks on shutdown and confirm no events fire afterward.
+
+## Event Recording
+### Control Flow Events
+- Capture `PY_START` and `PY_RETURN` for a simple script and assert a start/stop pair is recorded.
+- Resume and yield events within a generator function produce matching `PY_RESUME`/`PY_YIELD` entries.
+- A `PY_THROW` followed by `RERAISE` generates the expected unwind and rethrow sequence.
+
+### Call Tracking
+- Direct function calls record `CALL` and `PY_RETURN` with correct frame identifiers.
+- Recursive calls nest frames correctly and unwind in LIFO order.
+- Decorated functions ensure wrapper frames are recorded separately from wrapped frames.
+
+### Line and Branch Coverage
+- A loop with conditional branches emits `LINE` events for each executed line and `BRANCH` for each branch taken or skipped.
+- Jump statements such as `continue` and `break` produce `JUMP` events with source and destination line numbers.
+
+### Exception Handling
+- Raising and catching an exception emits `RAISE` and `EXCEPTION_HANDLED` events with matching exception IDs.
+- An uncaught exception records `RAISE` followed by `PY_UNWIND` and terminates the trace with a `PY_THROW`.
+
+### C API Boundary
+- Calling a built-in like `len` results in `C_CALL` and `C_RETURN` events linked to the Python frame.
+- A built-in that raises, such as `int("a")`, generates `C_RAISE` with the translated exception value.
+
+## Value Translation
+- Primitive values (ints, floats, strings, bytes) round-trip through the value registry and appear in the trace as expected.
+- Complex collections like lists of dicts are serialized recursively with cycle detection preventing infinite loops.
+- Object references without safe representations fall back to `repr` with a stable identifier.
+
+## Metadata and Source Capture
+- The trace writer copies the executing script into the output directory and records its SHA-256 hash.
+- Traces include `ProcessMetadata` fields for Python version and platform.
+
+## Shutdown Behavior
+- Normal interpreter exit flushes the trace and closes files without losing events.
+- An abrupt shutdown via `os._exit` truncates the trace file but leaves previous events intact.
+
+## Error and Edge Cases
+- Invalid event names in manual callback registration raise a clear `ValueError`.
+- Attempting to trace after the writer is closed results in a no-op without raising.
+- Large string values exceeding the configured limit are truncated with an explicit marker.
+
+## Performance and Stress
+- Tracing a tight loop of 10⁶ iterations completes within an acceptable time budget.
+- Concurrent threads each produce isolated traces with no frame ID collisions.
+