df-test-framework 4.7.3__tar.gz → 4.7.4__tar.gz

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/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.7.3
-- **更新时间**: 2026-05-27
+- **版本**: v4.7.4
+- **更新时间**: 2026-06-29
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/CHANGELOG.md

@@ -7,6 +7,14 @@
 
 ## [Unreleased]
 
+## [4.7.4] - 2026-06-29
+
+### ✨ 新增
+
+- **`OmsReporterPlugin` 嵌入式 scope 路由**：新增 `bind_execution(scope, callback, task_id, execution_id)` / `unbind_execution(scope)`，支持单个常驻插件实例按事件 `scope` 路由到对应执行的上报回调。嵌入方（如 OMS 测试平台）可一次 Bootstrap、多次执行复用，无需每次执行重建插件 + Bootstrap，多执行并发互不串扰。旧用法 `OmsReporterPlugin(callback, task_id, execution_id)` 完全向后兼容（构造即绑定一个作用域无关的默认上报目标）。
+
+**详细内容**: 查看完整发布说明 [v4.7.4](docs/releases/v4.7.4.md)
+
 ## [4.7.3] - 2026-05-27
 
 ### 💥 破坏性变更

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/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.7.3
-- **更新时间**: 2026-05-27
+- **版本**: v4.7.4
+- **更新时间**: 2026-06-29
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.7.3
+Version: 4.7.4
 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.7.3 → df_test_framework-4.7.4}/README.md

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

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/docs/ESSENTIAL_DOCS.md

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

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/docs/README.md

@@ -1,6 +1,6 @@
 # DF Test Framework 文档中心
 
-> 版本：v4.7.3 · 最近更新：2026-05-27
+> 版本：v4.7.4 · 最近更新：2026-06-29
 > 现代化 Python 测试自动化框架的官方知识库。
 
 ---

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/docs/releases/README.md

@@ -1,6 +1,6 @@
 # Release Notes 发布说明索引
 
-> 当前版本：**v4.7.3** · 最近更新：2026-05-27
+> 当前版本：**v4.7.4** · 最近更新：2026-06-29
 
 完整变更摘要见 [CHANGELOG.md](../../CHANGELOG.md)。
 
@@ -10,7 +10,8 @@
 
 | 版本 | 发布日期 | 核心特性 |
 |------|----------|----------|
-| **[v4.7.3](v4.7.3.md)** ⭐ 当前 | 2026-05-27 | 日志时间戳标准化：RFC 3339 毫秒 + 显式时区，`use_utc` → `timestamp` |
+| **[v4.7.4](v4.7.4.md)** ⭐ 当前 | 2026-06-29 | `OmsReporterPlugin` 嵌入式 scope 路由：一次 Bootstrap 多次执行复用，`bind_execution` / `unbind_execution` |
+| **[v4.7.3](v4.7.3.md)** | 2026-05-27 | 日志时间戳标准化：RFC 3339 毫秒 + 显式时区，`use_utc` → `timestamp` |
 | **[v4.7.2](v4.7.2.md)** | 2026-05-26 | 脚手架 `flows/` 目录 + 文档结构补强 + pytest addopts 收敛 |
 | **[v4.7.1](v4.7.1.md)** | 2026-05-22 | 修复 `_auto_allure_observer` 未取消订阅导致 Allure 重复记录 |
 | **[v4.7.0](v4.7.0.md)** | 2026-05-19 | `RuntimeContext.metadata` + 命名 AsyncDatabase 多数据库注册 |

df_test_framework-4.7.4/docs/releases/v4.7.4.md

