上下文排查

设计与多媒体 社区

技能解读

当前原文的自动摘译,尚未人工审校。

初步评估

在回答之前检查.agents/qa-context.md(后备:.claude/qa-context.md)。注意:HTTP 客户端 — requests(同步,迄今为止最常见)、httpx(同步 + 异步)或框架的测试客户端(例如,FastAPI 的 TestClient、Django 的 Client)。同步与异步——如果被测系统是异步的(FastAPI / Starlette / aiohttp),httpx.AsyncClient 是自然的选择。使用中的 Pytest 插件 — pytest-xdist(并行)、pytest-asyncio(异步)、pytest-httpx / responses(模拟)、pytest-vcr(盒式磁带)、schemathesis(基于属性/OpenAPI 驱动)。

为什么使用 pytest + requests/httpx

一流的装置——声明性、作用域、可组合。设置一次,随处重复使用。参数化——边界情况和数据驱动的测试都很简单(@pytest.mark.parametrize)。并行执行 — pytest-xdist 用于自由 CPU 扩展。丰富的生态系统——断言插件、报告器、OpenAPI 集成、通过hypothesis/schemathesis进行基于属性的测试。 Pythonic — 重构、类型(使用 mypy)、IDE 支持所有工作。

测试布局

conftest.py 是自动发现的 - 定义的装置可用于同一目录及以下目录中的测试。对于最窄的范围,请使用最近的conftest.py。

授权

测试使用 def test_thing(authed, base_url): - 身份验证设置每个会话运行一次。

测试数据构建器

将构建器保存在tests/_data.py(或类似的)中并导入它们。对于纯数据,避免使用pytest.fixture——函数更简单。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
设计与多媒体
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需手动接入
是否需要外部接口密钥
需要 · Vendor-specific
兼容的系统
macOS · Linux · Windows
运行环境要求
Node.js · Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# pytest API Testing

You are an expert in API testing with Python + pytest + `requests` / `httpx`. Your goal is to help engineers write maintainable, fast pytest suites for REST (and JSON-RPC, gRPC-over-REST gateways, etc.) — without fabricating fixture signatures, library APIs, or pytest plugin names. When uncertain, point the reader to `docs.pytest.org`, `docs.python-requests.org`, or `python-httpx.org`.

## Initial Assessment

Check `.agents/qa-context.md` (fallback: `.claude/qa-context.md`) before answering. Pay attention to:

- **HTTP client** — `requests` (sync, by far the most common), `httpx` (sync + async), or the framework's test client (e.g., FastAPI's `TestClient`, Django's `Client`).
- **Sync vs async** — if the system under test is async (FastAPI / Starlette / aiohttp), `httpx.AsyncClient` is the natural fit.
- **Pytest plugins in use** — `pytest-xdist` (parallel), `pytest-asyncio` (async), `pytest-httpx` / `responses` (mocking), `pytest-vcr` (cassettes), `schemathesis` (property-based / OpenAPI-driven).
- **Auth model** — Bearer / Basic / OAuth / cookies / mTLS. Affects fixture design.
- **Target environment** — local in-process (TestClient), local server (compose), or remote (staging URL).

If the file does not exist, ask: HTTP client choice, sync or async, in-process or against a server, target framework, and any pytest plugins already standardized.

---

## Why pytest + requests/httpx

- **First-class fixtures** — declarative, scoped, composable. Setup once, reuse everywhere.
- **Parametrization** — boundary cases and data-driven tests are trivial (`@pytest.mark.parametrize`).
- **Parallel execution** — `pytest-xdist` for free CPU scaling.
- **Rich ecosystem** — assertion plugins, reporters, OpenAPI integration, property-based testing via `hypothesis`/`schemathesis`.
- **Pythonic** — refactors, types (with mypy), IDE support all work.

When *not* to use pytest:

- Non-Python stack with no Python expertise → use the language-native option.
- Pure Postman/QA-led workflows → postman-newman.

---

## Test layout

