pytest-platform-adapter 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

pytest_platform_adapter/plugin.py

@@ -1,12 +1,14 @@
 import asyncio
 import json
 import os
-from typing import List, Optional
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
 
 import requests
-from allure_pytest.utils import allure_title
+from allure_pytest.utils import allure_label, allure_title
 import logging
 import pytest
+from _pytest.stash import StashKey
 
 logger = logging.getLogger('pytest-platform-adapter')
 logger.setLevel(logging.INFO)
@@ -30,6 +32,45 @@ platform_path = None
 pipeline_name = None
 build_number = None
 platform_use_https = False
+ENV_SETTINGS_KEY: StashKey["EnvCheckSettings"] = StashKey()
+ENV_RUNTIME_KEY: StashKey["EnvCheckRuntime"] = StashKey()
+ITEM_KIND_KEY: StashKey[str] = StashKey()
+BEHAVIOR_KEY: StashKey[Optional[str]] = StashKey()
+ENV_XFAIL_REASON_KEY: StashKey[Optional[str]] = StashKey()
+FORCED_ITEMS_KEY: StashKey[List[pytest.Item]] = StashKey()
+STASH_SENTINEL = object()
+
+
+@dataclass
+class EnvCheckSettings:
+    mode: str = 'all'
+    behavior_scope: str = 'feature'
+    fail_action: str = 'skip'
+    collect_mode: str = 'force'  # force(强制)/auto(自动)
+    global_nodeids: List[str] = field(default_factory=list)
+    behavior_nodeids: List[str] = field(default_factory=list)
+
+    def enable_global(self) -> bool:
+        return self.mode in {'global', 'all'} and bool(self.global_nodeids)
+
+    def enable_behavior(self) -> bool:
+        return self.mode in {'behavior', 'all'} and bool(self.behavior_nodeids)
+
+    def enabled(self) -> bool:
+        if self.mode == 'off':
+            return False
+        return self.enable_global() or self.enable_behavior()
+
+
+@dataclass
+class EnvCheckRuntime:
+    global_failures: Dict[str, str] = field(default_factory=dict)
+    behavior_failures: Dict[str, str] = field(default_factory=dict)
+
+    def first_global_failure(self) -> Optional[str]:
+        if not self.global_failures:
+            return None
+        return next(iter(self.global_failures.values()))
 
 
 def pytest_addoption(parser):
@@ -52,6 +93,26 @@ def pytest_addoption(parser):
         default=False,
         help='扫描模式：快速生成 Allure 报告而不实际执行测试'
     )
+    group.addoption(
+        '--env-check-mode',
+        action='store',
+        default='all',
+        choices=['off', 'global', 'behavior', 'all'],
+        help='环境检查模式：off(禁用)/global(仅全局)/behavior(仅行为)/all(全部)'
+    )
+    group.addoption(
+        '--env-check-scope',
+        action='store',
+        default=None,
+        help='特性级检查所使用的 Allure 标签层级：epic/feature/story'
+    )
+    group.addoption(
+        '--env-check-collect-mode',
+        action='store',
+        default=None,
+        choices=['force', 'auto'],
+        help='环境检查收集模式覆盖：force(强制收集并执行)/auto(仅执行已收集到的检查用例)'
+    )
     parser.addini(
         'platform_ip',
         help='自动化平台API IP',
@@ -72,28 +133,79 @@ def pytest_addoption(parser):
         help='上报自动化平台时启用HTTPS，默认不启用',
         default=False
     )
+    parser.addini(
+        'platform_env_global_checks',
+        type='linelist',
+        help='全局环境检查用例的绝对NodeID列表',
+        default=[]
+    )
+    parser.addini(
+        'platform_env_behavior_checks',
+        type='linelist',
+        help='特性级环境检查用例的绝对NodeID列表',
+        default=[]
+    )
+    parser.addini(
+        'platform_env_behavior_scope',
+        help='特性级检查的Allure层级（epic/feature/story）',
+        default='feature'
+    )
+    parser.addini(
+        'platform_env_fail_action',
+        help='环境检查失败后对业务用例的处理方式（skip/xfail/none）',
+        default='skip'
+    )
+    parser.addini(
+        'platform_env_collect_mode',
+        help='环境检查收集模式：force(强制收集并执行)/auto(仅执行已收集到的检查用例)',
+        default='force'
+    )
 
