diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..dd4a535e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,370 @@
+# Snowplow Python Tracker - CLAUDE.md
+
+## Project Overview
+
+The Snowplow Python Tracker is a public Python library for sending analytics events to Snowplow collectors. It enables developers to integrate Snowplow analytics into Python applications, games, and web servers. The library provides a robust event tracking system with support for various event types, custom contexts, and reliable event delivery through configurable emitters.
+
+**Key Technologies:**
+- Python 3.8+ (supported versions: 3.8-3.13)
+- requests library for HTTP communication
+- typing_extensions for enhanced type hints
+- Event-driven architecture with schema validation
+- Asynchronous and synchronous event emission
+
+## Development Commands
+
+```bash
+# Install dependencies
+pip install -r requirements-test.txt
+
+# Run tests
+./run-tests.sh
+
+# Run specific test module
+python -m pytest snowplow_tracker/test/unit/test_tracker.py
+
+# Run integration tests
+python -m pytest snowplow_tracker/test/integration/
+
+# Install package in development mode
+pip install -e .
+
+# Build Docker image for testing
+docker build -t snowplow-python-tracker .
+docker run snowplow-python-tracker
+```
+
+## Architecture
+
+The tracker follows a layered architecture with clear separation of concerns:
+
+```
+snowplow_tracker/
+├── Core Components
+│   ├── tracker.py          # Main Tracker class orchestrating events
+│   ├── snowplow.py         # High-level API for tracker management
+│   └── subject.py          # User/device context management
+├── Event Layer (events/)
+│   ├── event.py            # Base Event class
+│   ├── page_view.py        # PageView event
+│   ├── structured_event.py # Structured events
+│   └── self_describing.py  # Custom schema events
+├── Emission Layer
+│   ├── emitters.py         # Sync/Async event transmission
+│   ├── event_store.py      # Event buffering and persistence
+│   └── payload.py          # Event payload construction
+├── Configuration
+│   ├── tracker_configuration.py
+│   └── emitter_configuration.py
+└── Validation
+    ├── contracts.py        # Runtime validation
+    └── typing.py           # Type definitions
+```
+
+## Core Architectural Principles
+
+1. **Schema-First Design**: All events conform to Iglu schemas for consistency
+2. **Separation of Concerns**: Event creation, validation, and emission are separate
+3. **Configuration Objects**: Use dedicated configuration classes, not raw dictionaries
+4. **Type Safety**: Extensive use of type hints and Protocol classes
+5. **Fail-Safe Delivery**: Events are buffered and retried on failure
+6. **Immutability**: Event objects are largely immutable after creation
+
+## Layer Organization & Responsibilities
+
+### Application Layer (snowplow.py)
+- Singleton pattern for global tracker management
+- Factory methods for tracker creation
+- Namespace-based tracker registry
+
+### Domain Layer (tracker.py, events/)
+- Event creation and validation
+- Subject (user/device) context management
+- Event enrichment with standard fields
+
+### Infrastructure Layer (emitters.py, event_store.py)
+- HTTP communication with collectors
+- Event buffering and retry logic
+- Async/sync emission strategies
+
+### Cross-Cutting (contracts.py, typing.py)
+- Runtime validation with togglable contracts
+- Shared type definitions and protocols
+
+## Critical Import Patterns
+
+```python
+# ✅ Import from package root for public API
+from snowplow_tracker import Snowplow, Tracker, Subject
+from snowplow_tracker import EmitterConfiguration, TrackerConfiguration
+
+# ✅ Import specific event classes
+from snowplow_tracker.events import PageView, StructuredEvent
+
+# ❌ Don't import from internal modules
+from snowplow_tracker.emitters import Requester  # Internal class
+
+# ✅ Use typing module for type hints
+from snowplow_tracker.typing import PayloadDict, Method
+```
+
+## Essential Library Patterns
+
+### Tracker Initialization Pattern
+```python
+# ✅ Use Snowplow factory with configuration objects
+tracker = Snowplow.create_tracker(
+    namespace="my_app",
+    endpoint="https://collector.example.com",
+    tracker_config=TrackerConfiguration(encode_base64=True),
+    emitter_config=EmitterConfiguration(batch_size=10)
+)
+
+# ❌ Don't instantiate Tracker directly without Snowplow
+tracker = Tracker("namespace", emitter)  # Missing registration
+```
+
+### Event Creation Pattern
+```python
+# ✅ Use event classes with named parameters
+page_view = PageView(
+    page_url="https://example.com",
+    page_title="Homepage"
+)
+
+# ✅ Add contexts to events
+event.context = [SelfDescribingJson(schema, data)]
+
+# ❌ Don't modify event payload directly
+event.payload.add("custom", "value")  # Breaks schema validation
+```
+
+### Subject Management Pattern
+```python
+# ✅ Set subject at tracker or event level
+subject = Subject()
+subject.set_user_id("user123")
+tracker = Snowplow.create_tracker(..., subject=subject)
+
+# ✅ Override subject per event
+event = PageView(..., event_subject=Subject())
+
+# ❌ Don't modify subject after tracker creation
+tracker.subject.set_user_id("new_id")  # Not thread-safe
+```
+
+### Emitter Configuration Pattern
+```python
+# ✅ Configure retry and buffering behavior
+config = EmitterConfiguration(
+    batch_size=50,
+    buffer_capacity=10000,
+    custom_retry_codes={429: True, 500: True}
+)
+
+# ❌ Don't use magic numbers
+emitter = Emitter(endpoint, 443, "post", 100)  # Use config object
+```
+
+## Model Organization Pattern
+
+### Event Hierarchy
+```python
+Event (base class)
+├── PageView         # Web page views
+├── PagePing         # Page engagement tracking
+├── ScreenView       # Mobile screen views
+├── StructuredEvent  # Category/action/label/property/value events
+└── SelfDescribing   # Custom schema events
+```
+
+### Data Structures
+```python
+# SelfDescribingJson for custom contexts
+context = SelfDescribingJson(
+    "iglu:com.example/context/jsonschema/1-0-0",
+    {"key": "value"}
+)
+
+# Payload for event data assembly
+payload = Payload()
+payload.add("e", "pv")  # Event type
+payload.add_dict({"aid": "app_id"})
+```
+
+## Common Pitfalls & Solutions
+
+### Contract Validation
+```python
+# ❌ Passing invalid parameters silently fails in production
+tracker.track_page_view("")  # Empty URL
+
+# ✅ Enable contracts during development
+from snowplow_tracker import enable_contracts
+enable_contracts()
+```
+
+### Event Buffering
+```python
+# ❌ Not flushing events before shutdown
+tracker.track(event)
+sys.exit()  # Events lost!
+
+# ✅ Always flush before exit
+tracker.track(event)
+tracker.flush()
+```
+
+### Thread Safety
+```python
+# ❌ Sharing emitter across threads
+emitter = Emitter(endpoint)
+# Multiple threads using same emitter
+
+# ✅ Use AsyncEmitter for concurrent scenarios
+emitter = AsyncEmitter(endpoint, thread_count=2)
+```
+
+### Schema Validation
+```python
+# ❌ Hardcoding schema strings
+schema = "iglu:com.snowplow/event/1-0-0"
+
+# ✅ Use constants for schemas
+from snowplow_tracker.constants import CONTEXT_SCHEMA
+```
+
+## File Structure Template
+
+```
+project/
+├── tracker_app.py           # Application entry point
+├── config/
+│   └── tracker_config.py    # Tracker configuration
+├── events/
+│   ├── __init__.py
+│   └── custom_events.py     # Custom event definitions
+├── contexts/
+│   └── custom_contexts.py   # Custom context schemas
+└── tests/
+    ├── unit/
+    │   └── test_events.py
+    └── integration/
+        └── test_emission.py
+```
+
+## Testing Patterns
+
+### Unit Testing
+```python
+# ✅ Mock emitters for unit tests
+@mock.patch('snowplow_tracker.emitters.Emitter')
+def test_track_event(mock_emitter):
+    tracker = Tracker("test", mock_emitter)
+    tracker.track(PageView(...))
+    mock_emitter.input.assert_called_once()
+```
+
+### Contract Testing
+```python
+# ✅ Use ContractsDisabled context manager
+with ContractsDisabled():
+    # Test invalid inputs without raising
+    tracker.track_page_view(None)
+```
+
+### Integration Testing
+```python
+# ✅ Test against mock collector
+def test_event_delivery():
+    with requests_mock.Mocker() as m:
+        m.post("https://collector.test/com.snowplow/tp2")
+        # Track and verify delivery
+```
+
+## Configuration Best Practices
+
+### Environment-Based Configuration
+```python
+# ✅ Use environment variables
+import os
+endpoint = os.getenv("SNOWPLOW_COLLECTOR_URL")
+namespace = os.getenv("SNOWPLOW_NAMESPACE", "default")
+```
+
+### Retry Configuration
+```python
+# ✅ Configure intelligent retry behavior
+EmitterConfiguration(
+    max_retry_delay_seconds=120,
+    custom_retry_codes={
+        429: True,  # Retry rate limits
+        500: True,  # Retry server errors
+        400: False  # Don't retry bad requests
+    }
+)
+```
+
+## Quick Reference
+
+### Import Checklist
+- [ ] Import from `snowplow_tracker` package root
+- [ ] Use `EmitterConfiguration` and `TrackerConfiguration`
+- [ ] Import specific event classes from `snowplow_tracker.events`
+- [ ] Use type hints from `snowplow_tracker.typing`
+
+### Event Tracking Checklist
+- [ ] Create tracker with `Snowplow.create_tracker()`
+- [ ] Configure emitter with appropriate batch size
+- [ ] Set subject context if tracking users
+- [ ] Use appropriate event class for the use case
+- [ ] Add custom contexts as `SelfDescribingJson`
+- [ ] Call `flush()` before application shutdown
+- [ ] Handle failures with callbacks
+
+### Common Event Types
+- `PageView`: Web page views
+- `ScreenView`: Mobile app screens
+- `StructuredEvent`: Generic events with 5 parameters
+- `SelfDescribing`: Custom schema events
+- `PagePing`: Engagement tracking
+
+## Contributing to CLAUDE.md
+
+When adding or updating content in this document, please follow these guidelines:
+
+### File Size Limit
+- **CLAUDE.md must not exceed 40KB** (currently ~19KB)
+- Check file size after updates: `wc -c CLAUDE.md`
+- Remove outdated content if approaching the limit
+
+### Code Examples
+- Keep all code examples **4 lines or fewer**
+- Focus on the essential pattern, not complete implementations
+- Use `// ❌` and `// ✅` to clearly show wrong vs right approaches
+
+### Content Organization
+- Add new patterns to existing sections when possible
+- Create new sections sparingly to maintain structure
+- Update the architectural principles section for major changes
+- Ensure examples follow current codebase conventions
+
+### Quality Standards
+- Test any new patterns in actual code before documenting
+- Verify imports and syntax are correct for the codebase
+- Keep language concise and actionable
+- Focus on "what" and "how", minimize "why" explanations
+
+### Multiple CLAUDE.md Files
+- **Directory-specific CLAUDE.md files** can be created for specialized modules
+- Follow the same structure and guidelines as this root CLAUDE.md
+- Keep them focused on directory-specific patterns and conventions
+- Maximum 20KB per directory-specific CLAUDE.md file
+
+### Instructions for LLMs
+When editing files in this repository, **always check for CLAUDE.md guidance**:
+
+1. **Look for CLAUDE.md in the same directory** as the file being edited
+2. **If not found, check parent directories** recursively up to project root
+3. **Follow the patterns and conventions** described in the applicable CLAUDE.md
+4. **Prioritize directory-specific guidance** over root-level guidance when conflicts exist
\ No newline at end of file
diff --git a/snowplow_tracker/events/CLAUDE.md b/snowplow_tracker/events/CLAUDE.md
new file mode 100644
index 00000000..efc0f5ab
--- /dev/null
+++ b/snowplow_tracker/events/CLAUDE.md
@@ -0,0 +1,284 @@
+# Snowplow Event Types - CLAUDE.md
+
+## Directory Overview
+
+The `events/` directory contains all event type implementations for the Snowplow Python Tracker. Each event class represents a specific type of analytics event that can be sent to Snowplow collectors. All events inherit from the base `Event` class and follow a consistent pattern for construction, validation, and payload generation.
+
+## Event Class Hierarchy
+
+```
+Event (base class)
+├── PageView         # Web page view tracking
+├── PagePing         # Page engagement/heartbeat
+├── ScreenView       # Mobile/app screen views  
+├── StructuredEvent  # Generic 5-parameter events
+└── SelfDescribing   # Custom schema events
+```
+
+## Core Event Patterns
+
+### Event Construction Pattern
+```python
+# ✅ Use keyword arguments for clarity
+event = PageView(
+    page_url="https://example.com",
+    page_title="Homepage",
+    referrer="https://google.com"
+)
+
+# ❌ Don't use positional arguments
+event = PageView("https://example.com", "Homepage")
+```
+
+### Event Context Pattern
+```python
+# ✅ Add contexts as SelfDescribingJson list
+geo_context = SelfDescribingJson(
+    "iglu:com.acme/geolocation/jsonschema/1-0-0",
+    {"latitude": 40.0, "longitude": -73.0}
+)
+event = PageView(page_url="...", context=[geo_context])
+
+# ❌ Don't use raw dictionaries for context
+event.context = [{"latitude": 40.0}]  # Missing schema!
+```
+
+### Event Subject Override Pattern
+```python
+# ✅ Override tracker subject for specific event
+special_subject = Subject()
+special_subject.set_user_id("anonymous_user")
+event = StructuredEvent(
+    category="shop",
+    action="view",
+    event_subject=special_subject
+)
+
+# ❌ Don't modify shared subject
+tracker.subject.set_user_id("temp")  # Affects all events
+```
+
+### True Timestamp Pattern
+```python
+# ✅ Use milliseconds for true_timestamp
+import time
+timestamp_ms = time.time() * 1000
+event = PageView(
+    page_url="...",
+    true_timestamp=timestamp_ms
+)
+
+# ❌ Don't use seconds
+event = PageView(true_timestamp=time.time())
+```
+
+## Event-Specific Patterns
+
+### PageView Events
+```python
+# ✅ Complete PageView with all fields
+page_view = PageView(
+    page_url="https://example.com/products",
+    page_title="Products",
+    referrer="https://example.com/home"
+)
+
+# ❌ Missing required page_url
+page_view = PageView(page_title="Products")
+```
+
+### StructuredEvent Pattern
+```python
+# ✅ Use descriptive category/action pairs
+event = StructuredEvent(
+    category="ecommerce",
+    action="add-to-cart",
+    label="SKU-123",
+    property_="size:XL",
+    value=29.99
+)
+
+# ❌ Generic naming loses meaning
+event = StructuredEvent("event", "click")
+```
+
+### SelfDescribing Events
+```python
+# ✅ Custom events with Iglu schemas
+purchase_event = SelfDescribing(
+    SelfDescribingJson(
+        "iglu:com.acme/purchase/jsonschema/2-0-0",
+        {
+            "orderId": "ORD-123",
+            "total": 99.99,
+            "currency": "USD"
+        }
+    )
+)
+
+# ❌ Missing schema version
+event = SelfDescribing(
+    SelfDescribingJson("iglu:com.acme/purchase", {...})
+)
+```
+
+### ScreenView Pattern (Mobile)
+```python
+# ✅ Mobile screen tracking with ID
+screen = ScreenView(
+    name="ProductDetailScreen",
+    id_="screen-456",
+    previous_name="ProductListScreen"
+)
+
+# ❌ Using PageView for mobile apps
+page = PageView(page_url="app://product-detail")
+```
+
+## Event Validation Rules
+
+### Required Fields by Event Type
+- **PageView**: `page_url` (required), `page_title`, `referrer`
+- **StructuredEvent**: `category`, `action` (required), `label`, `property_`, `value`
+- **SelfDescribing**: `event_json` (SelfDescribingJson required)
+- **ScreenView**: `name` or `id_` (at least one required)
+- **PagePing**: `page_url` (required)
+
+### Schema Validation Pattern
+```python
+# ✅ Validate schema format
+SCHEMA_PATTERN = r"^iglu:[a-zA-Z0-9-_.]+/[a-zA-Z0-9-_]+/"
+SCHEMA_PATTERN += r"[a-zA-Z0-9-_]+/[0-9]+-[0-9]+-[0-9]+$"
+
+# ❌ Invalid schema formats
+"iglu:com.acme/event"  # Missing version
+"com.acme/event/1-0-0"  # Missing iglu: prefix
+```
+
+## Payload Building Pattern
+
+### Internal Payload Construction
+```python
+# ✅ Event classes handle payload internally
+def build_payload(self, encode_base64, json_encoder, subject):
+    # Add event-specific fields
+    self.payload.add("e", "pv")  # Page view type
+    self.payload.add("url", self.page_url)
+    
+    # Let base class handle common fields
+    return super().build_payload(encode_base64, json_encoder, subject)
+
+# ❌ Don't expose payload building to users
+event.payload = Payload()
+event.payload.add("custom", "field")
+```
+
+## Testing Event Classes
+
+### Unit Test Pattern
+```python
+# ✅ Test event construction and validation
+def test_page_view_required_fields():
+    with self.assertRaises(TypeError):
+        PageView()  # Missing required page_url
+    
+    event = PageView(page_url="https://test.com")
+    assert event.page_url == "https://test.com"
+
+# ✅ Test payload generation
+def test_event_payload():
+    event = PageView(page_url="https://test.com")
+    payload = event.build_payload(False, None, None)
+    assert payload.get()["url"] == "https://test.com"
+```
+
+### Context Testing Pattern
+```python
+# ✅ Test context attachment
+def test_event_context():
+    context = SelfDescribingJson(schema, data)
+    event = PageView(page_url="...", context=[context])
+    
+    payload = event.build_payload(True, None, None)
+    assert "cx" in payload.get()  # Base64 context
+```
+
+## Common Event Pitfalls
+
+### Timestamp Confusion
+```python
+# ❌ Mixing timestamp types
+event.true_timestamp = "2024-01-01"  # String not allowed
+event.true_timestamp = datetime.now()  # Use milliseconds
+
+# ✅ Consistent millisecond timestamps
+event.true_timestamp = int(time.time() * 1000)
+```
+
+### Context Array Management
+```python
+# ❌ Modifying context after creation
+event.context.append(new_context)  # Unexpected behavior
+
+# ✅ Set complete context at creation
+all_contexts = [context1, context2]
+event = PageView(page_url="...", context=all_contexts)
+```
+
+### Schema Version Control
+```python
+# ❌ Hardcoding schema versions
+schema = "iglu:com.acme/event/jsonschema/1-0-0"
+
+# ✅ Centralize schema definitions
+PURCHASE_SCHEMA = "iglu:com.acme/purchase/jsonschema/2-1-0"
+event = SelfDescribing(SelfDescribingJson(PURCHASE_SCHEMA, data))
+```
+
+## Event Migration Guide
+
+### Upgrading Event Schemas
+```python
+# From version 1-0-0 to 2-0-0
+# ✅ Handle backward compatibility
+def create_purchase_event(data):
+    if "items" in data:  # New schema
+        schema = "iglu:.../purchase/jsonschema/2-0-0"
+    else:  # Old schema
+        schema = "iglu:.../purchase/jsonschema/1-0-0"
+    
+    return SelfDescribing(SelfDescribingJson(schema, data))
+```
+
+## Quick Reference
+
+### Event Type Selection
+- **PageView**: Traditional web page tracking
+- **ScreenView**: Mobile app screen tracking
+- **StructuredEvent**: Generic business events
+- **SelfDescribing**: Complex custom events
+- **PagePing**: Engagement/time-on-page tracking
+
+### Event Field Checklist
+- [ ] Required fields provided
+- [ ] Timestamps in milliseconds
+- [ ] Contexts as SelfDescribingJson array
+- [ ] Valid Iglu schema format
+- [ ] Event-specific subject if needed
+
+### Common Event Methods
+- `build_payload()`: Internal payload generation
+- `event_subject`: Per-event user context
+- `context`: Custom context array
+- `true_timestamp`: User-defined timestamp
+
+## Contributing to events/CLAUDE.md
+
+When modifying event implementations or adding new event types:
+
+1. **Follow the Event base class pattern** - All events must inherit from Event
+2. **Implement required abstract methods** - Ensure payload building works correctly
+3. **Document required fields** - Update this file with new event requirements
+4. **Add comprehensive tests** - Test construction, validation, and payload generation
+5. **Maintain backward compatibility** - Don't break existing event APIs
+6. **Update schema constants** - Add new schemas to constants.py if needed
\ No newline at end of file
diff --git a/snowplow_tracker/test/CLAUDE.md b/snowplow_tracker/test/CLAUDE.md
new file mode 100644
index 00000000..08d0b042
--- /dev/null
+++ b/snowplow_tracker/test/CLAUDE.md
@@ -0,0 +1,365 @@
+# Snowplow Python Tracker Tests - CLAUDE.md
+
+## Directory Overview
+
+The `test/` directory contains comprehensive test suites for the Snowplow Python Tracker. Tests are organized into unit tests (isolated component testing) and integration tests (end-to-end collector communication). The test suite uses pytest and unittest.mock for mocking, with freezegun for time-based testing.
+
+## Test Organization
+
+```
+test/
+├── unit/                    # Isolated component tests
+│   ├── test_tracker.py      # Tracker class tests
+│   ├── test_emitters.py     # Emitter functionality
+│   ├── test_event.py        # Base event class
+│   ├── test_payload.py      # Payload construction
+│   ├── test_contracts.py    # Validation logic
+│   └── test_*.py            # Other component tests
+└── integration/             # End-to-end tests
+    └── test_integration.py  # Collector communication
+```
+
+## Core Testing Patterns
+
+### Mock Pattern for Emitters
+```python
+# ✅ Mock emitter for isolated tracker testing
+@mock.patch('snowplow_tracker.emitters.Emitter')
+def test_tracker_tracks_event(mock_emitter):
+    tracker = Tracker("test", mock_emitter)
+    tracker.track(PageView(page_url="test.com"))
+    mock_emitter.input.assert_called_once()
+
+# ❌ Don't test with real network calls in unit tests
+def test_tracker():
+    emitter = Emitter("https://real-collector.com")
+```
+
+### Contract Testing Pattern
+```python
+# ✅ Use ContractsDisabled context manager
+class ContractsDisabled:
+    def __enter__(self):
+        disable_contracts()
+    def __exit__(self, type, value, traceback):
+        enable_contracts()
+
+with ContractsDisabled():
+    # Test invalid inputs without raising
+    tracker.track_page_view(None)
+
+# ❌ Don't disable contracts globally
+disable_contracts()
+# ... rest of test file
+```
+
+### Time-Based Testing Pattern
+```python
+# ✅ Use freezegun for deterministic timestamps
+from freezegun import freeze_time
+
+@freeze_time("2024-01-01 12:00:00")
+def test_event_timestamp():
+    event = PageView(page_url="test.com")
+    # Timestamp will be consistent
+
+# ❌ Don't use actual system time
+import time
+timestamp = time.time()  # Non-deterministic
+```
+
+### UUID Mocking Pattern
+```python
+# ✅ Mock UUID generation for predictable IDs
+@mock.patch('snowplow_tracker.tracker.Tracker.get_uuid')
+def test_event_id(mock_uuid):
+    mock_uuid.return_value = "test-uuid-123"
+    tracker.track(event)
+    assert payload["eid"] == "test-uuid-123"
+
+# ❌ Don't rely on random UUIDs
+event_id = tracker.get_uuid()  # Different each run
+```
+
+## Unit Test Patterns
+
+### Payload Testing
+```python
+# ✅ Test payload field presence and values
+def test_payload_construction():
+    payload = Payload()
+    payload.add("e", "pv")
+    payload.add("url", "https://test.com")
+    
+    result = payload.get()
+    assert result["e"] == "pv"
+    assert result["url"] == "https://test.com"
+
+# ✅ Test JSON encoding
+def test_payload_json_encoding():
+    payload.add_json({"key": "value"}, True, "cx", "co")
+    assert "cx" in payload.get()  # Base64 encoded
+```
+
+### Event Testing
+```python
+# ✅ Test event construction with all parameters
+def test_page_view_complete():
+    context = SelfDescribingJson(schema, data)
+    subject = Subject()
+    
+    event = PageView(
+        page_url="https://test.com",
+        page_title="Test",
+        context=[context],
+        event_subject=subject,
+        true_timestamp=1234567890
+    )
+    
+    assert event.page_url == "https://test.com"
+    assert len(event.context) == 1
+
+# ❌ Don't test internal implementation details
+def test_private_methods():
+    event._internal_method()  # Testing private methods
+```
+
+### Emitter Testing
+```python
+# ✅ Mock HTTP requests for emitter tests
+@mock.patch('requests.post')
+def test_emitter_sends_events(mock_post):
+    mock_post.return_value.status_code = 200
+    
+    emitter = Emitter("https://collector.test")
+    emitter.input({"e": "pv"})
+    emitter.flush()
+    
+    mock_post.assert_called_once()
+
+# ✅ Test retry logic
+def test_emitter_retry_on_failure(mock_post):
+    mock_post.return_value.status_code = 500
+    emitter.custom_retry_codes = {500: True}
+    # Verify retry behavior
+```
+
+### Contract Validation Testing
+```python
+# ✅ Test validation rules
+def test_non_empty_string_validation():
+    with self.assertRaises(ValueError):
+        non_empty_string("")
+    
+    non_empty_string("valid")  # Should not raise
+
+# ✅ Test form element validation
+def test_form_element_contract():
+    valid_element = {
+        "name": "field1",
+        "value": "test",
+        "nodeName": "INPUT",
+        "type": "text"
+    }
+    form_element(valid_element)  # Should not raise
+```
+
+## Integration Test Patterns
+
+### Mock Collector Pattern
+```python
+# ✅ Use micro mock collector for integration tests
+from http.server import HTTPServer, BaseHTTPRequestHandler
+
+class MockCollector(BaseHTTPRequestHandler):
+    def do_POST(self):
+        # Capture and validate payload
+        content_length = int(self.headers['Content-Length'])
+        post_data = self.rfile.read(content_length)
+        # Store for assertions
+        self.send_response(200)
+
+# Start mock collector in test
+server = HTTPServer(('localhost', 9090), MockCollector)
+```
+
+### End-to-End Testing
+```python
+# ✅ Test complete tracking flow
+def test_end_to_end_tracking():
+    tracker = Snowplow.create_tracker(
+        namespace="test",
+        endpoint="http://localhost:9090"
+    )
+    
+    # Track multiple events
+    tracker.track(PageView(page_url="test1.com"))
+    tracker.track(StructuredEvent("cat", "act"))
+    tracker.flush()
+    
+    # Verify collector received both events
+    assert len(received_events) == 2
+```
+
+## Testing Best Practices
+
+### Test Isolation
+```python
+# ✅ Clean up after each test
+def setUp(self):
+    Snowplow.reset()  # Clear all trackers
+
+def tearDown(self):
+    # Clean up any test artifacts
+    if hasattr(self, 'server'):
+        self.server.shutdown()
+
+# ❌ Don't leave state between tests
+class TestSuite:
+    shared_tracker = Tracker(...)  # Shared state!
+```
+
+### Assertion Patterns
+```python
+# ✅ Use specific assertions
+assert event.page_url == "https://expected.com"
+assert "e" in payload.get()
+mock_func.assert_called_with(expected_arg)
+
+# ❌ Avoid generic assertions
+assert event  # Too vague
+assert payload.get()  # What are we checking?
+```
+
+### Mock Management
+```python
+# ✅ Use patch decorators or context managers
+@mock.patch('snowplow_tracker.tracker.uuid.uuid4')
+def test_with_mock(mock_uuid):
+    mock_uuid.return_value = "test-id"
+
+# ✅ Clean up patches
+def create_patch(self, name):
+    patcher = mock.patch(name)
+    thing = patcher.start()
+    self.addCleanup(patcher.stop)
+    return thing
+```
+
+## Common Test Scenarios
+
+### Testing Event Contexts
+```python
+# ✅ Test context encoding and attachment
+def test_event_with_multiple_contexts():
+    contexts = [
+        SelfDescribingJson(schema1, data1),
+        SelfDescribingJson(schema2, data2)
+    ]
+    event = PageView(page_url="test", context=contexts)
+    
+    payload = event.build_payload(True, None, None)
+    cx_data = json.loads(base64.b64decode(payload.get()["cx"]))
+    assert len(cx_data["data"]) == 2
+```
+
+### Testing Failure Scenarios
+```python
+# ✅ Test failure callbacks
+def test_emitter_failure_callback():
+    failed_events = []
+    
+    def on_failure(count, events):
+        failed_events.extend(events)
+    
+    emitter = Emitter(
+        "https://invalid.collector",
+        on_failure=on_failure
+    )
+    # Trigger failure and verify callback
+```
+
+### Testing Async Behavior
+```python
+# ✅ Test async emitter threading
+def test_async_emitter():
+    emitter = AsyncEmitter("https://collector.test")
+    
+    # Track events
+    for i in range(100):
+        emitter.input({"e": "pv", "url": f"test{i}.com"})
+    
+    # Wait for flush
+    emitter.flush()
+    time.sleep(1)  # Allow async processing
+    
+    # Verify all events sent
+```
+
+## Test Utilities
+
+### Helper Functions
+```python
+# ✅ Create reusable test helpers
+def create_test_tracker(namespace="test"):
+    emitter = mock.MagicMock()
+    return Tracker(namespace, emitter)
+
+def create_test_event():
+    return PageView(page_url="https://test.com")
+
+# ❌ Don't duplicate test setup
+def test_one():
+    emitter = mock.MagicMock()
+    tracker = Tracker("test", emitter)
+    # ... repeated in every test
+```
+
+## Performance Testing
+
+### Load Testing Pattern
+```python
+# ✅ Test tracker under load
+def test_high_volume_tracking():
+    tracker = create_test_tracker()
+    
+    start = time.time()
+    for i in range(10000):
+        tracker.track(PageView(page_url=f"test{i}.com"))
+    
+    duration = time.time() - start
+    assert duration < 5.0  # Performance threshold
+```
+
+## Quick Reference
+
+### Test File Naming
+- Unit tests: `test_<component>.py`
+- Integration tests: `test_integration_<feature>.py`
+- Test classes: `Test<Component>`
+- Test methods: `test_<scenario>`
+
+### Essential Test Imports
+```python
+import unittest
+import unittest.mock as mock
+from freezegun import freeze_time
+from snowplow_tracker.contracts import ContractsDisabled
+```
+
+### Common Mock Targets
+- `snowplow_tracker.tracker.Tracker.get_uuid`
+- `requests.post` / `requests.get`
+- `time.time`
+- `snowplow_tracker.emitters.Emitter.sync_flush`
+
+## Contributing to test/CLAUDE.md
+
+When adding or modifying tests:
+
+1. **Maintain test isolation** - Each test should be independent
+2. **Mock external dependencies** - No real network calls in unit tests
+3. **Use descriptive test names** - Clear what is being tested
+4. **Test both success and failure paths** - Include edge cases
+5. **Keep tests fast** - Mock time-consuming operations
+6. **Document complex test scenarios** - Add comments for clarity
\ No newline at end of file