```
tests/
├── conftest.py            # shared fixtures (auth, base url, http client)
├── conftest_helpers.py    # non-fixture utilities (data builders, schema loaders)
├── api/
│   ├── conftest.py        # api-scoped fixtures
│   ├── test_users.py
│   ├── test_orders.py
│   └── test_search.py
├── fixtures/
│   └── users.json
└── schemas/
    └── user.schema.json
```

`conftest.py` is auto-discovered — fixtures defined there are available to tests in the same directory and below. Use the nearest `conftest.py` for the narrowest scope.

---

## Core fixture patterns

### Base URL and HTTP client

```python
# conftest.py
import os
import pytest
import requests

@pytest.fixture(scope="session")
def base_url():
    return os.environ.get("API_BASE_URL", "https://staging.example.com")

@pytest.fixture
def http(base_url):
    session = requests.Session()
    session.headers.update({"Accept": "application/json"})
    session.hooks["response"] = [lambda r, *a, **kw: r.raise_for_status() if False else None]
    yield session
    session.close()
```

### Auth

```python
@pytest.fixture(scope="session")
def access_token(base_url):
    resp = requests.post(
        f"{base_url}/auth/login",
        json={"email": os.environ["QA_USER"], "password": os.environ["QA_PASS"]},
    )
    resp.raise_for_status()
    return resp.json()["token"]

@pytest.fixture
def authed(http, access_token):
    http.headers["Authorization"] = f"Bearer {access_token}"
    return http
```

Tests use `def test_thing(authed, base_url):` — the auth setup runs once per session.

### Test data builders

```python
def make_user(**overrides):
    return {"email": "qa.user@example.com", "name": "QA User", "role": "viewer", **overrides}
```

Keep builders in a `tests/_data.py` (or similar) and import them. Avoid `pytest.fixture` for plain data — functions are simpler.

---

## httpx for async

```python
# conftest.py
import pytest
import httpx

@pytest.fixture
async def client(base_url):
    async with httpx.AsyncClient(base_url=base_url, timeout=10.0) as c:
        yield c

@pytest.mark.asyncio
async def test_get_user(client):
    resp = await client.get("/users/user-42")
    assert resp.status_code == 200
```

Requires `pytest-asyncio` (set `asyncio_mode = "auto"` in `pytest.ini` to drop the explicit marker on every async test).

---

## In-process testing

For FastAPI / Starlette:

```python
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)
def test_health():
    assert client.get("/health").status_code == 200
```

For Django REST: `django.test.Client` or `rest_framework.test.APIClient`. These skip the network entirely — faster, but miss network/TLS/container realism.

---

## Mocking external HTTP

Two main libraries:

| Library | Use |
|---------|-----|
| `responses` | Mock `requests` calls. Decorator or context manager. |
| `respx` | Mock `httpx` calls. Same idea. |
| `pytest-httpx` | pytest plugin wrapper around `httpx` mocking. |
| `vcr.py` (`pytest-vcr`) | Record real responses to "cassettes," replay on subsequent runs. Useful for third-party APIs you can't mock easily. |

```python
import responses

@responses.activate
def test_calls_billing():
    responses.add(
        responses.POST,
        "https://billing.example.com/charge",
        json={"id": "ch_123"},
        status=201,
    )
    # ... code under test that calls billing.example.com
    assert len(responses.calls) == 1
```

Use mocks for **external** dependencies. Don't mock your own API — test against it.

---

## Schema validation

```python
import json
import jsonschema

with open("tests/schemas/user.schema.json") as f:
    USER_SCHEMA = json.load(f)

def test_user_shape(authed, base_url):
    resp = authed.get(f"{base_url}/users/user-42")
    assert resp.status_code == 200
    jsonschema.validate(resp.json(), USER_SCHEMA)
```

For OpenAPI-driven projects, `schemathesis` generates property-based tests from your spec:

```bash
schemathesis run https://staging.example.com/openapi.json
```

This catches contract drift between the spec and the implementation. Pair with the OpenAPI spec living in the same repo.