-
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
 def pytest_collection_modifyitems(config, items):
     """
     hook收集用例的过程，给--case_ids和--case_ids_file提供支持
     修改测试用例集合，根据提供的测试用例ID过滤测试用例
     """
+    settings = get_env_settings(config)
+    forced_nodeids = _collect_forced_nodeids(settings)
+    # 预先快照强制环境检查用例，供后续无视 -m / -k 过滤使用。
+    if env_checks_enabled(settings) and settings.collect_mode == 'force':
+        forced_items: List[pytest.Item] = []
+        seen: Set[str] = set()
+        for item in items:
+            if _is_forced_item(item.nodeid, forced_nodeids) and item.nodeid not in seen:
+                forced_items.append(item)
+                seen.add(item.nodeid)
+        config.stash[FORCED_ITEMS_KEY] = forced_items
+    yield
+    # 缺失检查告警：force 模式下使用 pre-deselect 的快照判断，避免被 -m/-k 误判。
+    if env_checks_enabled(settings) and settings.collect_mode == 'force':
+        forced_items_snapshot = config.stash.get(FORCED_ITEMS_KEY, [])
+        available_ids = {item.nodeid for item in forced_items_snapshot}
+    else:
+        available_ids = {item.nodeid for item in items}
+    missing_forced: List[str] = []
+    for prefix in forced_nodeids:
+        if not any(n == prefix or n.startswith(prefix + "::") for n in available_ids):
+            missing_forced.append(prefix)
+    for missing in sorted(missing_forced):
+        logger.warning(f"配置的环境检查用例 {missing} 未被收集，检查 NodeID 是否正确")
+
     target_ids = get_target_test_ids(config)
-    if not target_ids:
-        test_stats['total'] = len(items)  # 更新总用例数
-        return
     selected = []
     deselected = []
     for item in items:
+        nodeid = item.nodeid
+        should_force_run = _is_forced_item(nodeid, forced_nodeids)
         title = allure_title(item)
         test_id = get_test_id_from_title(title)
-        if test_id in target_ids:
+        if not target_ids or should_force_run or test_id in target_ids:
             selected.append(item)
         else:
             deselected.append(item)
-        # 检测 ID 是否有重复，只是单纯的检查一下，不影响执行
-        if test_id in cases_ids:
+        # 检测 ID 是否有重复，只是单纯的检查一下，不影响执行。用例 id 为 1 的是环境检查脚本
+        if test_id in cases_ids and test_id != "0":
             # 为 None 在这里就不用打印log了，因为在 get_test_id_from_title 里面就会报错一次
             if test_id is None:
                 continue
@@ -102,11 +214,24 @@ def pytest_collection_modifyitems(config, items):
             cases_ids.add(test_id)
     if deselected:
         config.hook.pytest_deselected(items=deselected)
-        items[:] = selected
-    selected_ids = [get_test_id_from_title(allure_title(item)) for item in selected]
-    test_stats['total'] = len(selected)  # 更新总用例数
-    logger.info("目标测试用例ID (%d个): %s", len(target_ids), target_ids)
-    logger.info("实际执行用例ID (%d个): %s", len(selected_ids), selected_ids)
+    items[:] = selected
+
+    # force 模式下无视 -m / -k 的 deselect：把缓存的环境检查重新插回来
+    if env_checks_enabled(settings) and settings.collect_mode == 'force':
+        forced_items = config.stash.get(FORCED_ITEMS_KEY, [])
+        current_ids = {item.nodeid for item in items}
+        for forced_item in forced_items:
+            if forced_item.nodeid not in current_ids:
+                items.append(forced_item)
+                current_ids.add(forced_item.nodeid)
+
+    selected_ids = [get_test_id_from_title(allure_title(item)) for item in items]
+    test_stats['total'] = len(items)  # 更新总用例数
+    if target_ids:
+        logger.info("目标测试用例ID (%d个): %s", len(target_ids), target_ids)
+        logger.info("实际执行用例ID (%d个): %s", len(selected_ids), selected_ids)
+    if env_checks_enabled(settings):
+        _apply_env_check_collection_logic(config, settings, items)
 
 
 @pytest.hookimpl(hookwrapper=True)
