tuner-testkit 4.0.0__py3-none-any.whl

tuner_testkit/__init__.py

@@ -0,0 +1,5 @@
+"""tuner-testkit — shared test runtime (db, api_test, page_test, recorders, DNA)."""
+
+from __future__ import annotations
+
+__version__ = "4.0.0"

tuner_testkit/action_words/__init__.py

@@ -0,0 +1,48 @@
+"""Action Words — 统一管理自动化测试资产的最小业务动作层。
+
+设计目标（见 docs/spec/action-words-syntax.md）：
+
+- 每个 action word 是一个独立可运行的业务动作（DB 造数 / DB 断言 /
+  接口请求 / 接口断言 / 页面操作 / 页面断言），入参经 pydantic 强类型
+  声明并带样例，可 CLI 一键执行，也可被 behave / pytest 步骤直接调用；
+- 接口类 word 只做冻结 ``packages/api_objects`` 资产的引用与编排，
+  不重复定义请求契约；
+- DB 类 word 统一走 ``tuner_testkit.db.DbClient``（经类元数据 ``datasource``
+  声明目标库），造数结果按表登记 ``cleanup``，供测试夹具精确清理。
+
+CLI::
+
+    uv run python -m tuner_testkit.action_words list
+    uv run python -m tuner_testkit.action_words describe <word_id>
+    uv run python -m tuner_testkit.action_words run <word_id> --params '{...}'
+    uv run python -m tuner_testkit.action_words catalog --out report/action_words_catalog.json
+"""
+from __future__ import annotations
+
+from tuner_testkit.action_words.base import (
+    ActionCategory,
+    ActionResult,
+    ActionWord,
+    TableRows,
+)
+from tuner_testkit.action_words.context import ActionContext
+from tuner_testkit.action_words.registry import (
+    discover,
+    export_catalog,
+    get,
+    list_all,
+    register,
+)
+
+__all__ = [
+    "ActionCategory",
+    "ActionContext",
+    "ActionResult",
+    "ActionWord",
+    "TableRows",
+    "discover",
+    "export_catalog",
+    "get",
+    "list_all",
+    "register",
+]

tuner_testkit/action_words/__main__.py

@@ -0,0 +1,111 @@
+"""Action Words CLI — 列出 / 查看 / 一键运行 / 导出目录。
+
+用法::
+
+    uv run python -m tuner_testkit.action_words list
+    uv run python -m tuner_testkit.action_words describe db_seed.create_example
+    uv run python -m tuner_testkit.action_words run db_seed.create_example --params "{...}"
+    uv run python -m tuner_testkit.action_words run db_seed.create_example --params-file p.json
+    uv run python -m tuner_testkit.action_words run db_seed.create_example --example
+    uv run python -m tuner_testkit.action_words catalog --out report/action_words_catalog.json
+
+``run`` 未提供 ``--params`` 时使用 ``{}``（即全部默认值）；``--example``
+使用 word 自带的 ``example_params`` 样例运行。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from tuner_testkit.action_words import ActionContext, export_catalog, get, list_all
+
+
+def _print_json(data: object) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2, default=str))
+
+
+def _cmd_list(_args: argparse.Namespace) -> int:
+    rows = [
+        {"word_id": cls.word_id, "name": cls.name, "category": str(cls.category)}
+        for cls in list_all()
+    ]
+    _print_json(rows)
+    return 0
+
+
+def _cmd_describe(args: argparse.Namespace) -> int:
+    _print_json(get(args.word_id).describe())
+    return 0
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    cls = get(args.word_id)
+    if args.example:
+        raw = dict(cls.example_params)
+    elif args.params_file:
+        raw = json.loads(Path(args.params_file).read_text(encoding="utf-8"))
+    else:
+        raw = json.loads(args.params or "{}")
+
+    with ActionContext(username=args.username, password=args.password) as ctx:
+        try:
+            result = cls(ctx).run_from_dict(raw)
+        except AssertionError as exc:
+            _print_json({"ok": False, "error": str(exc)})
+            return 1
+    _print_json(result.model_dump(mode="json"))
+    return 0 if result.ok else 1
+
+
+def _cmd_catalog(args: argparse.Namespace) -> int:
+    catalog = export_catalog()
+    if args.out:
+        out = Path(args.out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(
+            json.dumps(catalog, ensure_ascii=False, indent=2, default=str),
+            encoding="utf-8",
+        )
+        print(f"catalog written: {out} ({len(catalog)} words)")
+    else:
+        _print_json(catalog)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+
+    parser = argparse.ArgumentParser(prog="python -m tuner_testkit.action_words")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("list", help="列出全部已注册 action words")
+
+    p_desc = sub.add_parser("describe", help="查看某个 word 的元数据 / 入参 schema / 样例")
+    p_desc.add_argument("word_id")
+
+    p_run = sub.add_parser("run", help="一键运行某个 word")
+    p_run.add_argument("word_id")
+    p_run.add_argument("--params", help="JSON 入参字符串（默认 {}）")
+    p_run.add_argument("--params-file", help="JSON 入参文件路径")
+    p_run.add_argument("--example", action="store_true", help="使用 example_params 样例运行")
+    p_run.add_argument("--username", help="接口登录用户名（覆盖环境变量/配置）")
+    p_run.add_argument("--password", help="接口登录密码（覆盖环境变量/配置）")
+
+    p_cat = sub.add_parser("catalog", help="导出全量目录 JSON（平台化数据源）")
+    p_cat.add_argument("--out", help="输出文件路径；缺省打印到 stdout")
+
+    args = parser.parse_args(argv)
+    handlers = {
+        "list": _cmd_list,
+        "describe": _cmd_describe,
+        "run": _cmd_run,
+        "catalog": _cmd_catalog,
+    }
+    return handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tuner_testkit/action_words/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""action_words 内部共用工具（id 生成 / 随机业务值 / 批量插入 / API 辅助 / 轮询）。
+
+仅供 packages.action_words 内部使用；外部调用方请走各 action word 的
+``run`` / ``run_from_dict`` 入口。
+"""