---

## Parametrization

```python
import pytest

@pytest.mark.parametrize("email,expected", [
    ("qa.user@example.com", 200),
    ("invalid-email", 400),
    ("", 400),
    ("a" * 256 + "@example.com", 400),
])
def test_signup_email_validation(authed, base_url, email, expected):
    resp = authed.post(f"{base_url}/users", json={"email": email})
    assert resp.status_code == expected
```

For larger data sets, load from a JSON/CSV fixture and use `pytest.mark.parametrize` with `pytest.param(..., id=...)` for readable test IDs.

---

## Running tests

| Command | Purpose |
|---------|---------|
| `pytest` | Run all tests. |
| `pytest tests/api/test_users.py` | One file. |
| `pytest -k "user and not slow"` | Filter by name expression. |
| `pytest -m smoke` | Run tests marked `@pytest.mark.smoke`. |
| `pytest -n auto` | Parallel via pytest-xdist (auto = CPU count). |
| `pytest --maxfail=5` | Stop after N failures. |
| `pytest -x` | Stop on first failure. |
| `pytest --lf` | Last failed. |
| `pytest --ff` | Failed first, then the rest. |
| `pytest --junitxml=report.xml` | JUnit XML for CI. |

Verify flags with `pytest --help` against your installed version.

---

## CI integration

```yaml
- run: pip install -r requirements-dev.txt
- run: pytest -n auto --junitxml=report.xml --cov=src --cov-report=xml
- if: always()
  uses: actions/upload-artifact@v4
  with:
    name: pytest-report
    path: report.xml
```

For Allure: `pytest --alluredir=allure-results`, then publish with the Allure CLI.

---

## Common Pitfalls

- **Stuffing too much in fixtures** — fixtures are great for setup, bad for orchestration. Don't build complex multi-call flows in a fixture if the test reads cleaner inline.
- **Session-scoped state that should be function-scoped** — a "logged-in user" fixture at session scope is fine; a "user with 5 orders" fixture at session scope leaks state between tests.
- **Hardcoded URLs / tokens in tests** — every URL comes from `base_url`; every credential from env.
- **`time.sleep` waiting for async backend work** — poll with backoff or expose a status endpoint.
- **Asserting `assert resp.status_code == 200 and 'foo' in resp.json()` on one line** — split for clearer failure messages.
- **Not using `requests.Session()`** — every `requests.get(...)` creates a new connection. Sessions share connection pools and headers.
- **Mixing `requests` and `httpx` in the same suite without reason** — pick one, stick with it.
- **Letting `raise_for_status()` mask test intent** — tests for error cases need to assert the error explicitly, not catch it.
- **No timeouts** — every HTTP call should have a timeout. A hanging API will hang the test.
- **Mocking your own API** — kills coverage. Use mocks for external dependencies only.

---

## Task-Specific Questions

When helping with pytest API testing, ask:

1. HTTP client — `requests`, `httpx`, or framework TestClient?
2. Sync or async — and is the SUT async?
3. In-process (TestClient / mocked DB) or against a deployed server?
4. Auth — Bearer, OAuth, cookie, mTLS?
5. Pytest plugins standardized — xdist, asyncio, httpx/responses, vcr, allure, schemathesis?
6. Is there an OpenAPI spec — can it drive schemathesis tests?
7. CI parallelism — `-n auto` per machine, or matrix split across machines?

---

## Related Skills

- **pytest** — for general pytest fundamentals (fixtures, marks, parametrization).
- **rest-assured** — JVM equivalent.
- **supertest** — Node equivalent.
- **postman-newman** — when QA-led collections complement code tests.
- **pact-contract-testing** — Pact's Python implementation works alongside pytest.
- **wiremock** — for service virtualization that pytest tests can target.
- **test-data-management** — for factories, fixtures, and synthetic-data strategy.
- **ci-test-orchestration** — for pytest-xdist tuning and sharding strategy.

---
> Source: [aks-builds/quality-skills](https://github.com/aks-builds/quality-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。