@@ -122,6 +247,18 @@ def pytest_runtest_setup(item):
     if item.config.getoption('--scan'):
         # logger.info(f"扫描模式：跳过测试用例 {allure_title(item)}前置")
         pytest.skip("扫描模式已启动，跳过测试用例前置")
+    settings = get_env_settings(item.config)
+    if env_checks_enabled(settings):
+        runtime = get_env_runtime(item.config)
+        kind = _get_item_kind(item)
+        global_reason = runtime.first_global_failure()
+        if global_reason and kind != 'global_check':
+                _apply_env_failure_action(settings, item, global_reason)
+        elif kind == 'business':
+            behavior = _ensure_behavior_stashed(item, settings.behavior_scope)
+            behavior_reason = runtime.behavior_failures.get(behavior) if behavior else None
+            if behavior_reason:
+                _apply_env_failure_action(settings, item, behavior_reason)
     yield
 
 
@@ -133,6 +270,39 @@ def pytest_runtest_teardown(item):
     yield
 
 
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    report = outcome.get_result()
+    settings = get_env_settings(item.config)
+    if not env_checks_enabled(settings):
+        return
+    if report.when != 'call':
+        return
+    kind = _get_item_kind(item)
+    if kind not in {'global_check', 'behavior_check'}:
+        return
+    runtime = get_env_runtime(item.config)
+    if report.failed:
+        reason = _format_env_failure_message(kind, item, report)
+        if kind == 'global_check':
+            runtime.global_failures[item.nodeid] = reason
+        else:
+            behavior = _ensure_behavior_stashed(item, settings.behavior_scope)
+            if behavior:
+                runtime.behavior_failures[behavior] = reason
+            else:
+                logger.warning("特性级环境检查 %s 缺少 %s 标签，无法绑定到具体行为", item.nodeid,
+                               settings.behavior_scope)
+    else:
+        if kind == 'global_check':
+            runtime.global_failures.pop(item.nodeid, None)
+        else:
+            behavior = _ensure_behavior_stashed(item, settings.behavior_scope)
+            if behavior:
+                runtime.behavior_failures.pop(behavior, None)
+
+
 @pytest.hookimpl
 def pytest_runtest_logreport(report):
     """
@@ -209,6 +379,35 @@ def pytest_configure(config):
     scan_enable, platform_ip, platform_port, platform_path, platform_use_https = config.getoption(
         '--scan'), config.getini('platform_ip'), config.getini('platform_port'), config.getini(
         'platform_path'), config.getini('platform_use_https')
+    settings = build_env_check_settings(config)
+    config.stash[ENV_SETTINGS_KEY] = settings
+    config.stash[ENV_RUNTIME_KEY] = EnvCheckRuntime()
+    # 在强制模式下，将声明的环境检查 NodeID 注入到 pytest 收集参数中，
+    # 以保证即使用户只选择了业务目录也能收集到检查用例。
+    if env_checks_enabled(settings) and settings.collect_mode == 'force':
+        try:
+            from pathlib import Path
+
+            existing_args = set(config.args or [])
+            rootpath = getattr(config, "rootpath", Path.cwd())
+            forced_args: List[str] = []
+            for nodeid in _collect_forced_nodeids(settings):
+                if nodeid in existing_args:
+                    continue
+                # 仅对文件路径存在的 NodeID 进行注入，避免明显的 not found。
+                path_part = nodeid.split("::", 1)[0]
+                p = Path(path_part)
+                if not p.is_absolute():
+                    p = rootpath / p
+                if p.exists():
+                    forced_args.append(nodeid)
+                else:
+                    logger.warning("强制收集环境检查失败：文件不存在 %s", nodeid)
+            if forced_args:
+                config.args.extend(forced_args)
+                logger.debug("已强制注入环境检查收集参数: %s", forced_args)
+        except Exception as e:
+            logger.warning("强制收集环境检查参数注入异常：%s", e)
     pipeline_name = os.environ.get("JOB_NAME")
     build_number = os.environ.get("BUILD_NUMBER")
     handler = logging.StreamHandler()
@@ -220,6 +419,10 @@ def pytest_configure(config):
         "markers",
         "allure_title: 使用allure标题标记测试用例"
     )
+    config.addinivalue_line(
+        "markers",
+        "environment_check: 标记环境检查用例"
+    )
 
 
 def get_test_ids_from_file(file_path: str) -> List[str]:
@@ -263,3 +466,203 @@ def get_test_id_from_title(title: Optional[str]) -> Optional[str]:
     else:
         logger.error(f'存在无法解析用例ID的用例，用例标题为：{title}')
         return None
+
+
+def build_env_check_settings(config) -> EnvCheckSettings:
+    mode = config.getoption('--env-check-mode') or 'all'
+    scope_opt = config.getoption('--env-check-scope')
+    scope_ini = config.getini('platform_env_behavior_scope') or 'feature'
+    scope = (scope_opt or scope_ini or 'feature').strip().lower()
+    if scope not in {'epic', 'feature', 'story'}:
+        logger.warning("未识别的行为层级 %s，回退到 feature", scope)
+        scope = 'feature'
+    fail_action_raw = config.getini('platform_env_fail_action')
+    fail_action = (fail_action_raw or 'skip').strip().lower()
+    if fail_action not in {'skip', 'xfail', 'none'}:
+        logger.warning("platform_env_fail_action=%s 不受支持，改用 skip", fail_action_raw)
+        fail_action = 'skip'
+    collect_mode_opt = config.getoption('--env-check-collect-mode')
+    collect_mode_raw = collect_mode_opt or config.getini('platform_env_collect_mode')
+    collect_mode = (collect_mode_raw or 'force').strip().lower()
+    if collect_mode in {'强制'}:
+        collect_mode = 'force'
+    elif collect_mode in {'自动'}:
+        collect_mode = 'auto'
+    if collect_mode not in {'force', 'auto'}:
+        logger.warning("platform_env_collect_mode=%s 不受支持，改用 force", collect_mode_raw)
+        collect_mode = 'force'
+    global_nodes = _normalize_nodeids(config.getini('platform_env_global_checks'))
+    behavior_nodes = _normalize_nodeids(config.getini('platform_env_behavior_checks'))
+    if mode not in {'off', 'global', 'behavior', 'all'}:
+        logger.warning("未识别的 env-check-mode %s，回退到 all", mode)
+        mode = 'all'
+    return EnvCheckSettings(
+        mode=mode,
+        behavior_scope=scope,
+        fail_action=fail_action,
+        collect_mode=collect_mode,
+        global_nodeids=global_nodes,
+        behavior_nodeids=behavior_nodes,
+    )
+
+
+def env_checks_enabled(settings: Optional[EnvCheckSettings]) -> bool:
+    return bool(settings and settings.enabled())
+
+
+def _normalize_nodeids(values: Optional[List[str]]) -> List[str]:
+    if not values:
+        return []
+    normalized = []
+    for nodeid in values:
+        if not nodeid:
+            continue
+        value = nodeid.strip()
+        if value:
+            normalized.append(value)
+    return normalized
+
+
+def get_env_settings(config) -> EnvCheckSettings:
+    return config.stash.get(ENV_SETTINGS_KEY, EnvCheckSettings())
+
+
+def get_env_runtime(config) -> EnvCheckRuntime:
+    return config.stash.get(ENV_RUNTIME_KEY, EnvCheckRuntime())
+
+
+def _collect_forced_nodeids(settings: Optional[EnvCheckSettings]) -> Set[str]:
+    if not env_checks_enabled(settings):
+        return set()
+    forced = set()
+    if settings.enable_global():
+        forced.update(settings.global_nodeids)
+    if settings.enable_behavior():
+        forced.update(settings.behavior_nodeids)
+    return forced
+
+
+def _is_forced_item(nodeid: str, forced_nodeids: Set[str]) -> bool:
+    """支持用父级 NodeID（如模块/类）声明的强制收集。"""
+    if nodeid in forced_nodeids:
+        return True
+    for forced in forced_nodeids:
+        if nodeid.startswith(forced + "::"):
+            return True
+    return False
+
+
+def _apply_env_check_collection_logic(config, settings: EnvCheckSettings, items: List[pytest.Item]) -> None:
+    ordered: List[pytest.Item] = []
+    consumed: Set[str] = set()
+    missing_behaviors: List[str] = []
+
+    # 1) 全局检查：支持使用模块/类 NodeID 作为前缀声明。
+    for prefix in settings.global_nodeids:
+        for item in items:
+            if item.nodeid in consumed:
+                continue
+            if item.nodeid == prefix or item.nodeid.startswith(prefix + "::"):
+                ordered.append(item)
+                consumed.add(item.nodeid)
+                item.stash[ITEM_KIND_KEY] = 'global_check'
+                item.stash[BEHAVIOR_KEY] = None
+
+    # 2) 特性级检查：同样支持前缀声明，按行为（epic/feature/story）绑定。
+    behavior_checks: Dict[str, pytest.Item] = {}
+    for prefix in settings.behavior_nodeids:
+        for item in items:
+            if item.nodeid in consumed:
+                continue
+            if item.nodeid != prefix and not item.nodeid.startswith(prefix + "::"):
+                continue
+            behavior = _ensure_behavior_stashed(item, settings.behavior_scope)
+            if not behavior:
+                missing_behaviors.append(item.nodeid)
+                continue
+            if behavior in behavior_checks:
+                logger.warning(
+                    "特性级检查 %s 重复定义，沿用首次声明的用例 %s",
+                    behavior,
+                    behavior_checks[behavior].nodeid,
+                )
+                continue
+            behavior_checks[behavior] = item
+            consumed.add(item.nodeid)
+            item.stash[ITEM_KIND_KEY] = 'behavior_check'
+
+    if missing_behaviors:
+        logger.warning(
+            "下列特性级检查缺少 %s 标签：%s",
+            settings.behavior_scope,
+            missing_behaviors,
+        )
+
+    # 3) 按业务用例的行为插入对应检查。
+    behavior_inserted: Set[str] = set()
+    for item in items:
+        if item.nodeid in consumed:
+            continue
+        if item.stash.get(ITEM_KIND_KEY, STASH_SENTINEL) is STASH_SENTINEL:
+            item.stash[ITEM_KIND_KEY] = 'business'
+        behavior = _ensure_behavior_stashed(item, settings.behavior_scope)
+        if behavior and behavior in behavior_checks and behavior not in behavior_inserted:
+            ordered.append(behavior_checks[behavior])
+            behavior_inserted.add(behavior)
+        ordered.append(item)
+
+    # 4) 未匹配到业务用例的特性级检查：force 模式下不执行；auto 模式保持原行为（放到末尾执行）。
+    if settings.collect_mode != 'force':
+        for behavior, check_item in behavior_checks.items():
+            if behavior not in behavior_inserted:
+                ordered.append(check_item)
+                behavior_inserted.add(behavior)
+
+    if ordered:
+        items[:] = ordered
+    logger.debug(
+        "最终的环境检查执行顺序: %s",
+        [item.nodeid for item in items],
+    )
+
+
+def _ensure_behavior_stashed(item: pytest.Item, scope: str) -> Optional[str]:
+    behavior = item.stash.get(BEHAVIOR_KEY, STASH_SENTINEL)
+    if behavior is not STASH_SENTINEL:
+        return behavior
+    labels = allure_label(item, scope) or []
+    value = labels[0] if labels else None
+    item.stash[BEHAVIOR_KEY] = value
+    return value
+
+
+def _get_item_kind(item: pytest.Item) -> Optional[str]:
+    return item.stash.get(ITEM_KIND_KEY, None)
+
+
+def _apply_env_failure_action(settings: EnvCheckSettings, item: pytest.Item, reason: str) -> None:
+    if settings.fail_action == 'none':
+        return
+    if settings.fail_action == 'xfail':
+        _mark_item_expected_failure(item, reason)
+        return
+    pytest.skip(reason)
+
+
+def _mark_item_expected_failure(item: pytest.Item, reason: str) -> None:
+    existing = item.stash.get(ENV_XFAIL_REASON_KEY, None)
+    if existing:
+        return
+    item.add_marker(pytest.mark.xfail(reason=reason, run=True, strict=False))
+    item.stash[ENV_XFAIL_REASON_KEY] = reason
+
+
+def _format_env_failure_message(kind: str, item: pytest.Item, report: pytest.TestReport) -> str:
+    prefix = "全局" if kind == 'global_check' else "特性级"
+    detail = ""
+    longrepr = getattr(report, "longreprtext", "")
+    if longrepr:
+        first_line = longrepr.strip().splitlines()[0]
+        if first_line:
+            detail = f": {first_line}"
+    return f"{prefix}环境检查失败（{item.nodeid}）{detail}"

{pytest_platform_adapter-1.0.0.dist-info → pytest_platform_adapter-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: pytest_platform_adapter
-Version: 1.0.0
+Version: 1.2.0
 Summary: Pytest集成自动化平台插件
 Author-email: BlackYau <blackyau426@gmail.com>
 Maintainer-email: BlackYau <blackyau426@gmail.com>
@@ -32,6 +32,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pytest>=6.2.5
 Requires-Dist: allure-pytest>=2.9.45
+Dynamic: license-file
 
 # pytest-platform-adapter
 
@@ -47,6 +48,7 @@ Pytest集成自动化平台插件
 - 根据用例 `allure.title` 中的 ID 筛选执行的用例
 - 跳过所有用例的执行，快速生成 Allure 报告
 - 周期性的通过 RESTApi 上报执行用例的整体进度
+- 在执行前插入全局 / 特性级环境检查用例，失败时可批量 skip/xfail 后续业务用例
 
 ## 环境依赖
 
@@ -56,12 +58,52 @@ Pytest集成自动化平台插件
 
 ## 安装
 
+### 在线安装
+
+#### 官网在线安装
+
 执行以下命令即可完成安装
 
 ```shell
 pip install pytest-platform-adapter
 ```
 
+#### 国内镜像站在线安装
+
+如果安装遇到网络相关问题，也可以使用临时使用清华大学 PyPI 源安装本插件，安装命令如下：
+
+```shell
+pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple pytest-platform-adapter
+```
+
+### 离线安装
+
+#### 官网下载离线安装
+
+前往 PyPI 官网中的 pytest-platform-adapter 项目文件下载界面 https://pypi.org/project/pytest-platform-adapter/#files
+
+下载最新的 Built Distribution（构建发布版本），例如：`pytest_platform_adapter-x.x.x-py3-none-any.whl` 传输到需要离线安装的环境上
+
+然后在命令行中使用以下命令安装（你需要提前安装 `pytest` 和 `allure-pytest`）
+
+```
+# 需要把下面的 x.x.x 替换为实际的版本号
+pip install pytest_platform_adapter-x.x.x-py3-none-any.whl
+```
+
+#### 国内镜像站下载离线安装
+
+前往清华大学 PyPI 源本插件的下载文件页 https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/pytest-platform-adapter/
+
+下载最新（版本号最大）的扩展名为 `.whl` 的构建发布版本文件，例如：`pytest_platform_adapter-x.x.x-py3-none-any.whl` 传输到需要离线安装的环境上
+
+然后在命令行中使用以下命令安装（你需要提前安装 `pytest` 和 `allure-pytest`）
+
+```
+# 需要把下面的 x.x.x 替换为实际的版本号
+pip install pytest_platform_adapter-x.x.x-py3-none-any.whl
+```
+
 ## 使用方法
 
 ### 根据 Allure title 中的 ID 筛选用例
@@ -137,6 +179,42 @@ platform_use_https = False
 
 其中 `JOB_NAME` 和 `BUILD_NUMBER` 是通过环境变量获取的。
 
+### 环境检查
+
+环境检查由额外的 pytest 用例构成，通过配置它们的 NodeID 可以在收集阶段将这些用例插入到业务用例之前执行。可同时启用“全局检查”和“特性级检查”。
+
+#### 配置项-推荐
+
+在 `pytest.ini` 中添加以下内容：
+
+```ini
+[pytest]
+platform_env_global_checks =
+    tests/env_check/test_global_env_check.py::TestGlobalEnvCheck
+platform_env_behavior_checks =
+    tests/env_check/test_function_env_check.py::TestFunctionEnvCheck
+platform_env_behavior_scope = epic     # epic / feature / story
+platform_env_fail_action = skip        # skip / xfail / none
+platform_env_collect_mode = force      # force / auto
+```
+
+- `platform_env_global_checks`：在每次用例执行前跑一遍的检查用例列表。
+- `platform_env_behavior_checks`：特性级检查用例列表，插件会读取这些用例标签并在同一特性的首个用例前插入执行。
+- `platform_env_behavior_scope`：定义特性的级别可选的有 epic/feature/story（分别对应 Allure Report 的 behaviors 中的一级目录、二级目录、三级目录）
+- `platform_env_fail_action`：检查失败后对后续业务用例的处理方式，`skip` 为直接跳过、`xfail` 为继续执行并动态加上 `xfail`（失败记为 XFAIL、通过记为 XPASS）、`none` 仅记录日志不干预执行。
+- `platform_env_collect_mode`：环境检查收集模式，默认 `force`。
+  - `force`（强制）：即使本次命令行只收集了业务目录，也会强制把 `platform_env_global_checks` / `platform_env_behavior_checks` 声明的 NodeID 注入收集范围；环境检查用例不受 `-m`/`-k` 等筛选影响永远执行；全局检查永远执行；特性级检查仅在本次业务用例中存在同一行为标签（scope 对应 epic/feature/story）的情况下才执行，没有匹配的特性级检查不会执行。
+  - `auto`（自动）：不额外注入收集参数，仅执行本次 pytest 收集到的检查用例；如果声明的 NodeID 没有被收集到则不会执行。
+
+#### 命令行
+
+- `--env-check-mode={off,global,behavior,all}`：快速控制启用的检查范围。
+- `--env-check-scope=<epic|feature|story>`：临时覆盖行为层级设定。
+- `--env-check-collect-mode={force,auto}`：临时覆盖 `platform_env_collect_mode`，控制环境检查的收集/执行策略。
+- 当 `platform_env_fail_action=xfail` 时，会在受影响的业务用例上自动添加 `pytest.mark.xfail(run=True, strict=False)`，用例依旧执行，只是失败时记为 XFAIL。
+
+当检查用例失败时，插件会在 `pytest_runtest_setup` 阶段统一对后续业务用例执行 `skip` 或 `xfail`，并在日志中说明对应的检查节点。检查用例自身依旧遵循 pytest 原生语义，可继续使用 `skip/xfail/flaky` 等标记。
+
 
 ## 调试方法
 

pytest_platform_adapter-1.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_platform_adapter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_platform_adapter/plugin.py,sha256=QvKwWrlxDuZ8GMNjZ-bHP4FIEFO5kd86U4e0OBPoRRw,26634
+pytest_platform_adapter-1.2.0.dist-info/licenses/LICENSE,sha256=QOkNlcvUHENY86LE8OEpmtwMM24v76pgF4FmkEk8aXI,1064
+pytest_platform_adapter-1.2.0.dist-info/METADATA,sha256=d7lMZYTmi9Zp1x5KgsbTubTfmBFE7VCYSShJkpRuCvg,11429
+pytest_platform_adapter-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pytest_platform_adapter-1.2.0.dist-info/entry_points.txt,sha256=VorMHllVSkGNUUsVJOCrDMeW0-oLco5XcrmdfxND48c,61
+pytest_platform_adapter-1.2.0.dist-info/top_level.txt,sha256=OnTaKf7GCc7yqBHQ4H2XLK8PAz7oHslUZKEsd1t5BpA,24
+pytest_platform_adapter-1.2.0.dist-info/RECORD,,

{pytest_platform_adapter-1.0.0.dist-info → pytest_platform_adapter-1.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pytest_platform_adapter-1.0.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-pytest_platform_adapter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pytest_platform_adapter/plugin.py,sha256=xNdbIscIhajhfe4EJOvdNw2psrjrTV-uofdCCSlOJZU,10336
-pytest_platform_adapter-1.0.0.dist-info/LICENSE,sha256=QOkNlcvUHENY86LE8OEpmtwMM24v76pgF4FmkEk8aXI,1064
-pytest_platform_adapter-1.0.0.dist-info/METADATA,sha256=afNaCFnL1KfaykAo8e3V7Y3rQY4AOAc1tC49iiiecRE,7010
-pytest_platform_adapter-1.0.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-pytest_platform_adapter-1.0.0.dist-info/entry_points.txt,sha256=VorMHllVSkGNUUsVJOCrDMeW0-oLco5XcrmdfxND48c,61
-pytest_platform_adapter-1.0.0.dist-info/top_level.txt,sha256=OnTaKf7GCc7yqBHQ4H2XLK8PAz7oHslUZKEsd1t5BpA,24
-pytest_platform_adapter-1.0.0.dist-info/RECORD,,