df-test-framework 4.8.0__tar.gz → 4.9.0__tar.gz

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/AGENTS.md

@@ -8,8 +8,8 @@ This file provides guidance to Codex (Codex.ai/code) when working with code in t
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.8.0
-- **更新时间**: 2026-08-10
+- **版本**: v4.9.0
+- **更新时间**: 2026-08-11
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/CHANGELOG.md

@@ -7,6 +7,106 @@
 
 ## [Unreleased]
 
+## [4.9.0] - 2026-08-11
+
+### ⚠️ 破坏性变更
+
+- **`NamingRegistry.case_match_patterns()` 对不可直接认领的规则改为抛错**。声明了
+  `joins_via` 或非 `Lifecycle.CASE` 的规则调用它会 `ValueError`。改用
+  `claimable_keys()` 遍历，或先用 `is_directly_claimable()` 判断。
+  `NamingRegistry` 在 v4.8.1 才引入，受影响面小，故未升 MAJOR。
+
+### 🐛 修复
+
+- **SM2 短私钥导致偶发失败**（`infrastructure/helpers/gmcrypto.py`）：`_normalize_private_key`
+  此前只接受恰好 32 字节的裸私钥。私钥本质是大整数，首字节为 0 时最短表示只有 31 字节，
+  实测 `gmalg.generate_keypair()` 约 **1/256** 的概率产出（3000 次采样中 8 次）。
+  现对 1~32 字节裸私钥左侧补零，空值与超长仍拒绝。
+  - 影响：v4.8.1 起任何自行生成密钥对的调用方都会周期性踩到，且失败与输入无关、难以复现。
+    框架自身的国密测试用 class 级 keypair fixture，一旦踩中整个测试类一起失败。
+
+- **`case_match_patterns()` 违背框架自己的契约**（`testing/data/naming.py`）：`NamingRule`
+  文档写明声明了 `joins_via` 的字段"只能跟父对象级联删除"，该方法却照样返回其宽匹配式，
+  把防误删的责任推给每个调用方。现在直接拒绝，并新增 `is_directly_claimable()`
+  与 `claimable_keys()` 表达这一语义。
+  - 判定同时覆盖生命周期：非 `Lifecycle.CASE` 的规则同样不可直接认领。此前 `lifecycle`
+    字段只是摆设 —— 合法的 `BASELINE` 规则会被 `case_match_patterns()` 当作用例级返回，
+    又被 `self_check()` 判成"会命中基准池前缀"，自相矛盾。
+
+### ✨ 新增
+
+- **`wait_until` / `async_wait_until` 轮询等待**（`testing/assertions/waiting.py`）：等异步结果落地的通用封装，
+  超时抛 `WaitTimeoutError`（继承 `AssertionError`，pytest 报成断言失败），消息带最后一次探测值
+  和探测次数。
+  - 动机：业务项目手写了 **52 个**形状相同的 `_wait_for_*`，每个都要重复 deadline、循环、间隔、
+    超时报错四件事。写 `time.sleep(5)` 只要一行、写轮询要十行，工具缺位直接导致盲等泛滥 ——
+    某个业务文件里一个 5 秒盲等被用了 7 次，占该文件 44 秒耗时中的 35 秒。
+  - `ready` 判定默认为 `bool`，覆盖最常见的"查到行就继续"；剩余时间不足一个间隔时按剩余时间睡，
+    不会睡过 `timeout`；探测函数自身抛错立即传播，不会被当成超时吞掉。
+  - 参数在入口校验：`timeout` 非负有限、`interval` 正有限。`NaN` 会让比较恒假从而死循环，
+    `inf` 让超时形同虚设，负 `interval` 要等到 `time.sleep` 才抛错、报错位置离病因很远。
+    `timeout=0` 合法，表示只探测一次。
+
+- **`assert_consistently` / `async_assert_consistently`**：否定断言的框架抽象 ——
+  在整个窗口内反复采样，要求条件**始终**成立。用于幂等（重推不产生新流水）、被拒后不落库、
+  MQ 重投不重复扣款；这类场景 `wait_until` 帮不上忙（条件一开始就成立，它立刻返回）。
+  比裸 `time.sleep(n)` 强在：能抓到"中途变了又变回来"、一旦破坏立即失败而非等满、
+  报错带第几次采样和当时的值。
+
+- **`like_to_regex(pattern, case_sensitive=...)`**：声明从"语义与 MySQL 一致"降级为
+  **词法近似**，并支持大小写开关。框架支持 MySQL / MSSQL / PostgreSQL / SQLite 四种方言，
+  而它们的 `LIKE` 并不等价：
+  - 大小写——MySQL 与 MSSQL 默认排序规则不敏感、SQLite 对 ASCII 不敏感、PostgreSQL 敏感；
+  - 字符类——MSSQL 的 `[abc]` 是字符类，其余三家当普通字符；
+  - 转义——`NO_BACKSLASH_ESCAPES` 与显式 `ESCAPE` 会改变转义符。
+
+  `self_check()` 因此改为按**最宽松口径过近似**（大小写不敏感），并检出模式中含 `[`、`]`
+  这类随方言改变含义的字符。安全检查里误报只是让人收紧模式，漏报会真删数据 ——
+  修复前的实测：模式 `AUTO_CASE_商品_%` 对值 `auto_case_商品_x` 自检判"安全"，
+  而 MySQL 默认排序规则下 `DELETE` 会命中。清理 SQL 仍应显式写 `ESCAPE` 并明确大小写语义。
+
+- **`cleanup_module` / `cleanup_session` fixture**：`cleanup` 之外新增 module 与 session 作用域，
+  三者构造逻辑同源，只在作用域上不同。
+  - 动机：`cleanup` 此前只有 function 级，而 pytest 规则下依赖它的前置 fixture 也只能是 function 级 ——
+    业务项目因此无法让同模块用例共享前置数据，每条用例都要把"供应商→通道→商品→客户"整条链
+    重建一遍。这是框架施加的硬约束，项目层绕不过去。
+  - 能否共享的判据是断言锚点：锚在自己的业务单据上可共享；锚在共享对象的总量或状态
+    （余额、可用库存、流水条数）上仍须用 function 级 `cleanup`。同一判据也决定用例能否并行。
+  - `@pytest.mark.keep_data` 是函数级标记，宽作用域下取不到；`--keep-test-data` 与
+    `KEEP_TEST_DATA` 配置照常生效。
+
+## [4.8.1] - 2026-08-11
+
+### ✨ 新增
+
+- **测试数据命名注册表 `NamingRegistry`**（`testing/data/naming.py`，从 master_test 项目下沉）：
+  把「生成名字」（`template`）、「认领名字」（`match` SQL LIKE 模式）、「字段上限」（`max_length`）
+  绑在同一条 `NamingRule` 里，生成端与兜底清理端读同一份定义，消除两端手抄漂移。
+  - `make(key, test_id, suffix)`：未登记的 key 抛 `KeyError`（逼迫新命名先登记），超长抛
+    `ValueError`（不静默截断）。
+  - `scoped(test_id, label)`：一条用例造多套前置数据时显式附加场景标签。宽字段（`{tid}` 模板）
+    把完整标签放在语义位（域标签之后、test_id 之前）；长度吃紧字段（`{sid}` 模板）让标签参与
+    短 id 哈希保证唯一，不占名字文本。标签限定 `[A-Za-z0-9_-]`，拒绝嵌套。
+  - `self_check(sample_test_id, protected_names=...)`：自洽校验（模板产出必能被自己的模式认领、
+    任何模式不许命中基准池前缀与保护名单、`joins_via` 指向已登记规则），项目单测一行断言即获持续保护。
+  - `short_id()`（哈希短 id）、`like_to_regex()`（MySQL LIKE 语义）、`Lifecycle`
+    （`AUTO_BASE` 基准池 / `AUTO_CASE` 用例级前缀约定）一并公开。
+  - 规则表由各项目自行登记，框架只提供机制。顶层导出 `NamingRegistry` / `NamingRule`。
+
+### 🔧 修复
+
+- **清理 pytest 10 将移除的弃用 API**（pytest 9.1 起告警）：
+  - `testing/fixtures/core.py`、`testing/plugins/env_plugin.py` 不再用 `config.inicfg` 做
+    「ini 项是否已注册」的守卫，改为直接 `config.getini()` 并捕获 `ValueError`。两个 ini 项
+    （`df_settings_class` / `df_plugins`）注册时默认值均为空串，`or` 优先级链行为不变。
+  - `core.py` 抽出私有 helper `_read_ini()`，两处调用点共用。
+
+### 🔧 依赖
+
+- 开发依赖整体升级：`pytest` 9.0.3 → 9.1.1、`ruff` 0.15.14 → 0.16.2、`redis` 7.4.0 → 8.1.0、
+  `sqlalchemy` 2.0.50 → 2.0.51、`structlog` 25.5.0 → 26.1.0 等。
+- `openapi-spec-validator` 仍锁定 0.7.2：上游 `prance[osv]` 约束为 `~=0.7.1`，无法升至 0.9.x。
+
 ## [4.8.0] - 2026-08-10
 
 ### ✨ 新增

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/CLAUDE.md

