shopline-qa-tools 1.0.0__tar.gz

shopline_qa_tools-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+exclude README.md

shopline_qa_tools-1.0.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: shopline-qa-tools
+Version: 1.0.0
+Summary: QA 常用工具包
+Requires-Python: >=3.8
+Requires-Dist: pulsar-client>=3.4
+Requires-Dist: deepdiff>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"

shopline_qa_tools-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shopline-qa-tools"
+version = "1.0.0"
+description = "QA 常用工具包"
+requires-python = ">=3.8"
+dependencies = ["pulsar-client>=3.4", "deepdiff>=6"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+confusefile = "shopline_qa_tools.confusefile.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "pulsar: 需要真实 Pulsar 的集成用例",
+    "pulsar_config(**kwargs): 覆盖单个用例的 Pulsar 配置，如 topic/subscription_name/wait_timeout_s",
+]

shopline_qa_tools-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shopline_qa_tools-1.0.0/src/shopline_qa_tools/__init__.py

@@ -0,0 +1,3 @@
+"""QA 常用工具包。"""
+
+__version__ = "1.0.0"

shopline_qa_tools-1.0.0/src/shopline_qa_tools/confusefile/__init__.py

@@ -0,0 +1,5 @@
+"""文件混淆：在文件末尾追加内容，使文件 MD5 发生变化。"""
+
+from .core import METHODS, ConfuseResult, confuse, md5sum
+
+__all__ = ["METHODS", "ConfuseResult", "confuse", "md5sum"]

shopline_qa_tools-1.0.0/src/shopline_qa_tools/confusefile/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

shopline_qa_tools-1.0.0/src/shopline_qa_tools/confusefile/cli.py

