qa-skills 3.0.0 → 3.1.0

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

@@ -1,140 +0,0 @@
-# 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

@@ -1,212 +0,0 @@
-# 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

@@ -1,262 +0,0 @@
-# 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
-```