@@ -8,8 +8,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.8.0
-- **更新时间**: 2026-08-10
+- **版本**: v4.9.0
+- **更新时间**: 2026-08-11
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: df-test-framework
-Version: 4.8.0
+Version: 4.9.0
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/README.md

@@ -1,7 +1,7 @@
 # DF Test Framework
 
-> **版本**: v4.8.0
-> **更新时间**: 2026-08-10
+> **版本**: v4.9.0
+> **更新时间**: 2026-08-11
 > 简单、强大、可扩展的现代化 Python 测试自动化框架
 
 [![PyPI version](https://img.shields.io/pypi/v/df-test-framework.svg)](https://pypi.org/project/df-test-framework/)

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/docs/ESSENTIAL_DOCS.md

@@ -1,8 +1,8 @@
 # 核心文档导航 - 真正有价值的文档清单
 
 > **目标读者**: 测试开发人员、框架使用者、新团队成员
-> **更新日期**: 2026-08-10
-> **框架版本**: v4.8.0
+> **更新日期**: 2026-08-11
+> **框架版本**: v4.9.0
 
 ---
 

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/docs/README.md

@@ -1,6 +1,6 @@
 # DF Test Framework 文档中心
 
-> 版本：v4.8.0 · 最近更新：2026-08-10
+> 版本：v4.9.0 · 最近更新：2026-08-11
 > 现代化 Python 测试自动化框架的官方知识库。
 
 ---

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/docs/guides/assertions_guide.md

@@ -1,10 +1,10 @@
 # 断言系统使用指南
 
-> **版本**: v3.38.0 | **更新**: 2025-12-24
+> **版本**: v4.9.0 | **更新**: 2026-08-11
 > **引入版本**: v3.30.0
 > **模块**: `df_test_framework.testing.assertions`
 
-断言系统提供丰富的断言辅助方法，简化 API 测试代码。包含 HTTP 响应断言、JSON Schema 验证、自定义匹配器三大功能模块。
+断言系统提供丰富的断言辅助方法，简化 API 测试代码。包含 HTTP 响应断言、JSON Schema 验证、自定义匹配器、异步结果等待四大功能模块。
 
 ---
 
@@ -437,6 +437,71 @@ matcher.assert_matches(50, message="年龄必须在 1-100 之间")
 
 ---
 
+## 异步结果的等待（v4.9.0）
+
+测真实系统时，写库、发 MQ、跑定时任务都是异步完成的，断言前必须等。
+盲等固定秒数既慢又不可靠 —— 等短了偶发失败，等长了整条回归被拖垮。
+
+```python
+from df_test_framework import wait_until
+
+# 等到查得到行（默认判定为「返回值为真」）
+order = wait_until(
+    lambda: db.query_one("SELECT * FROM orders WHERE no = :n", {"n": no}),
+    message=f"订单 {no} 未落库",
+)
+
+# 自定义判定
+wait_until(
+    lambda: count_trades(order_no),
+    lambda n: n >= 2,
+    timeout=20,
+    interval=0.5,
+    message="调价流水未落齐",
+)
+```
+
+超时抛 `WaitTimeoutError`（继承 `AssertionError`，pytest 报成断言失败），
+消息里带**最后一次探测到的值**和探测次数 —— 排查时最需要的就是它：
+
+```
+调价流水未落齐（超时 20s，实际等待 20.0s，探测 40 次，最后一次结果：1）
+```
+
+异步探测用 `async_wait_until`，签名一致。
+
+### 否定断言用 `assert_consistently`
+
+`wait_until` 只用于等「应该发生的事」。断言「不该发生」——幂等、被拒后不落库、
+MQ 重投不重复扣款——轮询帮不上忙：条件一开始就成立，它立刻返回，等于没等。
+这类场景要观察完整窗口：
+
+```python
+from df_test_framework import assert_consistently
+
+assert_consistently(
+    lambda: count_trades(order_no),
+    lambda n: n == 1,
+    duration=3,
+    interval=0.5,
+    message="重复回调不该产生第二条流水",
+)
+```
+
+比裸 `time.sleep(3)` 强在三点：窗口内多次采样提高「中途变过又变回来」被发现的
+概率；一旦发现破坏立即失败而不必等满；报错带第几次采样和当时的值。
+
+```
+重复回调不该产生第二条流水（窗口 3s，第 1.5s 的第 4 次采样已不满足，当时结果：2）
+```
+
+采样是离散的：短于 `interval` 的瞬时变化仍可能错过，缩小 `interval` 只提高概率、
+不提供保证。要确定性捕获中间态得靠事件或变更日志，不是轮询。
+
+异步版本是 `async_assert_consistently`。
+
+---
+
 ## 实战示例
 
 ### 完整的 API 测试

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/docs/guides/test_data_cleanup.md

@@ -146,6 +146,86 @@ def cleanup_orders(request, database):
 
 ---
 
+### 2.6 NamingRegistry - 命名注册表（v4.8.1）
+
+清理有两条腿：用例正常结束时 cleanup fixture 按登记的 ID 清；用例崩溃/被中断时，
+兜底脚本只能按**名字模式**认领残留。命名注册表让生成端与认领端读同一份定义，
+消除两端各写一份手抄定义导致的漂移。
+
+```python
+from df_test_framework.testing.data import NamingRegistry, NamingRule, scoped
+
+REGISTRY = NamingRegistry([
+    NamingRule(
+        key="supplier_name",
+        table="supplier",
+        column="SUPPLIER_NAME",
+        template="AUTO_CASE_供应商_{tid}",   # {tid} 完整 test_id，{sid} 8 位哈希
+        match="AUTO_CASE_供应商_%",          # 兜底清理按此认领，必须锚定
+        max_length=100,                      # 超长直接报错，不静默截断
+    ),
+])
+
+# 生成
+name = REGISTRY.make("supplier_name", test_id)
+
+# 一条用例造多套前置数据时，用 scoped 附加场景标签（完整保留语义）
+name = REGISTRY.make("supplier_name", scoped(test_id, "np_agree"))
+# → AUTO_CASE_供应商_np_agree_ORD2026…（宽字段：标签在语义位）
+# {sid} 模板的短字段则让标签参与哈希，不占文本
+
+# 清理脚本取认领模式
+patterns = REGISTRY.case_match_patterns("supplier_name")
+```
+
+项目单测一行断言即可持续校验「模板产出必能被自己认领、绝不误伤保护名单」：
+
+```python
+def test_naming_registry_is_consistent():
+    assert REGISTRY.self_check(
+        "ORD202608071318033693331512",
+        protected_names=("基准池样本", "同事手工数据样本"),
+    ) == []
+```
+
+生命周期约定：`AUTO_BASE`（基准池，兜底清理永不触碰）/ `AUTO_CASE`（用例级，
+随用随清）。规则表由各项目自行登记，框架只提供机制。
+
+### 2.7 cleanup 的三种作用域（v4.9.0）
+
+```python
+cleanup          # function 级，每条用例结束就清（默认）
+cleanup_module   # module 级，整个模块跑完才清
+cleanup_session  # session 级，整轮跑完才清
+```
+
+作用域决定**前置数据能不能跨用例共享**：前置 fixture 一旦依赖 function 级的
+`cleanup`，pytest 规则下它自己也只能是 function 级，于是每条用例都要把前置链
+重建一遍。改依赖 `cleanup_module` 后才能这样写：
+
+```python
+@pytest.fixture(scope="module")
+def shared_supplier(supplier_api, cleanup_module):
+    """整个模块共用一个供应商，不再每条用例重建。"""
+    return create_supplier(supplier_api, cleanup_module)
+```
+
+**什么时候不能共享**：判据是断言锚在什么上。
+
+| 断言锚点 | 能否共享 |
+|---------|---------|
+| 自己的业务单据（订单号、批次号） | ✅ 可共享 |
+| 共享对象的总量或状态（余额、可用库存、某客户的流水条数） | ❌ 用 `cleanup` |
+| 被测对象就是「创建过程」本身 | ❌ 用 `cleanup` |
+| 要消耗或改变共享资源 | ❌ 用 `cleanup` |
+
+这条判据同时决定了用例能不能并行：锚在自己单据上的，共享和并发都安全。
+
+注意 `@pytest.mark.keep_data` 是函数级标记，宽作用域下取不到；
+`--keep-test-data` 与 `KEEP_TEST_DATA` 配置照常生效。
+
+---
+
 ## 3. 项目实现示例
 
 ### 3.1 简单列表模式

{df_test_framework-4.8.0 → df_test_framework-4.9.0}/docs/releases/README.md

@@ -1,16 +1,23 @@
 # Release Notes 发布说明索引
 
-> 当前版本：**v4.8.0** · 最近更新：2026-08-10
+> 当前版本：**v4.9.0** · 最近更新：2026-08-11
 
 完整变更摘要见 [CHANGELOG.md](../../CHANGELOG.md)。
 
 ---
 
-## v4.8.x（当前系列）
+## v4.9.x（当前系列）
 
 | 版本 | 发布日期 | 核心特性 |
 |------|----------|----------|
-| **[v4.8.0](v4.8.0.md)** ⭐ 当前 | 2026-08-10 | 国密 SM2/SM3/SM4 + 签名模块两层拆分（`build_sign_source` / `digest_sign`）|
+| **[v4.9.0](v4.9.0.md)** ⭐ 当前 | 2026-08-11 | 轮询等待与观察窗口断言、cleanup 作用域扩展、命名认领契约落地、SM2 短私钥修复 |
+
+## v4.8.x
+
+| 版本 | 发布日期 | 核心特性 |
+|------|----------|----------|
+| [v4.8.1](v4.8.1.md) | 2026-08-11 | 测试数据命名注册表 `NamingRegistry` + pytest 10 弃用 API 清理 |
+| [v4.8.0](v4.8.0.md) | 2026-08-10 | 国密 SM2/SM3/SM4 + 签名模块两层拆分（`build_sign_source` / `digest_sign`）|
 
 ## v4.7.x
 

df_test_framework-4.9.0/docs/releases/v4.8.1.md

@@ -0,0 +1,136 @@
+# v4.8.1 - 测试数据命名注册表 NamingRegistry + pytest 10 弃用 API 清理
+
+**发布日期**: 2026-08-11
+
+## 概述
+
+本版本两件事：
+
+- **`NamingRegistry`**：把测试数据的「怎么生成名字」和「兜底清理怎么认领这个名字」绑进同一份
+  定义。这套东西在 master_test 项目里已经跑了一段时间，本次下沉到框架。
+- **pytest 10 弃用 API 清理**：pytest 9.1 开始对 `config.inicfg` 告警，框架内两处用法已改掉。
+
+---
+
+## 新增
+
+### 测试数据命名注册表 `NamingRegistry`
+
+**要解决的问题**：共享测试环境里，用例造的数据得能被兜底脚本清掉，靠的是名字前缀。
+但「生成名字」写在 fixture 里、「认领名字」写在清理脚本的 SQL LIKE 里，两边各抄一份。
+改了一边忘了另一边，结果是数据悄悄堆积 —— 而且没有任何报错，直到某天环境被撑爆才发现。
+
+`NamingRule` 把生成模板、认领模式、字段上限绑在一起，两端读同一份定义：
+
+```python
+from df_test_framework import NamingRegistry, NamingRule
+from df_test_framework.testing.data.naming import Lifecycle
+
+REGISTRY = NamingRegistry([
+    NamingRule(
+        key="supplier_name",
+        table="supplier", column="name",
+        template="AUTO_CASE_供应商_{tid}",   # 生成
+        match="AUTO_CASE\\_供应商\\_%",       # 认领（SQL LIKE）
+        max_length=64,
+        lifecycle=Lifecycle.CASE,
+    ),
+    NamingRule(
+        key="login_name",
+        table="sys_user", column="login_name",
+        template="ac_{sid}",                # varchar(30)，塞不下可辨识前缀
+        match="ac\\_%",
+        max_length=30,
+        joins_via="supplier_name",          # 认领不了，跟着父对象级联删
+    ),
+])
+```
+
+**生成**：
+
+```python
+REGISTRY.make("supplier_name", test_id)              # AUTO_CASE_供应商_t20260811_a1b2
+REGISTRY.make("supplier_name", test_id, "电子面单")   # 追加业务标签，计入长度校验
+```
+
+`make()` 有两个刻意的「不宽容」设计：
+
+| 情况 | 行为 | 为什么 |
+|------|------|--------|
+| key 未登记 | 抛 `KeyError` | 新命名必须先登记，否则它天然逃出清理覆盖 |
+| 结果超长 | 抛 `ValueError` | 静默截断会把可辨识前缀切掉，认领模式再也匹配不上 |
+
+**一条用例造多套数据**时用 `scoped()` 附加场景标签：
+
+```python
+from df_test_framework.testing.data.naming import scoped
+
+REGISTRY.make("supplier_name", scoped(test_id, "sender"))
+REGISTRY.make("supplier_name", scoped(test_id, "receiver"))
+```
+
+标签的去向按模板分流 —— `{tid}` 宽字段把完整标签放在语义位（域标签之后、test_id 之前），
+这样展示端截断只会吃掉没信息量的 test_id 尾部；`{sid}` 长度吃紧字段则让标签参与短 id 哈希，
+保证唯一但不占名字文本。
+
+**自洽校验**：项目单测一行断言，持续防止规则表自己长歪：
+
+```python
+def test_naming_registry_self_consistent():
+    assert REGISTRY.self_check(SAMPLE_TEST_ID, protected_names=PROTECTED) == []
+```
+
+校验三件事：模板产出必须能被自己的 `match` 认领；任何模式都不许命中基准池前缀与保护名单
+（否则兜底脚本会删掉不属于它的数据）；`joins_via` 必须指向已登记的规则。
+
+**生命周期**：`Lifecycle.BASELINE`（`AUTO_BASE`，基准池，跨用例复用，兜底清理永不触碰）与
+`Lifecycle.CASE`（`AUTO_CASE`，用例级，随用随清）。枚举值即推荐前缀。
+
+框架只提供机制，**规则表由各项目自行登记**。`NamingRegistry` / `NamingRule` 从包顶层导入；
+`Lifecycle`、`scoped()`、`short_id()`（哈希短 id）、`like_to_regex()`（按 MySQL 语义把 LIKE
+翻成正则，清理脚本可在 Python 侧预演匹配范围）从 `df_test_framework.testing.data.naming` 导入。
+
+---
+
+## 修复
+
+### pytest 10 弃用 API 清理
+
+pytest 9.1 起，`config.inicfg` 会触发 `PytestRemovedIn10Warning`。框架内两处用它来做
+「这个 ini 项注册了吗」的守卫：
+
+- `testing/fixtures/core.py`
+- `testing/plugins/env_plugin.py`
+
+改为直接调 `config.getini()` 并捕获 `ValueError`。**行为完全等价** —— `df_settings_class`
+与 `df_plugins` 注册时默认值均为空串，是 falsy，CLI > ini > 环境变量 > 默认的优先级链不变。
+`core.py` 顺带抽出私有 helper `_read_ini()` 供两个调用点共用。
+
+对使用方无影响，无需改动项目代码。
+
+---
+
+## 依赖
+
+开发依赖整体升级，其中值得注意的：
+
+| 包 | 变化 |
+|---|---|
+| `pytest` | 9.0.3 → 9.1.1 |
+| `ruff` | 0.15.14 → 0.16.2 |
+| `redis` | 7.4.0 → 8.1.0 |
+| `sqlalchemy` | 2.0.50 → 2.0.51 |
+| `structlog` | 25.5.0 → 26.1.0 |
+
+`openapi-spec-validator` 仍锁在 0.7.2（最新为 0.9.0）：上游 `prance[osv]` 的约束是
+`~=0.7.1`，锁死 0.7.x。等 prance 放宽后才能跟进。
+
+---
+
+## 升级
+
+```bash
+pip install --upgrade df-test-framework==4.8.1
+```
+
+无破坏性变更，直接升级即可。