qa-skills 3.0.0

package/skills/qa-httpx-writer/references/best-practices.md

@@ -0,0 +1,140 @@
+# Python API Testing Best Practices
+
+## Async vs Sync
+
+| Use Case | Recommendation |
+| -------- | -------------- |
+| **Most API tests** | Sync `httpx.Client` — simpler, sufficient for typical CRUD |
+| **High concurrency** | Async `httpx.AsyncClient` — when testing many parallel requests |
+| **Async app under test** | Async client — matches async handlers |
+| **Mixed codebase** | Prefer sync unless async is required |
+
+### When to Use Async
+
+- Testing endpoints that benefit from concurrent requests
+- Matching async application architecture
+- Performance benchmarks with many simultaneous calls
+
+### Sync Simplicity
+
+```python
+# Prefer sync for straightforward tests
+def test_get_users(client, base_url):
+    response = client.get(f"{base_url}/users")
+    assert response.status_code == 200
+```
+
+## Session Reuse
+
+| Scope | Pros | Cons |
+| ----- | ---- | ---- |
+| **Function** | Isolated; no shared state | New connection per test |
+| **Module** | Fewer connections | Shared state across tests in module |
+| **Session** | Fastest; single connection pool | Must avoid mutating shared state |
+
+**Recommendation:** Use function-scoped client by default. Use session scope only when tests are read-only and do not mutate server state.
+
+## Schema Validation
+
+1. **Use Pydantic when** — OpenAPI contract exists; response shape is well-defined
+2. **Use JSON Schema when** — Contract is in JSON Schema format; no Pydantic in project
+3. **Use manual assertions when** — Only a few fields matter; full schema is overkill
+
+### Contract-Driven
+
+```python
+# From qa-api-contract-curator OpenAPI spec
+class UserResponse(BaseModel):
+    id: int
+    email: EmailStr
+    name: str | None = None
+
+def test_user_matches_contract(client, base_url, auth_headers):
+    response = client.get(f"{base_url}/users/1", headers=auth_headers)
+    UserResponse.model_validate(response.json())  # Fails if contract violated
+```
+
+## Test Isolation
+
+1. **Independent tests** — Each test passes regardless of order
+2. **No shared mutable state** — Avoid global variables; use fixtures
+3. **Clean data** — Create/delete test data per test or use unique identifiers
+4. **Idempotent when possible** — GET requests are safe; POST may create duplicates — use unique emails, UUIDs
+
+### Unique Test Data
+
+```python
+import uuid
+
+def test_create_user_unique(client, base_url, auth_headers):
+    email = f"test-{uuid.uuid4().hex}@example.com"
+    response = client.post(
+        f"{base_url}/users",
+        json={"email": email, "name": "Test"},
+        headers=auth_headers
+    )
+    assert response.status_code == 201
+```
+
+## Error Scenarios
+
+Cover at least:
+
+| Scenario | Status | Assertion |
+| -------- | ------ | --------- |
+| Success | 200/201/204 | Per contract |
+| Validation error | 400 | Error payload structure |
+| Unauthorized | 401 | When missing/invalid auth |
+| Forbidden | 403 | Insufficient permissions |
+| Not found | 404 | Missing resource |
+| Conflict | 409 | Duplicate, constraint violation |
+
+## Avoid
+
+1. **Hardcoded secrets** — Use `os.environ` or pytest fixtures
+2. **Fragile assertions** — Prefer partial match for dynamic fields (id, createdAt)
+3. **Sleep/timeout for flakiness** — Use retries or deterministic data instead
+4. **Testing implementation** — Test behavior and contract, not internal routes
+5. **Large fixtures** — Minimize payload size; use factories for scale
+6. **External services in unit tests** — Mock third-party APIs; use real API only in integration tests
+
+## File Organization
+
+```
+tests/
+  conftest.py              # base_url, client, auth
+  api/
+    conftest.py            # auth_headers, token
+    test_users_api.py
+    test_products_api.py
+  unit/                    # Mocked API calls
+    test_services.py
+```
+
+## Parallel Execution
+
+When using `pytest-xdist`:
+
+- Use unique data (UUIDs, timestamps) to avoid collisions
+- Or run API tests sequentially: `pytest -m api --forked` or single worker
+- Consider separate DB/schema per worker for integration tests
+
+## Dependencies
+
+```toml
+# pyproject.toml
+[project.optional-dependencies]
+test = [
+    "httpx>=0.24.0",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21.0",
+    "pydantic>=2.0",
+]
+```
+
+## Contract-Driven Workflow
+
+1. **Get OpenAPI** — From qa-api-contract-curator
+2. **Generate Pydantic models** — From `components.schemas` (or use datamodel-code-generator)
+3. **Generate tests** — One test per operation × status code
+4. **Validate responses** — `Model.model_validate(response.json())`