@@ -0,0 +1,81 @@
+"""confusefile 命令行入口。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from .core import DEFAULT_COMMENT_PREFIX, DEFAULT_RANDOM_BYTES, METHODS, confuse
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="confusefile",
+        description="在文件末尾追加内容，改变文件 MD5。默认原地覆盖并自动备份。",
+    )
+    p.add_argument("files", nargs="+", help="要处理的文件，可传多个")
+    p.add_argument("-o", "--output", help="输出文件路径（仅处理单个文件时可用），源文件保持不变")
+    p.add_argument("-d", "--out-dir", help="输出目录（可批量），文件名不变，源文件保持不变")
+    p.add_argument("-m", "--method", choices=METHODS, default="random",
+                   help="random=追加随机字节（默认，适合任意文件）；comment=追加一行注释（适合文本文件）")
+    p.add_argument("-n", "--bytes", type=int, default=DEFAULT_RANDOM_BYTES, dest="random_bytes",
+                   help=f"random 方法追加的字节数，默认 {DEFAULT_RANDOM_BYTES}")
+    p.add_argument("-p", "--prefix", default=DEFAULT_COMMENT_PREFIX, dest="comment_prefix",
+                   help=f'comment 方法的注释前缀，默认 "{DEFAULT_COMMENT_PREFIX}"')
+    p.add_argument("--no-backup", action="store_true", help="原地覆盖时不备份源文件")
+    p.add_argument("--json", action="store_true", help="以 JSON 输出结果")
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.output and args.out_dir:
+        print("error: -o 和 -d 不能同时使用", file=sys.stderr)
+        return 2
+    if args.output and len(args.files) > 1:
+        print("error: 处理多个文件时请用 -d 指定输出目录", file=sys.stderr)
+        return 2
+
+    results, failed = [], 0
+    for f in args.files:
+        if args.output:
+            output = args.output
+        elif args.out_dir:
+            output = str(Path(args.out_dir) / Path(f).name)
+        else:
+            output = None
+        try:
+            r = confuse(f, output, method=args.method, random_bytes=args.random_bytes,
+                        comment_prefix=args.comment_prefix, backup=not args.no_backup)
+        except (OSError, ValueError) as e:
+            failed += 1
+            print(f"error: {f}: {e}", file=sys.stderr)
+            continue
+        results.append(r)
+        if not args.json:
+            print(f"file:    {r.output}")
+            if r.backup:
+                print(f"backup:  {r.backup}")
+            print(f"md5:     {r.original_md5} -> {r.new_md5}")
+            print(f"size:    +{r.size_change} bytes ({r.method})")
+            print()
+
+    if args.json:
+        print(json.dumps([
+            {
+                "source": str(r.source), "output": str(r.output),
+                "backup": str(r.backup) if r.backup else None,
+                "originalMd5": r.original_md5, "newMd5": r.new_md5,
+                "method": r.method, "sizeChange": r.size_change,
+            } for r in results
+        ], ensure_ascii=False, indent=2))
+
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shopline_qa_tools-1.0.0/src/shopline_qa_tools/confusefile/core.py

@@ -0,0 +1,113 @@
+"""文件混淆核心逻辑。"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import secrets
+import shutil
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+PathLike = Union[str, os.PathLike]
+
+RANDOM = "random"
+COMMENT = "comment"
+METHODS = (RANDOM, COMMENT)
+
+DEFAULT_RANDOM_BYTES = 8
+DEFAULT_COMMENT_PREFIX = "# Confused: "
+
+
+@dataclass
+class ConfuseResult:
+    source: Path
+    output: Path
+    backup: Optional[Path]
+    original_md5: str
+    new_md5: str
+    method: str
+    size_change: int
+
+
+def md5sum(path: PathLike) -> str:
+    h = hashlib.md5()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _build_suffix(method: str, random_bytes: int, comment_prefix: str) -> bytes:
+    if method == RANDOM:
+        if random_bytes <= 0:
+            raise ValueError("random_bytes 必须大于 0")
+        return secrets.token_bytes(random_bytes)
+    if method == COMMENT:
+        line = f"\n{comment_prefix}{uuid.uuid4()}_{time.time_ns()}\n"
+        return line.encode("utf-8")
+    raise ValueError(f"不支持的混淆方法: {method}，可选: {', '.join(METHODS)}")
+
+
+def confuse(
+    src: PathLike,
+    output: Optional[PathLike] = None,
+    *,
+    method: str = RANDOM,
+    random_bytes: int = DEFAULT_RANDOM_BYTES,
+    comment_prefix: str = DEFAULT_COMMENT_PREFIX,
+    backup: bool = True,
+) -> ConfuseResult:
+    """混淆文件，使其 MD5 改变。
+
+    - 传 ``output``：生成新文件，源文件不变。
+    - 不传 ``output``：原地覆盖源文件；``backup=True`` 时先备份为 ``<文件名>.bak_<时间戳>``。
+    """
+    src = Path(src)
+    if not src.is_file():
+        raise FileNotFoundError(f"文件不存在: {src}")
+
+    method = method.strip().lower()
+    suffix = _build_suffix(method, random_bytes, comment_prefix)
+    original_md5 = md5sum(src)
+    original_size = src.stat().st_size
+    backup_path: Optional[Path] = None
+
+    if output is not None:
+        dst = Path(output)
+        if dst.resolve() == src.resolve():
+            raise ValueError("输出路径与源文件相同，原地覆盖请不要传 output")
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(src, dst)
+        with open(dst, "ab") as f:
+            f.write(suffix)
+    else:
+        dst = src
+        if backup:
+            backup_path = src.with_name(f"{src.name}.bak_{time.time_ns()}")
+            shutil.copy2(src, backup_path)
+        # 先写临时文件再原子替换，避免中途失败导致源文件损坏
+        fd, tmp = tempfile.mkstemp(prefix=f".{src.name}.tmp_", dir=src.parent)
+        try:
+            with os.fdopen(fd, "wb") as out, open(src, "rb") as inp:
+                shutil.copyfileobj(inp, out)
+                out.write(suffix)
+            shutil.copymode(src, tmp)
+            os.replace(tmp, src)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise
+
+    return ConfuseResult(
+        source=src,
+        output=dst,
+        backup=backup_path,
+        original_md5=original_md5,
+        new_md5=md5sum(dst),
+        method=method,
+        size_change=dst.stat().st_size - original_size,
+    )

shopline_qa_tools-1.0.0/src/shopline_qa_tools/pulsar_capture/__init__.py