tuner_testkit/action_words/_internal/api.py

@@ -0,0 +1,56 @@
+"""API 辅助 — 冻结 api_objects 的动态加载与登录换 token。
+
+登录资产模块由环境变量 ``TEST_LOGIN_API_MODULE`` /
+``TEST_LOGIN_API_ATTR`` 配置（默认未设置时明确报错），避免模板硬编码
+业务路由目录。含连字符的包路径（如 ``packages.api_objects.prod-api.login``）
+同样经 :func:`load_api` 按名加载。
+"""
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Any
+
+
+def load_api(module_path: str, attr: str) -> Any:
+    """按模块路径与属性名加载一个冻结的 APIModel 资产。"""
+    return getattr(importlib.import_module(module_path), attr)
+
+
+def login_token(username: str, password: str) -> str:
+    """调用冻结的 login 接口资产换取 bearer token。
+
+    配置（环境变量）：
+      - ``TEST_LOGIN_API_MODULE`` — 如 ``tuner_testkit.api_objects.auth_api.login``
+      - ``TEST_LOGIN_API_ATTR`` — 如 ``login_post_v1``（默认 ``login_post_v1``）
+    """
+    module = (os.getenv("TEST_LOGIN_API_MODULE") or "").strip()
+    attr = (os.getenv("TEST_LOGIN_API_ATTR") or "login_post_v1").strip()
+    if not module:
+        raise RuntimeError(
+            "未配置登录 API Object：请设置环境变量 TEST_LOGIN_API_MODULE "
+            "（及可选 TEST_LOGIN_API_ATTR），指向冻结的 login 资产；"
+            "或向 ActionContext 显式传入 bearer_token。"
+        )
+    login_model = load_api(module, attr)
+    resp = login_model.set_json({"username": username, "password": password}).execute()
+    token = _extract_token(resp)
+    if not token:
+        keys = sorted(resp.json.keys()) if isinstance(resp.json, dict) else type(resp.json)
+        raise RuntimeError(f"登录响应中未找到 token（响应顶层键: {keys}）")
+    return token
+
+
+def _extract_token(resp: Any) -> str | None:
+    payload = resp.json if isinstance(resp.json, dict) else {}
+    for candidate in (payload.get("token"), payload.get("access_token")):
+        if candidate:
+            return str(candidate)
+    data = payload.get("data")
+    if isinstance(data, dict):
+        for key in ("token", "access_token", "accessToken"):
+            if data.get(key):
+                return str(data[key])
+    if isinstance(data, str) and data:
+        return data
+    return None