package/skills/qa-httpx-writer/references/config.md

@@ -0,0 +1,212 @@
+# httpx Test Configuration
+
+## conftest.py Structure
+
+```python
+# tests/conftest.py
+import os
+import pytest
+import httpx
+
+
+@pytest.fixture
+def base_url():
+    return os.environ.get("API_BASE_URL", "http://localhost:8000")
+
+
+@pytest.fixture
+def client(base_url):
+    """Sync client; use for non-async tests."""
+    with httpx.Client(
+        base_url=base_url,
+        timeout=30.0,
+        follow_redirects=True,
+    ) as c:
+        yield c
+
+
+@pytest.fixture
+async def async_client(base_url):
+    """Async client; use with @pytest.mark.asyncio."""
+    async with httpx.AsyncClient(
+        base_url=base_url,
+        timeout=30.0,
+        follow_redirects=True,
+    ) as c:
+        yield c
+```
+
+## Base URL Management
+
+### Environment Variable
+
+```python
+# .env.test or pytest.ini
+# API_BASE_URL=https://api.staging.example.com
+
+@pytest.fixture
+def base_url():
+    url = os.environ.get("API_BASE_URL")
+    if not url:
+        pytest.skip("API_BASE_URL not set")
+    return url
+```
+
+### Per-Environment
+
+```python
+@pytest.fixture
+def base_url():
+    env = os.environ.get("TEST_ENV", "local")
+    urls = {
+        "local": "http://localhost:8000",
+        "staging": "https://api.staging.example.com",
+        "integration": "https://api.integration.example.com",
+    }
+    return urls.get(env, urls["local"])
+```
+
+## Client Fixtures
+
+### Function-Scoped (Default)
+
+```python
+@pytest.fixture
+def client(base_url):
+    with httpx.Client(base_url=base_url) as c:
+        yield c
+# New client per test; no shared state
+```
+
+### Session-Scoped (Connection Reuse)
+
+```python
+@pytest.fixture(scope="session")
+def client(base_url):
+    with httpx.Client(base_url=base_url) as c:
+        yield c
+# Reuse connection across tests; faster but shared state
+```
+
+### With Custom Headers
+
+```python
+@pytest.fixture
+def client(base_url, default_headers):
+    with httpx.Client(
+        base_url=base_url,
+        headers=default_headers,
+    ) as c:
+        yield c
+
+@pytest.fixture
+def default_headers():
+    return {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "qa-httpx-tests/1.0",
+    }
+```
+
+## Auth Fixtures
+
+```python
+@pytest.fixture
+def token(client, base_url):
+    response = client.post(
+        f"{base_url}/auth/login",
+        json={
+            "email": os.environ.get("TEST_USER_EMAIL", "test@example.com"),
+            "password": os.environ.get("TEST_USER_PASSWORD", "test"),
+        },
+    )
+    assert response.status_code == 200
+    return response.json()["token"]
+
+
+@pytest.fixture
+def auth_headers(token):
+    return {"Authorization": f"Bearer {token}"}
+
+
+@pytest.fixture
+def auth_client(client, auth_headers):
+    client.headers.update(auth_headers)
+    return client
+```
+
+## pytest-asyncio Configuration
+
+### pyproject.toml
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+```
+
+### pytest.ini
+
+```ini
+[pytest]
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function
+```
+
+## Timeout and Retry
+
+```python
+from httpx import Timeout, Limits
+
+@pytest.fixture
+def client(base_url):
+    with httpx.Client(
+        base_url=base_url,
+        timeout=Timeout(60.0),
+        limits=Limits(max_keepalive_connections=5, max_connections=10),
+    ) as c:
+        yield c
+```
+
+## Markers for API Tests
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "api: marks tests as API integration tests",
+    "slow: marks tests as slow (network-dependent)",
+]
+```
+
+```python
+@pytest.mark.api
+def test_users_endpoint(client, base_url):
+    response = client.get(f"{base_url}/users")
+    assert response.status_code == 200
+```
+
+## Directory Layout
+
+```
+tests/
+  conftest.py           # Shared fixtures
+  api/
+    conftest.py         # API-specific fixtures (auth, etc.)
+    test_users_api.py
+    test_products_api.py
+    test_auth_api.py
+  fixtures/
+    sample_users.json
+```
+
+## Environment Config
+
+```python
+# tests/conftest.py
+def pytest_configure(config):
+    os.environ.setdefault("TESTING", "1")
+    if "API_BASE_URL" not in os.environ:
+        os.environ["API_BASE_URL"] = "http://localhost:8000"
+```