@@ -0,0 +1,66 @@
+# v4.7.4 - OmsReporterPlugin 嵌入式 scope 路由
+
+**发布日期**: 2026-06-29
+
+## 概述
+
+本版本让 `OmsReporterPlugin` 支持以**单个常驻实例**服务多次执行：插件全局订阅一次 HTTP 事件，内部按事件的 `scope` 路由到对应执行的上报回调。嵌入方（如 OMS 测试平台）从此可以**一次 Bootstrap、多次执行复用**，不必每次执行都重建插件 + Bootstrap，多执行并发互不串扰。旧用法完全向后兼容。
+
+---
+
+## 新增
+
+### `OmsReporterPlugin.bind_execution()` / `unbind_execution()`
+
+```python
+from df_test_framework.bootstrap import Bootstrap
+from df_test_framework.plugins.builtin.reporting.oms_reporter_plugin import OmsReporterPlugin
+
+# 常驻复用：插件与 Bootstrap 各一次
+plugin = OmsReporterPlugin()
+runtime = Bootstrap().with_plugin(plugin).build().run()
+
+# 每次执行前后绑定 / 解绑（scope 通常为 f"exec_{execution_id}"）
+scope = f"exec_{execution_id}"
+plugin.bind_execution(scope, callback=send_fn, task_id=task_id, execution_id=execution_id)
+exec_runtime = runtime.with_scope(scope)   # 该执行的事件携带此 scope
+try:
+    ...                                    # 运行步骤，事件按 scope 路由到 send_fn
+finally:
+    plugin.unbind_execution(scope)
+```
+
+| 方法 | 作用 |
+|------|------|
+| `bind_execution(scope, callback, task_id, execution_id)` | 绑定一次执行的上报回调；`scope` 需与 `runtime.with_scope(scope)` 一致 |
+| `unbind_execution(scope)` | 解绑某次执行，释放其上报状态（`step_index` 等） |
+
+每个绑定维护独立的 `step_index`，因此并发执行的步骤序号互不干扰。
+
+---
+
+## 兼容性
+
+**完全向后兼容**。旧用法不变：
+
+```python
+# 单次执行（每次 Bootstrap 一个插件）—— 行为与 v4.7.3 一致
+plugin = OmsReporterPlugin(callback=send_fn, task_id="t1", execution_id="e1")
+runtime = Bootstrap().with_plugin(plugin).build().run()
+```
+
+构造时传入 `callback/task_id/execution_id` 即绑定一个**作用域无关的默认上报目标**：事件无论是否带 `scope` 都会上报到它，与旧版每次 Bootstrap 独立插件的语义一致。
+
+> 提示：旧用法每次执行仍会 Bootstrap 一次；如需消除该开销，改用 `bind_execution()` 的常驻复用模式。
+
+---
+
+## 升级方式
+
+```bash
+uv add "df-test-framework[crypto]>=4.7.4"
+# 或
+pip install -U "df-test-framework[crypto]>=4.7.4"
+```
+
+无需修改现有代码；需要常驻复用时按上文改为 `bind_execution()` / `unbind_execution()`。

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "df-test-framework"
-version = "4.7.3"
+version = "4.7.4"
 description = "基于交互模式的现代化测试自动化框架，支持多种测试场景"
 authors = [{name = "DF QA Team", email = "qa@example.com"}]
 readme = "README_PYPI.md"

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/src/df_test_framework/__init__.py