@@ -0,0 +1,48 @@
+"""Pulsar 消息捕获与校验工具（测试专用，不 ack / 不 nack，不影响业务订阅）。
+
+依赖：pip install -e '.[pulsar]'
+"""
+
+from .capturer import MessageCapturer, MessageNotFoundError
+from .config import DEFAULT_IGNORE_FIELDS, PulsarTestConfig
+from .message import CapturedMessage
+from .validator import (
+    MessageValidationError,
+    MessageValidator,
+    PayloadDecodeError,
+    assert_key,
+    assert_payload,
+    assert_properties,
+    assert_publish_time,
+    assert_topic,
+    diff_payload,
+    extract_json_payload,
+)
+
+__all__ = [
+    "CapturedMessage",
+    "DEFAULT_IGNORE_FIELDS",
+    "MessageCapturer",
+    "MessageNotFoundError",
+    "MessageValidationError",
+    "MessageValidator",
+    "PayloadDecodeError",
+    "PulsarTestConfig",
+    "PulsarTestConsumer",
+    "assert_key",
+    "assert_payload",
+    "assert_properties",
+    "assert_publish_time",
+    "assert_topic",
+    "diff_payload",
+    "extract_json_payload",
+]
+
+
+def __getattr__(name):
+    # PulsarTestConsumer 依赖 pulsar-client，延迟导入：只用校验工具时无需安装 pulsar-client
+    if name == "PulsarTestConsumer":
+        from .consumer import PulsarTestConsumer
+
+        return PulsarTestConsumer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

shopline_qa_tools-1.0.0/src/shopline_qa_tools/pulsar_capture/capturer.py