package/skills/qa-httpx-writer/references/patterns.md

@@ -0,0 +1,262 @@
+# httpx API Test Patterns
+
+## Sync Client (httpx.Client)
+
+```python
+import httpx
+
+def test_get_users():
+    with httpx.Client(base_url="https://api.example.com") as client:
+        response = client.get("/users")
+        assert response.status_code == 200
+        data = response.json()
+        assert "users" in data
+        assert isinstance(data["users"], list)
+```
+
+## Async Client (httpx.AsyncClient)
+
+```python
+import httpx
+import pytest
+
+@pytest.mark.asyncio
+async def test_get_users_async():
+    async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+        response = await client.get("/users")
+        assert response.status_code == 200
+        data = response.json()
+        assert "users" in data
+```
+
+## CRUD Endpoints
+
+### GET (List)
+
+```python
+def test_get_users_list(client, base_url):
+    response = client.get(f"{base_url}/users")
+    assert response.status_code == 200
+    assert "application/json" in response.headers.get("content-type", "")
+    data = response.json()
+    assert isinstance(data.get("users"), list)
+
+def test_get_users_unauthorized(client, base_url):
+    response = client.get(f"{base_url}/users")  # No auth
+    assert response.status_code == 401
+```
+
+### GET (Single)
+
+```python
+def test_get_user_by_id(client, base_url, auth_headers):
+    response = client.get(f"{base_url}/users/1", headers=auth_headers)
+    assert response.status_code == 200
+    user = response.json()
+    assert user["id"] == 1
+    assert "email" in user
+
+def test_get_user_not_found(client, base_url, auth_headers):
+    response = client.get(f"{base_url}/users/99999", headers=auth_headers)
+    assert response.status_code == 404
+```
+
+### POST (Create)
+
+```python
+def test_create_user(client, base_url, auth_headers):
+    payload = {"email": "test@example.com", "name": "Test User"}
+    response = client.post(f"{base_url}/users", json=payload, headers=auth_headers)
+    assert response.status_code == 201
+    user = response.json()
+    assert "id" in user
+    assert user["email"] == "test@example.com"
+
+def test_create_user_validation_error(client, base_url, auth_headers):
+    response = client.post(
+        f"{base_url}/users",
+        json={"email": "invalid"},
+        headers=auth_headers
+    )
+    assert response.status_code == 400
+    errors = response.json()
+    assert "errors" in errors or "message" in errors
+```
+
+### PUT/PATCH (Update)
+
+```python
+def test_update_user(client, base_url, auth_headers):
+    response = client.put(
+        f"{base_url}/users/1",
+        json={"name": "Updated Name"},
+        headers=auth_headers
+    )
+    assert response.status_code == 200
+    user = response.json()
+    assert user["name"] == "Updated Name"
+```
+
+### DELETE
+
+```python
+def test_delete_user(client, base_url, auth_headers):
+    response = client.delete(f"{base_url}/users/1", headers=auth_headers)
+    assert response.status_code == 204
+    assert response.content == b""
+
+def test_delete_user_not_found(client, base_url, auth_headers):
+    response = client.delete(f"{base_url}/users/99999", headers=auth_headers)
+    assert response.status_code == 404
+```
+
+## Authentication
+
+### Bearer Token
+
+```python
+@pytest.fixture
+def auth_headers(token):
+    return {"Authorization": f"Bearer {token}"}
+
+@pytest.fixture
+def token(client, base_url):
+    response = client.post(
+        f"{base_url}/auth/login",
+        json={"email": "test@example.com", "password": "secret"}
+    )
+    assert response.status_code == 200
+    return response.json()["token"]
+
+def test_protected_route(client, base_url, auth_headers):
+    response = client.get(f"{base_url}/users", headers=auth_headers)
+    assert response.status_code == 200
+```
+
+### API Key
+
+```python
+@pytest.fixture
+def api_key_headers():
+    return {"X-API-Key": os.environ.get("TEST_API_KEY", "test-key")}
+
+def test_with_api_key(client, base_url, api_key_headers):
+    response = client.get(f"{base_url}/api/data", headers=api_key_headers)
+    assert response.status_code == 200
+```
+
+### Basic Auth
+
+```python
+def test_basic_auth(client, base_url):
+    auth = httpx.BasicAuth("user", "password")
+    response = client.get(f"{base_url}/admin", auth=auth)
+    assert response.status_code == 200
+```
+
+### OAuth2
+
+```python
+# Manual token flow
+def test_oauth2_protected(client, base_url, oauth_token):
+    response = client.get(
+        f"{base_url}/protected",
+        headers={"Authorization": f"Bearer {oauth_token}"}
+    )
+    assert response.status_code == 200
+```
+
+### Cookies (Session)
+
+```python
+def test_session_cookies(client, base_url):
+    # Login to set cookies
+    client.post(
+        f"{base_url}/auth/login",
+        json={"email": "test@example.com", "password": "secret"}
+    )
+    # Subsequent request uses session cookies
+    response = client.get(f"{base_url}/users")
+    assert response.status_code == 200
+```
+
+## File Upload
+
+```python
+def test_file_upload(client, base_url, auth_headers, tmp_path):
+    file_path = tmp_path / "sample.pdf"
+    file_path.write_bytes(b"%PDF-1.4 fake content")
+
+    with open(file_path, "rb") as f:
+        files = {"file": ("sample.pdf", f, "application/pdf")}
+        response = client.post(
+            f"{base_url}/upload",
+            files=files,
+            headers=auth_headers
+        )
+
+    assert response.status_code == 201
+    data = response.json()
+    assert "url" in data or "id" in data
+```
+
+## Streaming
+
+```python
+def test_streaming_response(client, base_url):
+    with client.stream("GET", f"{base_url}/stream") as response:
+        assert response.status_code == 200
+        chunks = []
+        for chunk in response.iter_bytes():
+            chunks.append(chunk)
+        assert len(chunks) > 0
+```
+
+## Query Parameters
+
+```python
+def test_query_params(client, base_url):
+    response = client.get(
+        f"{base_url}/search",
+        params={"q": "test", "limit": 5}
+    )
+    assert response.status_code == 200
+    # URL: /search?q=test&limit=5
+```
+
+## Retry Logic
+
+```python
+from httpx import Limits, Timeout
+
+@pytest.fixture
+def client_with_retry(base_url):
+    transport = httpx.HTTPTransport(retries=3)
+    with httpx.Client(
+        base_url=base_url,
+        transport=transport,
+        timeout=Timeout(30.0)
+    ) as client:
+        yield client
+```
+
+## requests Fallback
+
+When httpx is not available, use requests with similar patterns:
+
+```python
+import requests
+
+def test_with_requests(base_url):
+    response = requests.get(f"{base_url}/users")
+    assert response.status_code == 200
+    data = response.json()
+    assert "users" in data
+
+# Session for connection reuse
+def test_with_session(base_url):
+    with requests.Session() as session:
+        session.headers.update({"Authorization": f"Bearer {token}"})
+        response = session.get(f"{base_url}/users")
+        assert response.status_code == 200
+```