# Baseline Test Session Guide

This guide contains important instructions for working on baseline tests and oteltest development.

## Running oteltest

**CRITICAL:** Always activate the virtual environment first, then run oteltest:

```bash
source .venv/bin/activate && oteltest path/to/test.py
```

**DO NOT** try to:
- Run `python -m oteltest`
- Run `.venv/bin/oteltest` directly
- Use any other method

The correct pattern is: activate venv → run `oteltest` command.

## Git Commit Guidelines

**DO NOT** include `Co-Authored-By: Claude <noreply@anthropic.com>` in commit messages.

Write commit messages in standard format without co-author attribution.

## Additional Instructions

(To be expanded as we work on baseline tests)

### Test Organization

- Baseline tests go in `baseline_tests/opentelemetry_python/v1_27/`
- Use subdirectories: `traces/`, `metrics/`, `logs/`, `errors/`, `concurrency/`, `edge_cases/`

### Test Naming Convention

- Test class names must contain "OtelTest" (e.g., `BaselineTraceHttpProtobufOtelTest`)
- Use descriptive file names (e.g., `http_protobuf.py`, `grpc_protobuf.py`)

### Running Tests

```bash
# Single test
source .venv/bin/activate && oteltest baseline_tests/path/to/test.py

# All tests in directory
source .venv/bin/activate && oteltest baseline_tests/opentelemetry_python/v1_27/traces/
```

### Telemetry Object Structure

The `tel` object passed to `on_stop()` has:
- `tel.trace_requests` (NOT `tel.traces`)
- `tel.metric_requests` (NOT `tel.metrics`)
- `tel.log_requests` (NOT `tel.logs`)

Use helper functions from `oteltest.telemetry`:
```python
from oteltest.telemetry import count_spans, first_span, get_span_names
```

## Workflow

### Creating New Tests

1. Create branch: `git checkout -b descriptive-branch-name`
2. Write test file
3. Run test to verify it works
4. Add and commit changes
5. Push branch (don't merge without approval)

### Making Changes to oteltest

1. Create branch for the specific change
2. Make minimal, focused changes
3. Test with existing example scripts
4. Commit without co-author attribution
5. Document changes if needed
