# Specification Tests

Protocol compliance verification and API surface change detection.

## Purpose

- Verify public API matches documented specifications
- Detect unintended API surface changes
- Validate method signatures and type hints
- Ensure protocol compliance

## Running

```bash
uv run pytest tests/specification/
```

## Test Types

### Protocol Compliance

Verify that classes implement required protocols correctly:

```python
def test_client_implements_protocol():
    """Verify Pinecone client implements ClientProtocol."""
    assert isinstance(Pinecone, ClientProtocol)
```

### API Surface Detection

Detect changes to public API:

```python
def test_public_methods():
    """Verify expected public methods exist."""
    expected_methods = {"list_indexes", "create_index", "delete_index"}
    actual_methods = {m for m in dir(Pinecone) if not m.startswith("_")}
    assert expected_methods <= actual_methods
```

### Signature Validation

Validate method signatures match specifications:

```python
import inspect

def test_create_index_signature():
    """Verify create_index has expected parameters."""
    sig = inspect.signature(Pinecone.create_index)
    params = list(sig.parameters.keys())
    assert "name" in params
    assert "dimension" in params
```

## When to Update

Update specification tests when:

- Adding new public methods
- Changing method signatures
- Modifying protocol requirements
- Deprecating or removing APIs

Specification test failures indicate potential breaking changes that need documentation.