tuner_testkit/action_words/_internal/db.py

@@ -0,0 +1,48 @@
+"""DB 造数共用原语 — 参数化批量 INSERT（多方言：SQL Server / MySQL / PostgreSQL）。
+
+注入安全说明：表名与列名是各 action word 模块内代码定义的常量（固定白名单），
+从不接受外部输入；只有**值**经 ``%s`` 占位符传递，因此拼接列名/占位符
+不构成注入面。
+
+方言说明：pymssql / pymysql / psycopg 参数风格同为 ``%s``，各库仅标识符引用
+不同（``[name]`` / `` `name` `` / ``"name"``）；``bulk_insert`` 从
+``client.dialect`` 自动选择，调用方无感。
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from tuner_testkit.db import DbClient
+
+
+def quote_ident(name: str, dialect: str = "mysql") -> str:
+    """Quote an identifier for the given SQL dialect."""
+    if dialect == "mysql":
+        return f"`{name}`"
+    if dialect == "postgresql":
+        return '"' + name.replace('"', '""') + '"'
+    return f"[{name}]"
+
+
+def insert_sql(table: str, columns: Sequence[str], dialect: str = "mysql") -> str:
+    cols = ", ".join(quote_ident(c, dialect) for c in columns)
+    placeholders = ", ".join(["%s"] * len(columns))
+    return f"INSERT INTO {quote_ident(table, dialect)} ({cols}) VALUES ({placeholders})"
+
+
+def bulk_insert(
+    client: DbClient,
+    table: str,
+    columns: Sequence[str],
+    rows: Sequence[Mapping[str, Any]],
+) -> int:
+    """将 ``rows`` 以参数化语句批量插入 ``table``。
+
+    每个 row dict 必须恰好包含 ``columns`` 中的键；值按列序取出后经
+    ``%s`` 占位符传递。标识符引用按 ``client.dialect`` 自动选择方言。
+    """
+    if not rows:
+        return 0
+    sql = insert_sql(table, columns, client.dialect)
+    params = [tuple(row[c] for c in columns) for row in rows]
+    return client.execute_many(sql, params)

tuner_testkit/action_words/_internal/generators.py

@@ -0,0 +1,37 @@
+"""Random / derived value generators for action words.
+
+Implementation lives in ``tuner_testkit.fake``. This module re-exports the
+historical names so ``from tuner_testkit.action_words._internal import generators``
+keeps working.
+"""
+from __future__ import annotations
+
+from tuner_testkit.fake import (
+    batch_number,
+    date_str,
+    digits,
+    doc_no,
+    money,
+    now,
+    now_str,
+    qty,
+    random_future_date,
+    random_past_date,
+    task_id,
+    today_str,
+)
+
+__all__ = [
+    "batch_number",
+    "date_str",
+    "digits",
+    "doc_no",
+    "money",
+    "now",
+    "now_str",
+    "qty",
+    "random_future_date",
+    "random_past_date",
+    "task_id",
+    "today_str",
+]

tuner_testkit/action_words/_internal/ids.py

@@ -0,0 +1,78 @@
+"""Client-side monotonic bigint id generation for data factories.
+
+Capacity-test injection needs to control parent/child ids *before* hitting the
+database so that a whole batch (parent rows + child rows) can be inserted with
+``executemany`` while keeping the foreign-key linkage correct. We therefore do
+not rely on MySQL ``auto_increment`` / ``lastrowid`` for linkage; instead we
+mint ids here with a small snowflake-style scheme::
+
+    id = (elapsed_ms << 20) | sequence
+
+- ``elapsed_ms`` is milliseconds since a fixed epoch (2025-01-01 UTC), so the
+  high bits keep increasing over time and stay comfortably inside MySQL
+  ``bigint`` range.
+- ``sequence`` is a 20-bit per-millisecond counter (up to 1,048,576 ids/ms);
+  when it overflows we spin to the next millisecond, so ids are strictly
+  monotonically increasing and unique within a process.
+
+The generated ids visually resemble the sample data (e.g.
+``2070119332155711489``) while remaining unique across a run.
+"""
+from __future__ import annotations
+
+import threading
+import time
+
+# Fixed epoch: 2025-01-01T00:00:00Z in milliseconds.
+_EPOCH_MS = 1_735_689_600_000
+_SEQ_BITS = 20
+_SEQ_MASK = (1 << _SEQ_BITS) - 1
+
+
+class IdGenerator:
+    """Thread-safe, strictly increasing bigint id generator."""
+
+    def __init__(self, *, epoch_ms: int = _EPOCH_MS) -> None:
+        self._epoch_ms = epoch_ms
+        self._lock = threading.Lock()
+        self._last_ms = -1
+        self._seq = 0
+
+    def _now_ms(self) -> int:
+        return int(time.time() * 1000) - self._epoch_ms
+
+    def next(self) -> int:
+        """Return the next unique, monotonically increasing bigint id."""
+        with self._lock:
+            now = self._now_ms()
+            if now == self._last_ms:
+                self._seq = (self._seq + 1) & _SEQ_MASK
+                if self._seq == 0:
+                    # Sequence exhausted within this ms: wait for the next ms.
+                    while now <= self._last_ms:
+                        now = self._now_ms()
+            else:
+                self._seq = 0
+            self._last_ms = now
+            return (now << _SEQ_BITS) | self._seq
+
+    def next_batch(self, n: int) -> list[int]:
+        """Return ``n`` unique ids in increasing order."""
+        if n < 0:
+            raise ValueError("n must be >= 0")
+        return [self.next() for _ in range(n)]
+
+
+# Process-wide default shared by all factories so a single run never collides
+# parent and child ids across different factory instances.
+default_id_generator = IdGenerator()
+
+
+def next_id() -> int:
+    """Convenience wrapper around the process-wide default generator."""
+    return default_id_generator.next()
+
+
+def next_ids(n: int) -> list[int]:
+    """Convenience wrapper returning ``n`` ids from the default generator."""
+    return default_id_generator.next_batch(n)

tuner_testkit/action_words/_internal/wait.py

@@ -0,0 +1,27 @@
+"""轮询等待 — 异步结果断言前的同步点。"""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+
+def wait_until(
+    check: Callable[[], tuple[bool, Any]],
+    *,
+    timeout: float = 90.0,
+    interval: float = 3.0,
+    desc: str = "",
+) -> Any:
+    """轮询 ``check`` 直到其返回 ``(True, value)``，超时抛 AssertionError。
+
+    ``check`` 返回 ``(ok, detail)``：ok 为 False 时 detail 用于超时报错定位。
+    """
+    deadline = time.monotonic() + timeout
+    detail: Any = None
+    while True:
+        ok, detail = check()
+        if ok:
+            return detail
+        if time.monotonic() >= deadline:
+            raise AssertionError(f"等待超时({timeout}s): {desc}；最后状态: {detail!r}")
+        time.sleep(interval)

tuner_testkit/action_words/base.py

@@ -0,0 +1,131 @@
+"""Action Word 基类与统一数据契约。
+
+Action Word 是本仓库测试资产的最小可复用业务动作单元，按类别覆盖
+DB 造数 / DB 断言 / 接口请求 / 接口断言 / 页面操作 / 页面断言六类工作。
+每个 action word 独立可运行（CLI 一键执行），也可被 behave 步骤或 pytest
+直接调用。
+
+模板规范（平台化契约，违反会被 registry 注册与模板一致性测试拦截）：
+
+- 子类必须有业务 docstring（描述业务含义、前置条件、副作用）；
+- 类元数据 ``word_id`` / ``name`` / ``category`` 必填；
+- 内嵌 ``Params``（pydantic BaseModel）：每个字段必须有类型声明与
+  ``Field(description=...)``，供平台以可视化表单展示；
+- ``example_params``：一份能通过 ``Params`` 校验、可直接运行的入参样例；
+- ``run(params)`` 为唯一执行入口；断言类 word 失败时抛 ``AssertionError``，
+  成功返回 ``Result``（含 ``detail`` 细节与造数类的 ``cleanup`` 清理登记）。
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import StrEnum
+from typing import Any, ClassVar, Mapping
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from tuner_testkit.action_words.context import ActionContext
+from tuner_testkit.db import DEFAULT_ALIAS, DbClient
+
+
+class ActionCategory(StrEnum):
+    """Action word 的工作类别（平台侧用于分组展示与运行策略）。"""
+
+    DB_SEED = "db_seed"          # DB 造数
+    DB_ASSERT = "db_assert"      # DB 断言
+    API_REQUEST = "api_request"  # 接口请求 / 编排
+    API_ASSERT = "api_assert"    # 接口断言
+    UI_ACTION = "ui_action"      # 页面操作（预留）
+    UI_ASSERT = "ui_assert"      # 页面断言（预留）
+
+
+class TableRows(BaseModel):
+    """一张表上本次动作产生的行 id，供调用方注册清理夹具后精确删除。"""
+
+    table: str = Field(description="表名")
+    ids: list[int] = Field(default_factory=list, description="行主键 id 列表")
+
+
+class ActionResult(BaseModel):
+    """所有 action word 的统一返回基类。
+
+    子类可以增加强类型的业务字段（如 ``invoice_nos``）；``detail`` 存放
+    人类可读的执行摘要，``cleanup`` 仅造数类 word 填写。
+    """
+
+    ok: bool = Field(True, description="动作是否成功")
+    detail: dict[str, Any] = Field(
+        default_factory=dict, description="人类可读的执行细节 / 摘要"
+    )
+    cleanup: list[TableRows] = Field(
+        default_factory=list,
+        description="造数产生的行按表登记，供测试夹具在场景结束后精确删除",
+    )
+
+
+class ActionWord(ABC):
+    """所有 action word 的抽象基类。见模块 docstring 的模板规范。"""
+
+    # ---- 类元数据（平台目录 / registry 索引） ----
+    word_id: ClassVar[str]
+    name: ClassVar[str]
+    category: ClassVar[ActionCategory]
+    tags: ClassVar[tuple[str, ...]] = ()
+    #: 依赖的环境资源："db" / "api"；ActionContext 按需惰性初始化
+    requires: ClassVar[frozenset[str]] = frozenset()
+    #: 目标数据源别名（config/env.py 的 ``DATABASES`` 键）。框架支持
+    #: MySQL / SQL Server / PostgreSQL 共存，DB 类 word 在此显式声明去影响哪个库
+    #: （如主业务在 "main"、第二库在 "sqlserver" / "postgres"），
+    #: 数据库具体类型只写在配置里。
+    datasource: ClassVar[str] = DEFAULT_ALIAS
+    #: 可直接运行的入参样例（必须能通过 Params 校验）
+    example_params: ClassVar[dict[str, Any]] = {}
+
+    class Params(BaseModel):
+        """入参契约；子类内嵌覆盖。未知键一律拒绝，避免拼写错误静默生效。"""
+
+        model_config = ConfigDict(extra="forbid")
+
+    class Result(ActionResult):
+        pass
+
+    def __init__(self, ctx: ActionContext | None = None) -> None:
+        self.ctx = ctx if ctx is not None else ActionContext()
+
+    @property
+    def db(self) -> DbClient:
+        """本 word 声明的目标数据源连接（``ctx.get_db(cls.datasource)``）。"""
+        return self.ctx.get_db(type(self).datasource)
+
+    @abstractmethod
+    def run(self, params: Params) -> ActionResult:
+        """执行动作。断言类失败抛 ``AssertionError``，其余异常按原样上抛。"""
+
+    def run_from_dict(self, raw: Mapping[str, Any] | None = None) -> ActionResult:
+        """统一接入点：dict 入参 → pydantic 校验 → :meth:`run`。
+
+        behave 步骤、pytest、CLI、未来平台的在线执行都走这一入口。
+        """
+        params = self.Params.model_validate(dict(raw or {}))
+        return self.run(params)
+
+    # ---- 平台化导出 ----
+
+    @classmethod
+    def params_schema(cls) -> dict[str, Any]:
+        """入参 JSON Schema（供平台渲染表单）。"""
+        return cls.Params.model_json_schema()
+
+    @classmethod
+    def describe(cls) -> dict[str, Any]:
+        """目录条目：元数据 + docstring + 入参 schema + 样例。"""
+        return {
+            "word_id": cls.word_id,
+            "name": cls.name,
+            "category": str(cls.category),
+            "tags": list(cls.tags),
+            "requires": sorted(cls.requires),
+            "datasource": cls.datasource,
+            "doc": (cls.__doc__ or "").strip(),
+            "params_schema": cls.params_schema(),
+            "example_params": cls.example_params,
+        }

