Add GenAI test util (#11)

* Add genai test utils

Author: lmolkova

.github/instructions/instrumentation-genai.instructions.md

@@ -20,30 +20,64 @@ prefer opt-in or additive. Breaking changes need explicit justification in the P
 ## 1. Maintenance commitment
 
 - New instrumentations require contributor commitment to long-term maintenance. See
-  [Expectations from contributors](../../CONTRIBUTING.md#expectations-from-contributors) and the
-  general [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations).
+  [Expectations from contributors](../../CONTRIBUTING.md#expectations-from-contributors), the
+  general [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations), and
+  the GenAI-specific expectations in
+  [`CONTRIBUTING.md#guideline-for-genai-instrumentations`](../../CONTRIBUTING.md#guideline-for-genai-instrumentations).
 
-## 2. Semantic conventions
+## 2. Telemetry and configuration via `opentelemetry-util-genai`
 
+- Spans, logs, metrics, and events must go through `opentelemetry-util-genai`. Direct use of
+  `Tracer`, `Meter`, `Logger`, or event APIs is not allowed.
+- Content capture, hooks, and other cross-cutting configuration are owned by the util.
+  Instrumentations must not introduce their own env vars, settings, or hook interfaces.
+- Message content, prompts, and tool call arguments must only be set through the util's content
+  capture path — never as unconditional span/log attributes.
+- Adding attributes to invocations produced by the util is fine.
+- If a capability is missing in `opentelemetry-util-genai`, land it in the util first.
+
+## 3. Semantic conventions
+
+- Attributes, spans, events, and metrics must match the
+  [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai).
 - Attribute names must come from the semconv attribute modules, not hardcoded strings. Use the
   module matching the namespace under `opentelemetry.semconv` (e.g. `server_attributes`,
-  `error_attributes`, `http_attributes`, `db_attributes`, …).
+  `error_attributes`, `http_attributes`, `db_attributes`, …). `gen_ai.*` attribute names must
+  come from `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`.
 - For attributes with a well-known value set in semconv, use the generated enum from the same
-  modules instead of string literals.
+  module (e.g. `GenAiOutputTypeValues` for `gen_ai.output.type`) instead of string literals.
 - If a signal is not in semconv, wait until semconv lands.
 
-## 3. Exception handling
+## 4. Exception handling
 
 - When catching exceptions from the underlying library to record telemetry, always re-raise the
   original exception unmodified.
 - Do not raise **new** exceptions in instrumentation/telemetry code.
 
-## 4. Tests
+## 5. Tests
 
 - For every public API instrumented, cover sync/async variants when both exist.
-- Cover happy path and error scenarios.
+- Cover streaming and non-streaming variants when both exist.
+- Cover happy path and error scenarios. For error scenarios, at minimum include: provider error /
+  endpoint unavailable, stream interrupted by network, stream closed early by the caller.
+- Use recorded VCR cassettes for provider calls. No live-key-only tests; skipping on missing key
+  is not acceptable.
 - Tests must verify exact attribute names **and value types**, checked against the semconv spec.
 - Test against oldest and latest supported library versions via `tests/requirements.{oldest,latest}.txt`
   and `{oldest,latest}` `tox.ini` factors.
+- `tests/conftest.py` must consume the shared fixtures from `opentelemetry.test_util_genai`
+  (`from opentelemetry.test_util_genai.fixtures import *` and
+  `from opentelemetry.test_util_genai.vcr import fixture_vcr, scrub_response_headers`). Do not
+  re-implement in-memory provider/exporter setup or the VCR pretty-print serializer locally.
+
+## 6. Examples
+
+New instrumentations must ship a minimal example under the package's `examples/`, with both a
+`manual/` and a `zero-code/` (auto-instrumentation) variant.
+
+## 7. PR description
+
+- Cover which part of the GenAI semconv the change implements or follows (when applicable) and
+  how instrumentations should consume it.
 
 See also [AGENTS.md](../../AGENTS.md) for general repo rules.

.github/instructions/instrumentation.instructions.md

@@ -14,7 +14,7 @@ commitment — limit public API.
 ## 1. Semconv first
 
 No code without semconv. If a signal, attribute, or operation is not in the
-[GenAI semconv](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/),
+[GenAI semconv](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/),
 land the semconv change first.
 
 ## 2. Semantic conventions

.github/instructions/util-genai.instructions.md

@@ -35,6 +35,8 @@ comment - not in the PR description.
 
 - `instrumentation/` - GenAI instrumentation packages
 - `util/opentelemetry-util-genai/` - shared GenAI utilities
+- `util/opentelemetry-test-util-genai/` - shared test fixtures and assertion helpers
+  (workspace-internal, not published)
 
 Instrumentation packages live under `src/opentelemetry/instrumentation/{name}/` with their own
 `pyproject.toml` and `tests/`. The util package follows the equivalent layout under
@@ -92,6 +94,10 @@ Apply to packages under `instrumentation/`.
 - Tests must verify exact attribute names **and value types**, checked against the semconv spec.
 - Test against oldest and latest supported library versions via `tests/requirements.{oldest,latest}.txt`
   and `{oldest,latest}` `tox.ini` factors.
+- `tests/conftest.py` must consume the shared fixtures from
+  `opentelemetry.test_util_genai` (`from opentelemetry.test_util_genai.fixtures import *` and
+  `from opentelemetry.test_util_genai.vcr import fixture_vcr, scrub_response_headers`) rather
+  than re-implementing provider/exporter/VCR plumbing.
 
 The parallel PR-review rules live in
 [`.github/instructions/instrumentation.instructions.md`](.github/instructions/instrumentation.instructions.md)