@@ -0,0 +1,247 @@
+"""消息捕获器：后台线程持续 receive，暂存到内存，支持按字段查找与轮询等待。"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+from .message import CapturedMessage, format_ms, now_ms
+
+logger = logging.getLogger(__name__)
+
+Predicate = Callable[[CapturedMessage], bool]
+_MISSING = object()
+
+
+class MessageNotFoundError(AssertionError):
+    """等待超时仍未找到匹配消息。继承 AssertionError，pytest 中按断言失败展示。"""
+
+
+def _values_equal(actual: Any, expected: Any) -> bool:
+    if callable(expected):
+        return bool(expected(actual))
+    if actual == expected:
+        return True
+    # properties 都是字符串，兼容 order_id=123 与 "123" 的比较
+    if isinstance(actual, str) != isinstance(expected, str) and not isinstance(actual, (dict, list)):
+        return str(actual) == str(expected)
+    return False
+
+
+def build_matcher(predicate: Optional[Predicate] = None, **criteria: Any) -> Predicate:
+    """criteria 的 key 支持：payload 字段/点路径（data.order_id）、properties 名、key、topic。
+    value 可以是期望值，也可以是 callable(actual) -> bool。
+    """
+
+    def match(msg: CapturedMessage) -> bool:
+        for name, expected in criteria.items():
+            actual = msg.get(name, _MISSING)
+            if actual is _MISSING or not _values_equal(actual, expected):
+                return False
+        return predicate(msg) if predicate else True
+
+    return match
+
+
+def describe_criteria(predicate: Optional[Predicate], criteria: Dict[str, Any]) -> str:
+    parts = [f"{k}={v!r}" for k, v in criteria.items()]
+    if predicate is not None:
+        parts.append(f"predicate={getattr(predicate, '__name__', repr(predicate))}")
+    return ", ".join(parts) or "<任意消息>"
+
+
+class MessageCapturer:
+    def __init__(
+        self,
+        consumer: Any,
+        *,
+        wait_timeout_s: float = 10.0,
+        poll_interval_s: float = 0.2,
+        receive_timeout_ms: int = 1000,
+        clock_skew_ms: int = 2000,
+        topic: str = "",
+        subscription_name: str = "",
+    ) -> None:
+        """consumer 只需实现 receive(timeout_ms) -> Optional[CapturedMessage]。"""
+        self._consumer = consumer
+        self.wait_timeout_s = wait_timeout_s
+        self.poll_interval_s = poll_interval_s
+        self.receive_timeout_ms = receive_timeout_ms
+        self.clock_skew_ms = clock_skew_ms
+        self.topic = topic
+        self.subscription_name = subscription_name
+
+        self._messages: List[CapturedMessage] = []
+        self._cond = threading.Condition()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._since_ms = now_ms() - clock_skew_ms
+        self._stale_count = 0
+        self._errors: List[str] = []
+
+    @classmethod
+    def from_consumer(cls, consumer: Any) -> "MessageCapturer":
+        """从 PulsarTestConsumer 读取配置构造。"""
+        cfg = consumer.config
+        return cls(
+            consumer,
+            wait_timeout_s=cfg.wait_timeout_s,
+            poll_interval_s=cfg.poll_interval_s,
+            receive_timeout_ms=cfg.receive_timeout_ms,
+            clock_skew_ms=cfg.clock_skew_ms,
+            topic=cfg.topic,
+            subscription_name=cfg.subscription_name,
+        )
+
+    # ---------- 生命周期 ----------
+    def start(self) -> "MessageCapturer":
+        if self._thread and self._thread.is_alive():
+            return self
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._run, name="pulsar-message-capturer", daemon=True)
+        self._thread.start()
+        return self
+
+    def stop(self, join_timeout_s: Optional[float] = None) -> None:
+        self._stop.set()
+        t = self._thread
+        if t and t.is_alive():
+            # receive 最长阻塞 receive_timeout_ms，等它自然返回
+            t.join(join_timeout_s if join_timeout_s is not None else self.receive_timeout_ms / 1000 + 2)
+            if t.is_alive():
+                logger.warning("捕获线程未在超时内退出")
+        self._thread = None
+
+    def __enter__(self) -> "MessageCapturer":
+        return self.start()
+
+    def __exit__(self, *exc: Any) -> None:
+        self.stop()
+
+    def clear(self) -> None:
+        """清空已捕获消息，并把“起始时间”重置为当前，之前发布的消息不再收集。"""
+        with self._cond:
+            self._messages.clear()
+            self._errors.clear()
+            self._stale_count = 0
+            self._since_ms = now_ms() - self.clock_skew_ms
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                msg = self._consumer.receive(self.receive_timeout_ms)
+            except Exception as e:  # 记录错误继续收，超时报错时一并输出
+                with self._cond:
+                    self._errors.append(f"{format_ms(now_ms())} {e!r}")
+                    del self._errors[:-20]
+                if self._stop.wait(self.poll_interval_s):
+                    break
+                continue
+            if msg is None:
+                continue
+            self.add(msg)
+
+    def add(self, msg: CapturedMessage) -> bool:
+        """加入一条消息（后台线程调用；也可手工注入）。返回是否被收集。"""
+        with self._cond:
+            if msg.publish_time_ms and msg.publish_time_ms < self._since_ms:
+                self._stale_count += 1  # 上一轮残留的旧消息
+                return False
+            self._messages.append(msg)
+            self._cond.notify_all()
+            return True
+
+    # ---------- 查询 ----------
+    @property
+    def messages(self) -> List[CapturedMessage]:
+        with self._cond:
+            return list(self._messages)
+
+    def find_all(self, predicate: Optional[Predicate] = None, **criteria: Any) -> List[CapturedMessage]:
+        """返回所有匹配消息，按接收顺序。"""
+        match = build_matcher(predicate, **criteria)
+        return [m for m in self.messages if match(m)]
+
+    def find_latest(self, predicate: Optional[Predicate] = None, **criteria: Any) -> Optional[CapturedMessage]:
+        """返回最近一条匹配消息（publish_time 最大；相同时取后收到的）。"""
+        found = self.find_all(predicate, **criteria)
+        if not found:
+            return None
+        return max(enumerate(found), key=lambda p: (p[1].publish_time_ms, p[0]))[1]
+
+    def wait_for_all(
+        self,
+        predicate: Optional[Predicate] = None,
+        *,
+        count: int = 1,
+        timeout: Optional[float] = None,
+        **criteria: Any,
+    ) -> List[CapturedMessage]:
+        """轮询等待直到匹配消息数 >= count，返回所有匹配消息；超时抛 MessageNotFoundError。"""
+        if count < 1:
+            raise ValueError("count 必须 >= 1")
+        timeout = self.wait_timeout_s if timeout is None else timeout
+        match = build_matcher(predicate, **criteria)
+        deadline = time.monotonic() + timeout
+        while True:
+            with self._cond:
+                found = [m for m in self._messages if match(m)]
+                if len(found) >= count:
+                    return found
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                self._cond.wait(min(remaining, self.poll_interval_s))
+        raise MessageNotFoundError(self._not_found_message(predicate, criteria, count, len(found), timeout))
+
+    def wait_for(
+        self,
+        predicate: Optional[Predicate] = None,
+        *,
+        timeout: Optional[float] = None,
+        **criteria: Any,
+    ) -> CapturedMessage:
+        """轮询等待第一条匹配消息出现，返回最近一条匹配消息。"""
+        self.wait_for_all(predicate, count=1, timeout=timeout, **criteria)
+        return self.find_latest(predicate, **criteria)  # type: ignore[return-value]
+
+    def assert_no_message(
+        self, predicate: Optional[Predicate] = None, *, within: float = 3.0, **criteria: Any
+    ) -> None:
+        """断言 within 秒内没有匹配消息（用于“不应发消息”的场景）。"""
+        try:
+            found = self.wait_for_all(predicate, count=1, timeout=within, **criteria)
+        except MessageNotFoundError:
+            return
+        raise AssertionError(
+            f"期望 {within}s 内没有匹配消息 [{describe_criteria(predicate, criteria)}]，"
+            f"实际收到 {len(found)} 条:\n" + "\n".join(f"  - {m.summary()}" for m in found)
+        )
+
+    def _not_found_message(self, predicate, criteria, count, found, timeout) -> str:
+        with self._cond:
+            msgs = list(self._messages)
+            stale = self._stale_count
+            errors = list(self._errors)
+        lines = [
+            f"等待 {timeout}s 未找到匹配消息: 条件 [{describe_criteria(predicate, criteria)}]，"
+            f"期望至少 {count} 条，实际匹配 {found} 条",
+            f"topic={self.topic or '-'} subscription={self.subscription_name or '-'} "
+            f"捕获起点={format_ms(self._since_ms)}",
+            f"期间共捕获 {len(msgs)} 条消息，过滤掉早于起点的旧消息 {stale} 条",
+        ]
+        if self._thread is None or not self._thread.is_alive():
+            lines.append("注意: 捕获线程未运行，是否忘记调用 start()？")
+        if msgs:
+            lines.append("最近捕获的消息（最多 5 条）:")
+            lines += [f"  - {m.summary()}" for m in msgs[-5:]]
+        if errors:
+            lines.append("receive 异常（最近 5 条）:")
+            lines += [f"  - {e}" for e in errors[-5:]]
+        lines.append(
+            "排查建议: 1) 确认业务是否真的发了消息/发到了该 topic；2) 测试消费者需在发消息之前启动(Latest)；"
+            "3) 同一测试订阅如被多个进程 Shared 消费，消息会被分走；4) 检查查找字段名是否在 payload 或 properties 中"
+        )
+        return "\n".join(lines)

shopline_qa_tools-1.0.0/src/shopline_qa_tools/pulsar_capture/config.py

@@ -0,0 +1,112 @@
+"""Pulsar 测试消费配置。
+
+所有超时、topic、订阅名都可通过环境变量或 pytest marker 覆盖，不写死在用例里。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from typing import Any, Tuple
+
+# 默认忽略的动态字段（任意层级同名字段都会被忽略）
+DEFAULT_IGNORE_FIELDS: Tuple[str, ...] = ("created_at", "updated_at", "id", "trace_id")
+
+SUPPORTED_CONSUMER_TYPES = ("Shared", "Failover")
+
+
+def _env(name: str, default: Any, cast=str) -> Any:
+    raw = os.environ.get(name)
+    if raw is None or raw.strip() == "":
+        return default
+    try:
+        return cast(raw.strip())
+    except ValueError as e:
+        raise ValueError(f"环境变量 {name}={raw!r} 格式错误: {e}") from None
+
+
+def _to_bool(raw: str) -> bool:
+    return raw.lower() in ("1", "true", "yes", "y", "on")
+
+
+def _to_tuple(raw: str) -> Tuple[str, ...]:
+    return tuple(s.strip() for s in raw.split(",") if s.strip())
+
+
+@dataclass(frozen=True)
+class PulsarTestConfig:
+    service_url: str = "pulsar://localhost:6650"
+    topic: str = "persistent://public/default/order-created"
+    # 固定、可配置的测试订阅名，禁止与业务订阅同名
+    subscription_name: str = "test-sub-order-validate"
+    # 测试订阅名必须以该前缀开头，防止误用业务订阅（置空可关闭校验）
+    subscription_prefix: str = "test-"
+    consumer_type: str = "Shared"  # Shared / Failover
+    # 单次 consumer.receive() 超时（毫秒）
+    receive_timeout_ms: int = 1000
+    # 等待匹配消息的总超时（秒）
+    wait_timeout_s: float = 10.0
+    # 轮询等待间隔（秒）
+    poll_interval_s: float = 0.2
+    # Pulsar client 操作超时 / 连接超时
+    operation_timeout_s: int = 10
+    connect_timeout_ms: int = 5000
+    # 关闭时取消测试订阅，避免残留订阅和 backlog 堆积（只作用于测试订阅）
+    unsubscribe_on_close: bool = True
+    # 只收 publish_time >= 捕获开始时间 - clock_skew_ms 的消息，过滤上次残留
+    clock_skew_ms: int = 2000
+    ignore_fields: Tuple[str, ...] = field(default=DEFAULT_IGNORE_FIELDS)
+
+    def __post_init__(self) -> None:
+        errors = []
+        if self.consumer_type not in SUPPORTED_CONSUMER_TYPES:
+            errors.append(f"consumer_type 只支持 {SUPPORTED_CONSUMER_TYPES}，当前为 {self.consumer_type!r}")
+        if not self.subscription_name:
+            errors.append("subscription_name 不能为空")
+        elif self.subscription_prefix and not self.subscription_name.startswith(self.subscription_prefix):
+            errors.append(
+                f"测试订阅名 {self.subscription_name!r} 必须以 {self.subscription_prefix!r} 开头，"
+                "避免误用业务订阅"
+            )
+        if not self.topic:
+            errors.append("topic 不能为空")
+        for name in ("receive_timeout_ms", "wait_timeout_s", "poll_interval_s",
+                     "operation_timeout_s", "connect_timeout_ms"):
+            if getattr(self, name) <= 0:
+                errors.append(f"{name} 必须 > 0，当前为 {getattr(self, name)!r}")
+        if self.clock_skew_ms < 0:
+            errors.append(f"clock_skew_ms 不能为负数，当前为 {self.clock_skew_ms!r}")
+        if errors:
+            raise ValueError("PulsarTestConfig 配置错误:\n  - " + "\n  - ".join(errors))
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "PulsarTestConfig":
+        """从环境变量读取配置，overrides 优先级最高。"""
+        d = cls()
+        values = dict(
+            service_url=_env("PULSAR_SERVICE_URL", d.service_url),
+            topic=_env("PULSAR_TOPIC", d.topic),
+            subscription_name=_env("PULSAR_TEST_SUBSCRIPTION", d.subscription_name),
+            subscription_prefix=os.environ.get("PULSAR_TEST_SUB_PREFIX", d.subscription_prefix),
+            consumer_type=_env("PULSAR_CONSUMER_TYPE", d.consumer_type),
+            receive_timeout_ms=_env("PULSAR_RECEIVE_TIMEOUT_MS", d.receive_timeout_ms, int),
+            wait_timeout_s=_env("PULSAR_WAIT_TIMEOUT_S", d.wait_timeout_s, float),
+            poll_interval_s=_env("PULSAR_POLL_INTERVAL_S", d.poll_interval_s, float),
+            operation_timeout_s=_env("PULSAR_OPERATION_TIMEOUT_S", d.operation_timeout_s, int),
+            connect_timeout_ms=_env("PULSAR_CONNECT_TIMEOUT_MS", d.connect_timeout_ms, int),
+            unsubscribe_on_close=_env("PULSAR_UNSUBSCRIBE_ON_CLOSE", d.unsubscribe_on_close, _to_bool),
+            clock_skew_ms=_env("PULSAR_CLOCK_SKEW_MS", d.clock_skew_ms, int),
+            ignore_fields=_env("PULSAR_IGNORE_FIELDS", d.ignore_fields, _to_tuple),
+        )
+        values.update(overrides)
+        return cls(**values)
+
+    def with_overrides(self, **overrides: Any) -> "PulsarTestConfig":
+        if not overrides:
+            return self
+        unknown = set(overrides) - set(self.__dataclass_fields__)
+        if unknown:
+            raise ValueError(f"PulsarTestConfig 不支持的配置项: {sorted(unknown)}")
+        if "ignore_fields" in overrides:
+            overrides["ignore_fields"] = tuple(overrides["ignore_fields"])
+        return replace(self, **overrides)