tuner_testkit/action_words/context.py

@@ -0,0 +1,105 @@
+"""ActionContext — action word 运行所需环境资源的惰性容器。
+
+持有 DB 连接与 API 登录 token，按 word 的 ``requires`` 声明按需初始化：
+
+- ``get_db(alias)``: 按 ``config.env.DATABASES`` 中的命名数据源别名取
+  :class:`tuner_testkit.db.DbClient`，实例内按别名缓存（框架支持 MySQL /
+  SQL Server 共存，word 通过类元数据 ``datasource`` 声明目标库）；
+- ``db``: 默认别名（``main``）的便捷入口，等价 ``get_db(DEFAULT_ALIAS)``；
+- ``api_token``: 首次访问时通过可配置的登录 API Object 换取；凭据解析
+  顺序为 显式入参 > 环境变量 ``TEST_USERNAME`` / ``TEST_PASSWORD`` >
+  ``config.env.TEST_ACCOUNT``；behave 的 ``-D username/password`` 由
+  environment 钩子解析后显式传入。
+
+一个 behave scenario / 一次 CLI 运行对应一个 ActionContext 实例，
+token 与各别名的 DB 连接在实例内缓存。
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from tuner_testkit.db import DEFAULT_ALIAS, DbClient
+
+
+class ActionContext:
+    def __init__(
+        self,
+        *,
+        db: DbClient | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        bearer_token: str | None = None,
+    ) -> None:
+        # 别名 -> DbClient；外部注入的 db 挂在默认别名下，由注入方管理生命周期
+        self._dbs: dict[str, DbClient] = {}
+        self._injected_aliases: set[str] = set()
+        if db is not None:
+            self._dbs[DEFAULT_ALIAS] = db
+            self._injected_aliases.add(DEFAULT_ALIAS)
+        self._username = username
+        self._password = password
+        self._token = bearer_token
+
+    # ------------------------------------------------------------------
+    # DB
+    # ------------------------------------------------------------------
+
+    def get_db(self, alias: str = DEFAULT_ALIAS) -> DbClient:
+        """按命名数据源别名取 DbClient；未注入时首次访问惰性创建并缓存。"""
+        client = self._dbs.get(alias)
+        if client is None:
+            client = DbClient.for_datasource(alias)
+            self._dbs[alias] = client
+        return client
+
+    @property
+    def db(self) -> DbClient:
+        return self.get_db(DEFAULT_ALIAS)
+
+    # ------------------------------------------------------------------
+    # API 登录 token
+    # ------------------------------------------------------------------
+
+    @property
+    def api_token(self) -> str:
+        if self._token:
+            return self._token
+        username, password = self._resolve_credentials()
+        from tuner_testkit.action_words._internal.api import login_token
+
+        self._token = login_token(username, password)
+        return self._token
+
+    def _resolve_credentials(self) -> tuple[str, str]:
+        from tuner_testkit.config import load_project_env
+
+        env_config = load_project_env()
+
+        account: dict[str, Any] = getattr(env_config, "TEST_ACCOUNT", None) or {}
+        username = self._username or os.getenv("TEST_USERNAME") or account.get("username") or ""
+        password = self._password or os.getenv("TEST_PASSWORD") or account.get("password") or ""
+        if not username or not password:
+            raise RuntimeError(
+                "缺少登录凭据：请在 config/env.py 的 TEST_ACCOUNT 填入，"
+                "或通过 behave -D username=... -D password=...，"
+                "或环境变量 TEST_USERNAME / TEST_PASSWORD 提供"
+            )
+        return str(username), str(password)
+
+    # ------------------------------------------------------------------
+    # 生命周期
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """关闭自建的 DB 连接；外部注入的连接由注入方管理。"""
+        for alias, client in list(self._dbs.items()):
+            if alias not in self._injected_aliases:
+                client.close()
+                del self._dbs[alias]
+
+    def __enter__(self) -> "ActionContext":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()