@@ -7,7 +7,7 @@ DF 测试自动化框架
 变更历史见 CHANGELOG.md，发布说明见 docs/releases/。
 """
 
-__version__ = "4.7.3"
+__version__ = "4.7.4"
 __author__ = "DF QA Team"
 
 # ==============================================================================

df_test_framework-4.7.4/src/df_test_framework/plugins/builtin/reporting/oms_reporter_plugin.py

@@ -0,0 +1,227 @@
+"""OMS 平台实时结果上报插件
+
+通过回调将测试执行事件实时推送到 OMS 平台。用于 Agent 分布式执行场景，
+将 df_test_framework 的事件流转换为 OMS 平台可消费的步骤结果。
+
+两种使用模式：
+
+1. 单次执行（旧用法，向后兼容）——每次执行 Bootstrap 一个插件实例::
+
+    plugin = OmsReporterPlugin(callback=send_fn, task_id="t1", execution_id="e1")
+    runtime = Bootstrap().with_plugin(plugin).build().run()
+
+2. 常驻复用（嵌入式）——Bootstrap 一次、插件常驻，按执行作用域（scope）分发::
+
+    plugin = OmsReporterPlugin()                       # 不绑定具体执行
+    runtime = Bootstrap().with_plugin(plugin).build().run()   # 仅一次
+    # 每次执行前后绑定/解绑（scope 通常为 f"exec_{execution_id}"）
+    plugin.bind_execution(scope, callback=send_fn, task_id="t1", execution_id="e1")
+    exec_runtime = runtime.with_scope(scope)           # 事件携带该 scope
+    ...                                                # 运行步骤
+    plugin.unbind_execution(scope)
+
+模式 2 让嵌入方（如 OMS 测试平台）无需每次执行重建插件 + Bootstrap：插件全局订阅一次，
+内部按事件的 ``scope`` 路由到对应执行的上报回调，多执行并发互不串扰。
+
+配合 OMS Agent 使用时，callback 即为 WebSocket send 函数。
+"""
+
+import asyncio
+import time
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from df_test_framework.core.events import (
+    HttpRequestEndEvent,
+    HttpRequestErrorEvent,
+    HttpRequestStartEvent,
+)
+from df_test_framework.infrastructure.events import EventBus
+from df_test_framework.infrastructure.plugins import hookimpl
+
+OmsCallback = Callable[[dict[str, Any]], Coroutine[Any, Any, None]]
+
+
+class _ExecutionSink:
+    """单次执行的上报状态（回调 + 标识 + 步骤计数）。"""
+
+    def __init__(self, callback: OmsCallback, task_id: str, execution_id: str) -> None:
+        self.callback = callback
+        self.task_id = task_id
+        self.execution_id = execution_id
+        self.step_index = 0
+        self.pending: dict[str, dict[str, Any]] = {}
+
+
+class OmsReporterPlugin:
+    """OMS 实时上报插件 — 监听框架事件并按执行作用域推送到 OMS 平台。
+
+    全局订阅一次 HTTP 事件，内部按事件的 ``scope`` 路由到对应执行的回调；
+    支持常驻复用（一次 Bootstrap，多次执行）。
+    """
+
+    def __init__(
+        self,
+        callback: OmsCallback | None = None,
+        task_id: str | None = None,
+        execution_id: str | None = None,
+        *,
+        scope: str | None = None,
+    ) -> None:
+        """初始化插件。
+
+        Args:
+            callback: 上报回调（单次执行用法时必填）。
+            task_id: 任务 ID（单次执行用法时必填）。
+            execution_id: 执行 ID（单次执行用法时必填）。
+            scope: 可选作用域；指定时把传入的回调绑定到该 scope，
+                未指定时作为"作用域无关"的默认上报目标（兼容每次 Bootstrap 一个插件的旧用法）。
+        """
+        # scope -> sink（常驻复用按 scope 路由）
+        self._sinks: dict[str, _ExecutionSink] = {}
+        # 作用域无关的默认上报目标（旧用法：每次 Bootstrap 一个插件，事件不带 scope）
+        self._default_sink: _ExecutionSink | None = None
+
+        if callback is not None and task_id is not None and execution_id is not None:
+            sink = _ExecutionSink(callback, task_id, execution_id)
+            if scope is not None:
+                self._sinks[scope] = sink
+            else:
+                self._default_sink = sink
+
+    def bind_execution(
+        self,
+        scope: str,
+        callback: OmsCallback,
+        task_id: str,
+        execution_id: str,
+    ) -> None:
+        """绑定一次执行的上报回调（常驻复用）。
+
+        Args:
+            scope: 执行作用域，需与运行时 ``runtime.with_scope(scope)`` 一致。
+            callback: 上报回调。
+            task_id: 任务 ID。
+            execution_id: 执行 ID。
+        """
+        self._sinks[scope] = _ExecutionSink(callback, task_id, execution_id)
+
+    def unbind_execution(self, scope: str) -> None:
+        """解绑某次执行，释放其上报状态。
+
+        Args:
+            scope: 执行作用域。
+        """
+        self._sinks.pop(scope, None)
+
+    def _resolve_sink(self, event: Any) -> _ExecutionSink | None:
+        """按事件 scope 解析上报目标；无匹配时回退到作用域无关的默认目标。"""
+        scope = getattr(event, "scope", None)
+        if scope is not None:
+            sink = self._sinks.get(scope)
+            if sink is not None:
+                return sink
+        return self._default_sink
+
+    def _dispatch(self, sink: _ExecutionSink, step_result: dict[str, Any]) -> None:
+        """把步骤结果包成 OMS 消息并异步推送。"""
+        message = {
+            "type": "task.step_result",
+            "payload": {
+                "task_id": sink.task_id,
+                "execution_id": sink.execution_id,
+                **step_result,
+            },
+        }
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(sink.callback(message))
+        except RuntimeError:
+            # 无运行中的事件循环（如同步上下文）时静默跳过
+            pass
+
+    @hookimpl
+    def df_event_handlers(self, event_bus: EventBus) -> list[Any]:
+        """注册 HTTP 事件处理器，实时上报到 OMS。"""
+        handlers: list[Any] = []
+
+        @event_bus.on(HttpRequestStartEvent)
+        def on_http_start(event: HttpRequestStartEvent) -> None:
+            """记录请求开始时间。"""
+            sink = self._resolve_sink(event)
+            if sink is None:
+                return
+            key = f"{event.method}:{event.url}"
+            sink.pending[key] = {
+                "start_time": time.time(),
+                "method": event.method,
+                "url": event.url,
+            }
+
+        handlers.append(on_http_start)
+
+        @event_bus.on(HttpRequestEndEvent)
+        def on_http_end(event: HttpRequestEndEvent) -> None:
+            """HTTP 请求完成 — 上报步骤结果。"""
+            sink = self._resolve_sink(event)
+            if sink is None:
+                return
+            sink.step_index += 1
+            key = f"{event.method}:{event.url}"
+            sink.pending.pop(key, None)
+            duration = event.duration if hasattr(event, "duration") else 0
+
+            is_success = 200 <= event.status_code < 400
+            step_result = {
+                "step_order": sink.step_index,
+                "request_name": f"{event.method} {event.url}",
+                "status": "success" if is_success else "failed",
+                "request_data": {
+                    "method": event.method,
+                    "url": event.url,
+                    "headers": getattr(event, "request_headers", {}),
+                },
+                "response_data": {
+                    "status_code": event.status_code,
+                    "headers": getattr(event, "response_headers", {}),
+                    "elapsed": duration,
+                },
+                "assertion_results": [],
+                "extracted_variables": {},
+                "error_message": None,
+                "duration_ms": int(duration * 1000),
+            }
+            self._dispatch(sink, step_result)
+
+        handlers.append(on_http_end)
+
+        @event_bus.on(HttpRequestErrorEvent)
+        def on_http_error(event: HttpRequestErrorEvent) -> None:
+            """HTTP 请求错误 — 上报错误步骤。"""
+            sink = self._resolve_sink(event)
+            if sink is None:
+                return
+            sink.step_index += 1
+            key = f"{event.method}:{event.url}"
+            sink.pending.pop(key, None)
+            duration = event.duration if hasattr(event, "duration") else 0
+
+            step_result = {
+                "step_order": sink.step_index,
+                "request_name": f"{event.method} {event.url}",
+                "status": "error",
+                "request_data": {
+                    "method": event.method,
+                    "url": event.url,
+                },
+                "response_data": {},
+                "assertion_results": [],
+                "extracted_variables": {},
+                "error_message": f"{event.error_type}: {event.error_message}",
+                "duration_ms": int(duration * 1000),
+            }
+            self._dispatch(sink, step_result)
+
+        handlers.append(on_http_error)
+
+        return handlers

df_test_framework-4.7.4/tests/plugins/builtin/reporting/test_oms_reporter_plugin.py

@@ -0,0 +1,124 @@
+"""OmsReporterPlugin 单元测试 — 嵌入式 scope 路由与向后兼容"""
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+from df_test_framework.infrastructure.events import EventBus
+from df_test_framework.plugins.builtin.reporting.oms_reporter_plugin import OmsReporterPlugin
+
+
+def _register(plugin: OmsReporterPlugin) -> tuple:
+    """注册事件处理器，返回 (on_start, on_end, on_error)。"""
+    bus = EventBus()
+    handlers = plugin.df_event_handlers(bus)
+    return handlers[0], handlers[1], handlers[2]
+
+
+def _end_event(
+    scope: str | None,
+    method: str = "GET",
+    url: str = "http://svc/a",
+    status_code: int = 200,
+    duration: float = 0.05,
+) -> SimpleNamespace:
+    return SimpleNamespace(
+        scope=scope, method=method, url=url, status_code=status_code, duration=duration
+    )
+
+
+class TestBackwardCompatSingleExecution:
+    """旧用法：构造时绑定单次执行，事件不区分 scope。"""
+
+    async def test_legacy_constructor_reports_regardless_of_scope(self) -> None:
+        cb = AsyncMock()
+        plugin = OmsReporterPlugin(callback=cb, task_id="t1", execution_id="e1")
+        _, on_end, _ = _register(plugin)
+
+        on_end(_end_event(scope="exec_e1"))  # 事件带 scope，默认 sink 仍接收
+        await asyncio.sleep(0)
+
+        cb.assert_awaited_once()
+        payload = cb.await_args.args[0]["payload"]
+        assert payload["task_id"] == "t1"
+        assert payload["execution_id"] == "e1"
+        assert payload["step_order"] == 1
+        assert payload["status"] == "success"
+
+    async def test_legacy_reports_when_event_has_no_scope(self) -> None:
+        cb = AsyncMock()
+        plugin = OmsReporterPlugin(callback=cb, task_id="t1", execution_id="e1")
+        _, on_end, _ = _register(plugin)
+
+        on_end(_end_event(scope=None))
+        await asyncio.sleep(0)
+
+        cb.assert_awaited_once()
+
+
+class TestPersistentScopeRouting:
+    """新用法：常驻插件，按 scope 路由到对应执行。"""
+
+    async def test_routes_by_scope_with_independent_step_index(self) -> None:
+        cb_a, cb_b = AsyncMock(), AsyncMock()
+        plugin = OmsReporterPlugin()
+        _, on_end, _ = _register(plugin)
+        plugin.bind_execution("exec_a", cb_a, "ta", "ea")
+        plugin.bind_execution("exec_b", cb_b, "tb", "eb")
+
+        on_end(_end_event(scope="exec_a"))
+        on_end(_end_event(scope="exec_a"))
+        on_end(_end_event(scope="exec_b"))
+        await asyncio.sleep(0)
+
+        assert cb_a.await_count == 2
+        assert cb_b.await_count == 1
+        # 每个执行的 step_order 独立自增
+        assert cb_a.await_args_list[0].args[0]["payload"]["step_order"] == 1
+        assert cb_a.await_args_list[1].args[0]["payload"]["step_order"] == 2
+        b_payload = cb_b.await_args.args[0]["payload"]
+        assert b_payload["step_order"] == 1
+        assert b_payload["execution_id"] == "eb"
+        assert b_payload["task_id"] == "tb"
+
+    async def test_unbind_stops_reporting(self) -> None:
+        cb = AsyncMock()
+        plugin = OmsReporterPlugin()
+        _, on_end, _ = _register(plugin)
+        plugin.bind_execution("exec_a", cb, "ta", "ea")
+        plugin.unbind_execution("exec_a")
+
+        on_end(_end_event(scope="exec_a"))
+        await asyncio.sleep(0)
+
+        cb.assert_not_awaited()
+
+    async def test_unknown_scope_without_default_is_ignored(self) -> None:
+        plugin = OmsReporterPlugin()
+        _, on_end, _ = _register(plugin)
+
+        # 未绑定任何执行，事件直接忽略且不抛异常
+        on_end(_end_event(scope="exec_unknown"))
+        await asyncio.sleep(0)
+
+    async def test_error_event_reports_error_status(self) -> None:
+        cb = AsyncMock()
+        plugin = OmsReporterPlugin()
+        _, _, on_error = _register(plugin)
+        plugin.bind_execution("exec_a", cb, "ta", "ea")
+
+        event = SimpleNamespace(
+            scope="exec_a",
+            method="POST",
+            url="http://svc/b",
+            duration=0.0,
+            error_type="Timeout",
+            error_message="boom",
+        )
+        on_error(event)
+        await asyncio.sleep(0)
+
+        payload = cb.await_args.args[0]["payload"]
+        assert payload["status"] == "error"
+        assert payload["error_message"] == "Timeout: boom"
+        assert payload["step_order"] == 1

{df_test_framework-4.7.3 → df_test_framework-4.7.4}/uv.lock

@@ -590,7 +590,7 @@ wheels = [
 
 [[package]]
 name = "df-test-framework"
-version = "4.7.3"
+version = "4.7.4"
 source = { editable = "." }
 dependencies = [
     { name = "allure-pytest" },