Repository navigation
[Q2-P1] Add contract tests to validate API assumptions #25
Description
Problem
SDK makes assumptions about API:
- Endpoints exist
- Response format matches expectations
- Field names are correct
Risk: Backend changes can break SDK
Solution
Add contract tests that validate SDK assumptions against API:
# tests/contract/test_api_contracts.py
class TestHistoricalEndpointContract:
"""Validate historical endpoint contract."""
def test_past_year_endpoint_exists(self):
response = requests.get(f'{API_URL}/v1/prices/past_year')
assert response.status_code != 404
def test_response_schema_matches_sdk(self):
response = requests.get(
f'{API_URL}/v1/prices/past_year',
params={'commodity': 'WTI_USD'},
headers={'Authorization': f'Token {TEST_KEY}'}
)
data = response.json()
# Validate structure
assert 'data' in data
assert 'prices' in data['data']
# Validate price schema
price = data['data']['prices'][0]
assert 'code' in price
assert 'price' in price
assert 'created_at' in price
assert 'type' in price
assert 'unit' in price
def test_pagination_schema(self):
response = requests.get(
f'{API_URL}/v1/prices/past_year',
params={'commodity': 'WTI_USD', 'page': 1, 'per_page': 10}
)
data = response.json()
# Validate pagination metadata
assert 'meta' in data
assert 'page' in data['meta']
assert 'per_page' in data['meta']
assert 'total' in data['meta']
assert 'has_next' in data['meta']Run on Backend Deploys
# In oilpriceapi-api repo: .github/workflows/deploy.yml
jobs:
deploy:
steps:
- name: Deploy to production
run: ...
- name: Run SDK contract tests
run: |
# Clone SDK repo
git clone https://github.com/OilpriceAPI/python-sdk.git
cd python-sdk
# Run contract tests against deployed API
pytest tests/contract/ --api-url=https://api.oilpriceapi.com
- name: Create issue if contract broken
if: failure()
run: |
gh issue create \
--title "SDK Contract Broken by Backend Deploy" \
--label "bug,priority: critical"Acceptance Criteria
- Contract test suite created
- Tests validate all SDK assumptions
- Tests run on backend deploys
- Failures create GitHub issues automatically
- Documentation for maintaining contracts
Estimated Effort
Time: 4 hours
Activity
coderabbitai commentedon Dec 17, 2025
📝 CodeRabbit Plan Mode
Generate an implementation plan and prompts that you can use with your favorite coding agent.
Examples
🔗 Similar Issues
Possible Duplicates
Related Issues
👤 Suggested Assignees
🧪 Issue enrichment is currently in open beta.
To disable automatic issue enrichment, add the following to your
.coderabbit.yaml:💬 Have feedback or questions? Drop into our discord or schedule a call!
feat: Complete Q1 & Q2 QA improvements (#20-28)
feat: Complete Q1 & Q2 QA improvements (#20-28)
karlwaldman commentedon Jul 13, 2026
Closing as complete — contract tests exist and run on a schedule:
tests/contract/test_api_contract.py(~22 tests): response formats, field types, commodity-code format, chronological ordering, pagination metadata, error formats — the exact checks this issue sketchedtests/contract/README.md+tests/contract/conftest.py.github/workflows/weekly-health.yml(pytest -m contract)Proof they work: they caught a real contract change — unknown commodity codes now return HTTP 400
invalid_codeinstead of 404. The two affected tests are updated to the current contract in PR #53.