df-test-framework 4.10.1__tar.gz → 4.10.2__tar.gz

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/.github/workflows/release.yml

@@ -113,6 +113,7 @@ jobs:
         aes = aes_encrypt("验收", key=key, mode="ECB")
         assert aes_decrypt(aes, key=key, mode="ECB") == "验收"
         PY
+        "$RUNNER_TEMP/release-smoke/bin/python" -I "$GITHUB_WORKSPACE/scripts/smoke_config_release.py" "$EXPECTED"
 
     - name: 上传构建产物
       uses: actions/upload-artifact@v4

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/.github/workflows/test.yml

@@ -160,7 +160,7 @@ jobs:
         uv run df-test init api-test-project --type api
         test -f api-test-project/pyproject.toml
         test -f api-test-project/config/base.yaml
-        test -f api-test-project/config/secrets/.env.local.example
+        test -f api-test-project/config/secrets/.env.test.example
         # v4.9.5: 最小骨架 + 类型真裁剪
         test -f api-test-project/src/api_test_project/apis/example_api.py
         test -f api-test-project/src/api_test_project/clients/http_clients.py
@@ -178,7 +178,7 @@ jobs:
       run: |
         uv run df-test init ui-test-project --type ui
         test -f ui-test-project/pyproject.toml
-        test -f ui-test-project/config/secrets/.env.local.example
+        test -f ui-test-project/config/secrets/.env.test.example
         # v4.9.5: 最小骨架 + 类型真裁剪
         test -f ui-test-project/src/ui_test_project/actions/example_actions.py
         test -f ui-test-project/src/ui_test_project/pages/example_page.py

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

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/CHANGELOG.md

@@ -7,6 +7,20 @@
 
 ## [Unreleased]
 
+## [4.10.2] - 2026-10-10
+
+### 配置按环境隔离（破坏性配置迁移，维护者指定 PATCH）
+
+- secrets 改用共享 `.env` 和环境专属 `.env.{env}`；本机 YAML 改为
+  `{env}.local.yaml`，通过 pytest/CLI `--local` 或 API `local=True` 显式启用。
+- 环境名支持受字符约束的自定义名称，显式环境身份不受文件或进程变量再次覆盖；
+  缓存按实际环境与覆盖开关区分，pytest 不再改写进程 ENV。
+- `_extends` 对所有 YAML 层按声明文件目录解析；写坏的 YAML、循环、缺失引用报错，
+  普通可选文件缺省仍可只用 base 或默认值运行。
+- 自定义环境可声明 `production: true`，统一生产守卫；prod/production 不可解除保护。
+- 迁移原 test 调试文件为 `test.local.yaml`、`.env.test`，命令改为
+  `--env=test --local`；无历史文件告警或 doctor 失败规则。模板、指南和来源诊断同步。
+
 ## [4.10.1] - 2026-09-29
 
 ### 发布配套

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

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: df-test-framework
-Version: 4.10.1
+Version: 4.10.2
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Author-email: DF QA Team <qa@example.com>
 License: MIT

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/README.md

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

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/ESSENTIAL_DOCS.md

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

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/FAQ.md

@@ -179,19 +179,19 @@ my-project/
 ├── config/
 │   ├── base.yaml              # 基础配置（所有环境共享）
 │   ├── environments/
-│   │   ├── local.yaml         # 本地开发环境
+│   │   ├── test.local.yaml    # --local 显式启用的本机覆盖
 │   │   ├── dev.yaml           # 开发环境
 │   │   ├── test.yaml          # 测试环境
 │   │   ├── staging.yaml       # 预发布环境
 │   │   └── prod.yaml          # 生产环境
 │   └── secrets/               # 敏感配置（已 .gitignore）
-│       └── .env.local         # 本地敏感配置
+│       └── .env.test          # test 环境敏感配置
 └── tests/
 ```
 
 **配置优先级**（从高到低）：
 1. 环境变量（最高优先级）
-2. `config/secrets/.env.local`
+2. `config/secrets/.env.test`
 3. `config/environments/{env}.yaml`
 4. `config/base.yaml`
 5. `.env` + `.env.{env}`（回退模式）
@@ -245,7 +245,7 @@ export DB__DATABASE="test_db"
 
 **敏感信息**（密码）：
 ```bash
-# config/secrets/.env.local
+# config/secrets/.env.test
 DB_PASSWORD=your_secret_password
 ```
 

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/README.md

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

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/architecture/TEST_EXECUTION_LIFECYCLE.md

@@ -60,7 +60,7 @@ Hook 执行顺序由 `@pytest.hookimpl(tryfirst/trylast)` 控制：env_plugin
 
 ```
 1. 环境变量（OBSERVABILITY__DEBUG_OUTPUT=true，双下划线嵌套）
-2. Secrets 文件（config/secrets/.env.local）
+2. Secrets 文件（config/secrets/.env.test）
 3. 环境 YAML（config/environments/{env}.yaml，支持 _extends 继承链）
 4. 基础 YAML（config/base.yaml）
 5. .env 文件（回退模式）

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/development/RELEASE.md

@@ -34,6 +34,8 @@ uv run --no-sync python scripts/check_release.py X.Y.Z
 本地构建用 `uvx --from build pyproject-build --outdir <本次新建空目录>`，
 再用 `uvx twine check <产物文件>` 检查；不要混入历史 dist。
 独立虚拟环境安装 wheel，从仓库外核验版本、CLI 与受影响公共入口。
+配置与三类脚手架可用该环境的 Python 执行
+`-I <仓库绝对路径>/scripts/smoke_config_release.py X.Y.Z` 验收。
 源码测试通过不代表打包清单或 extras 正确。
 
 模板变更运行 `tests/cli/test_init_cmd.py`，覆盖三类型结构、AST、导入和生成物 Ruff。

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/development/local-development.md

@@ -282,7 +282,7 @@ def test_problematic_feature(http_client):
 pytest tests/ -v -s --log-cli-level=DEBUG
 
 # 使用 local 环境配置（包含 DEBUG 日志设置）
-pytest tests/ --env=local --log-cli-level=DEBUG -v -s
+pytest tests/ --env=test --local --log-cli-level=DEBUG -v -s
 ```
 
 > 详细的日志和调试配置请参考 [本地开发调试快速指南](../guides/local_debug_quickstart.md)

df_test_framework-4.10.2/docs/guides/config_guide.md

@@ -0,0 +1,173 @@
+# 配置系统使用指南
+
+配置分为共用默认值、目标环境差异、本机覆盖和凭据。一次环境选择决定对应文件；
+本机 YAML 覆盖通过 `--local` 显式启用。
+
+## 目录与职责
+
+```text
+config/
+├── base.yaml
+├── environments/
+│   ├── test.yaml
+│   ├── staging.yaml
+│   └── test.local.yaml             # 可选，不提交
+└── secrets/
+    ├── .env                        # 可选，共用值，不提交
+    ├── .env.test                   # 可选，test 凭据，不提交
+    └── .env.staging                # 可选，staging 凭据，不提交
+```
+
+`base.yaml` 保存超时、重试、日志、客户端注册等共用值；`{env}.yaml` 保存服务地址、
+数据库名和环境开关。`{env}.local.yaml` 保存本机隧道地址、DEBUG、有头浏览器等覆盖。
+凭据文件按环境自动读取，与 `--local` 无关。共享 `secrets/.env` 的值参与所有环境，
+仅放确实通用的项，环境专属写入开关和凭据放 `.env.{env}`。
+
+所有文件都可缺省，由已存在的层或模型默认值补齐。写入文件后，语法必须有效。
+`.yaml` 也支持 `.yml`，同名两者并存时选择 `.yaml`。
+
+## 运行与选择环境
+
+```bash
+uv run pytest --env=test
+uv run pytest --env=test --local
+uv run pytest --env=staging
+uv run df-test env show --env=test --local
+uv run df-test env validate --env=test --local
+uv run df-test doctor --env=test --local
+```
+
+环境选择顺序：显式 CLI/API 参数 → `ENV` → 默认 `test`。
+不使用 `APP_ENV`、`ENVIRONMENT` 选择环境。名称统一小写，允许 1～32 位
+字母、数字、下划线和连字符，以字母或数字开头；如 `uat`、`qa-2` 均合法。
+选定身份后，YAML、dotenv 中的 `env/ENV` 不再改变文件选择或生效环境。
+
+本机执行 staging 时身份仍为 staging；真正测试本机部署服务时可以使用 `local` 环境，
+其 `secrets/.env.local` 是合法凭据文件，并非所有环境的共享覆盖。
+
+## 合并顺序
+
+从低到高：
+
+```text
+模型默认值
+→ base.yaml（含继承）
+→ environments/{env}.yaml（含继承）
+→ environments/{env}.local.yaml（仅 local=True / --local）
+→ secrets/.env
+→ secrets/.env.{env}
+→ 进程环境变量
+→ 程序显式覆盖
+```
+
+字典递归合并，列表和标量由后层整体替换。dotenv 采用 pydantic-settings 原生多文件源，
+不会把凭据写入全局 `os.environ`。并行执行不同环境时分别选择对应文件。
+进程环境变量仍具有更高优先级，切换环境时核对终端已有变量。
+
+```yaml
+# base.yaml
+http:
+  timeout: 30
+logging:
+  level: INFO
+```
+
+```yaml
+# environments/test.yaml
+http:
+  base_url: https://test.example.com
+```
+
+```yaml
+# environments/test.local.yaml：加 --local 才加载
+web:
+  headless: false
+logging:
+  level: DEBUG
+```
+
+```dotenv
+# secrets/.env.test
+DATABASE__PASSWORD=your-test-password
+BEARER_TOKEN__TOKEN=your-test-token
+```
+
+嵌套变量使用双下划线，键名对应 Settings 模型，如 `DATABASE__HOST`、`HTTP__BASE_URL`。
+业务配置在项目 `FrameworkSettings` 子类声明；值放 YAML/环境变量，避免为改默认值重复定义字段。
+
+## 配置继承
+
+`_extends` 是可选的单父级复用机制，所有 YAML 层一致支持。
+路径相对**写出该声明的文件所在目录**解析，不相对工作目录或配置根目录。
+
+```yaml
+# environments/staging.yaml
+_extends: test.yaml
+http:
+  base_url: https://staging.example.com
+```
+
+父文件先加载，当前文件覆盖。路径可用 `../shared.yaml` 引用配置目录内公共片段，
+解析后的路径须留在配置目录内。不存在的显式引用、循环继承、非映射 YAML、
+无效 `_extends` 类型或 YAML 语法错误会报错，错误包含文件位置而不回显秘密值。
+普通可选文件不存在则跳过。自动本机覆盖无需通过 `_extends` 再继承目标环境。
+
+## 程序与平台接入
+
+```python
+from df_test_framework import FrameworkSettings, get_settings, get_settings_for_class
+from df_test_framework.infrastructure.config import ConfigLoader, load_config
+
+normal = load_config("test")
+debug = load_config("test", local=True)
+loader = ConfigLoader(config_dir="config", settings_class=FrameworkSettings)
+staging = loader.load("staging", local=True)
+cached = get_settings(env="test", local=True)
+custom = get_settings_for_class(FrameworkSettings, env="test", local=True)
+```
+
+Bootstrap 的 `with_settings(..., profile="test", local=True)` 使用相同规则。
+缓存按实际环境、配置目录和覆盖开关区分；pytest 复用已加载的 Settings。
+修改文件后，长驻进程可调用 `clear_settings_cache()` 或重新建立配置对象。
+
+没有 `config/` 目录时，仍支持项目根目录 `.env` + `.env.{env}` 的原生 dotenv 方式；
+这一模式没有 YAML 本机覆盖文件，`local=True` 不增加额外 dotenv 层。
+`FrameworkSettings.for_environment("staging")` 会固定选定环境身份。
+
+## 生产环境与诊断
+
+`settings.is_prod` 在环境名为 `prod/production` 或 `production: true` 时成立。
+自定义环境如 `live` 可声明 `production: true`；
+`prod` 不能通过 `production: false` 解除保护。
+生产环境禁 debug、禁止在 `CI=true` 中运行，cleanup/baseline 在资源创建前拒绝操作。
+名称匹配类 marker（如 `requires_env`）仍按环境名匹配。
+
+`df-test env show/validate`、doctor 和 pytest 报告显示实际环境、覆盖开关及加载文件链。
+来源信息不展示秘密值。缺少环境文件时可使用 base 的完整配置，
+通过来源列表确认实际使用了哪些文件。体检不代替服务连通性或业务验收。
+
+## 迁移已有项目
+
+原来作为 test 调试覆盖的文件迁移为：
+
+| 原文件/命令 | 新文件/命令 |
+|---|---|
+| `config/secrets/.env.local` | `config/secrets/.env.test` |
+| `config/environments/local.yaml` | `config/environments/test.local.yaml` |
+| `pytest --env=local`（原用于调试 test） | `pytest --env=test --local` |
+
+删除原本仅用于继承 test 的 `_extends`，保留调试项。实际归属 dev/staging 的文件
+迁往对应环境；不要复制凭据到其他环境。已有继承路径 `environments/test.yaml`
+在环境文件内应改为 `test.yaml`。普通 test 执行不会默认开启调试。
+
+```gitignore
+config/environments/*.local.yaml
+config/environments/*.local.yml
+config/secrets/*
+!config/secrets/*.example
+!config/secrets/.gitkeep
+```
+
+`df-test init` 生成 `test.local.yaml.example` 与 `.env.test.example`。
+复制前确认目标文件不存在。框架不猜测 `.env.local` 是历史共享文件还是合法 local 环境，
+不因此额外告警或判定 doctor 失败，迁移由项目维护者一次性确认。

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/guides/database_guide.md

@@ -62,7 +62,7 @@ database:
   port: 3306
   name: test_db
   user: root
-  # password 建议放 config/secrets/.env.local: DATABASE__PASSWORD=...
+  # password 建议放 config/secrets/.env.test: DATABASE__PASSWORD=...
 
 # MSSQL（v4.3.0+）
 database:

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/guides/integration-guide.md

@@ -118,12 +118,12 @@ observability:
   debug_output: false
 ```
 
-#### config/environments/local.yaml
+#### config/environments/test.local.yaml
 
 ```yaml
 # 本地调试配置
 # _extends 表示继承另一个环境配置
-_extends: test
+_extends: test.yaml
 
 observability:
   debug_output: true  # 本地开启调试输出
@@ -133,7 +133,7 @@ observability:
 
 ```gitignore
 # 敏感配置（不提交）
-config/environments/local.yaml
+config/environments/test.local.yaml
 config/secrets/
 ```
 
@@ -354,7 +354,7 @@ pytest tests/ -m smoke -v
 **检查优先级**（从高到低）：
 
 1. 环境变量
-2. `config/secrets/.env.local`
+2. `config/secrets/.env.test`
 3. `config/environments/{env}.yaml`
 4. `config/base.yaml`
 5. 代码默认值

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/guides/local_debug_quickstart.md

@@ -9,9 +9,8 @@
 ### 一分钟配置
 
 ```yaml
-# config/environments/local.yaml
-_extends: environments/dev.yaml
-env: local
+# config/environments/test.local.yaml
+env: test
 debug: true
 
 logging:
@@ -28,7 +27,7 @@ test:
 
 ```bash
 # 运行测试
-uv run pytest tests/ --env=local --log-cli-level=DEBUG -v
+uv run pytest tests/ --env=test --local --log-cli-level=DEBUG -v
 ```
 
 ---
@@ -37,12 +36,11 @@ uv run pytest tests/ --env=local --log-cli-level=DEBUG -v
 
 ### 方式 1：YAML 配置文件（推荐）
 
-创建 `config/environments/local.yaml`：
+创建 `config/environments/test.local.yaml`：
 
 ```yaml
-# 继承 dev 环境配置
-_extends: environments/dev.yaml
-env: local
+# 通过 --local 叠加 test 环境，不改变目标环境身份
+env: test
 debug: true
 
 # 日志配置
@@ -98,7 +96,7 @@ log_cli_level = "DEBUG"
 log_level = "DEBUG"
 
 # 默认参数
-addopts = "-v --env=local"
+addopts = "-v --env=test --local"
 ```
 
 ---
@@ -109,32 +107,32 @@ addopts = "-v --env=local"
 
 ```bash
 # 使用 local 环境运行所有测试
-uv run pytest tests/ --env=local -v
+uv run pytest tests/ --env=test --local -v
 
 # 显示 DEBUG 日志
-uv run pytest tests/ --env=local --log-cli-level=DEBUG -v
+uv run pytest tests/ --env=test --local --log-cli-level=DEBUG -v
 
 # 显示 print 输出（不捕获）
-uv run pytest tests/ --env=local -v -s
+uv run pytest tests/ --env=test --local -v -s
 
 # 组合使用
-uv run pytest tests/ --env=local --log-cli-level=DEBUG -v -s
+uv run pytest tests/ --env=test --local --log-cli-level=DEBUG -v -s
 ```
 
 ### 运行特定测试
 
 ```bash
 # 运行单个文件
-uv run pytest tests/api/test_user.py --env=local -v
+uv run pytest tests/api/test_user.py --env=test --local -v
 
 # 运行单个测试类
-uv run pytest tests/api/test_user.py::TestUserAPI --env=local -v
+uv run pytest tests/api/test_user.py::TestUserAPI --env=test --local -v
 
 # 运行单个测试函数
-uv run pytest tests/api/test_user.py::TestUserAPI::test_login --env=local -v
+uv run pytest tests/api/test_user.py::TestUserAPI::test_login --env=test --local -v
 
 # 按关键词筛选
-uv run pytest tests/ -k "login or register" --env=local -v
+uv run pytest tests/ -k "login or register" --env=test --local -v
 ```
 
 ### 失败调试
@@ -147,29 +145,29 @@ uv run pytest tests/ -k "login or register" --env=local -v
 
 ```bash
 # 首次失败即停止
-uv run pytest tests/ --env=local -x -v
+uv run pytest tests/ --env=test --local -x -v
 
 # 失败时进入 pdb 调试器
-uv run pytest tests/ --env=local --pdb -v
+uv run pytest tests/ --env=test --local --pdb -v
 
 # 失败时进入 pdb，并显示局部变量
-uv run pytest tests/ --env=local --pdb -l -v
+uv run pytest tests/ --env=test --local --pdb -l -v
 
 # 只运行上次失败的测试
-uv run pytest tests/ --env=local --lf -v
+uv run pytest tests/ --env=test --local --lf -v
 
 # 先运行失败的测试
-uv run pytest tests/ --env=local --ff -v
+uv run pytest tests/ --env=test --local --ff -v
 ```
 
 ### 性能分析
 
 ```bash
 # 显示最慢的 10 个测试
-uv run pytest tests/ --env=local --durations=10 -v
+uv run pytest tests/ --env=test --local --durations=10 -v
 
 # 显示所有测试耗时
-uv run pytest tests/ --env=local --durations=0 -v
+uv run pytest tests/ --env=test --local --durations=0 -v
 ```
 
 ---
@@ -178,7 +176,7 @@ uv run pytest tests/ --env=local --durations=0 -v
 
 | 参数 | 作用 | 示例 |
 |------|------|------|
-| `--env=local` | 使用本地环境配置 | `--env=local` |
+| `--env=test --local` | 使用目标环境的本机覆盖 | `--env=test --local` |
 | `--log-cli-level=DEBUG` | 实时显示 DEBUG 日志 | `--log-cli-level=DEBUG` |
 | `-v` / `-vv` | 详细输出 | `-vv` |
 | `-s` | 显示 print 输出 | `-s` |
@@ -211,7 +209,7 @@ def test_api(http_client):
 运行时需要 `-v -s`：
 
 ```bash
-uv run pytest tests/test_example.py -v -s --env=local
+uv run pytest tests/test_example.py -v -s --env=test --local
 ```
 
 ### 使用 debug_mode fixture
@@ -227,7 +225,7 @@ def test_with_debug(http_client, debug_mode):
 
 ```bash
 # 全局启用调试输出
-OBSERVABILITY__DEBUG_OUTPUT=true uv run pytest tests/ -v -s --env=local
+OBSERVABILITY__DEBUG_OUTPUT=true uv run pytest tests/ -v -s --env=test --local
 ```
 
 ---
@@ -249,7 +247,8 @@ OBSERVABILITY__DEBUG_OUTPUT=true uv run pytest tests/ -v -s --env=local
       "module": "pytest",
       "args": [
         "${file}",
-        "--env=local",
+        "--env=test",
+        "--local",
         "--log-cli-level=DEBUG",
         "-v",
         "-s"
@@ -257,7 +256,7 @@ OBSERVABILITY__DEBUG_OUTPUT=true uv run pytest tests/ -v -s --env=local
       "console": "integratedTerminal",
       "justMyCode": false,
       "env": {
-        "ENV": "local",
+        "ENV": "test",
         "OBSERVABILITY__DEBUG_OUTPUT": "true"
       }
     },
@@ -268,7 +267,8 @@ OBSERVABILITY__DEBUG_OUTPUT=true uv run pytest tests/ -v -s --env=local
       "module": "pytest",
       "args": [
         "${file}::${selectedText}",
-        "--env=local",
+        "--env=test",
+        "--local",
         "-v",
         "-s"
       ],
@@ -283,7 +283,7 @@ OBSERVABILITY__DEBUG_OUTPUT=true uv run pytest tests/ -v -s --env=local
 
 1. **Edit Configurations** → **+** → **pytest**
 2. 设置参数：
-   - **Additional Arguments**: `--env=local --log-cli-level=DEBUG -v -s`
+   - **Additional Arguments**: `--env=test --local --log-cli-level=DEBUG -v -s`
    - **Environment variables**: `ENV=local;OBSERVABILITY__DEBUG_OUTPUT=true`
 
 ---
@@ -375,13 +375,13 @@ def test_with_breakpoint(http_client):
 然后运行：
 
 ```bash
-uv run pytest tests/test_example.py -v -s --env=local
+uv run pytest tests/test_example.py -v -s --env=test --local
 ```
 
 ### Q4: 如何查看 SQL 查询？
 
 ```yaml
-# config/environments/local.yaml
+# config/environments/test.local.yaml
 logging:
   level: DEBUG  # SQLAlchemy 会输出 SQL
 
@@ -394,7 +394,7 @@ logging:
 ### Q5: 调试时想保留测试数据？
 
 ```yaml
-# config/environments/local.yaml
+# config/environments/test.local.yaml
 test:
   keep_test_data: true
 ```
@@ -402,7 +402,7 @@ test:
 或使用命令行：
 
 ```bash
-uv run pytest tests/ --env=local --keep-test-data -v
+uv run pytest tests/ --env=test --local --keep-test-data -v
 ```
 
 ---
@@ -411,16 +411,16 @@ uv run pytest tests/ --env=local --keep-test-data -v
 
 ```bash
 # 1. 使用 local 环境开发
-uv run pytest tests/api/test_user.py --env=local -v
+uv run pytest tests/api/test_user.py --env=test --local -v
 
 # 2. 遇到问题，开启 DEBUG 日志
-uv run pytest tests/api/test_user.py --env=local --log-cli-level=DEBUG -v -s
+uv run pytest tests/api/test_user.py --env=test --local --log-cli-level=DEBUG -v -s
 
 # 3. 需要断点调试
-uv run pytest tests/api/test_user.py::test_login --env=local --pdb -v -s
+uv run pytest tests/api/test_user.py::test_login --env=test --local --pdb -v -s
 
 # 4. 修复后，运行完整测试验证
-uv run pytest tests/ --env=local -v
+uv run pytest tests/ --env=test --local -v
 
 # 5. 切换到 CI 环境验证
 uv run pytest tests/ --env=test -v

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/guides/message_queue.md

@@ -237,7 +237,7 @@ kafka:
   # security_protocol: SASL_SSL
   # sasl_mechanism: PLAIN
   # sasl_username: user
-  # sasl_password 建议放 config/secrets/.env.local: KAFKA__SASL_PASSWORD=...
+  # sasl_password 建议放 config/secrets/.env.test: KAFKA__SASL_PASSWORD=...
 ```
 
 **Step 2：conftest.py 导入 fixtures**
@@ -544,7 +544,7 @@ rabbitmq:
   port: 5672
   virtual_host: /
   username: admin
-  # password 建议放 config/secrets/.env.local: RABBITMQ__PASSWORD=...
+  # password 建议放 config/secrets/.env.test: RABBITMQ__PASSWORD=...
 ```
 
 **Step 2：conftest.py 导入 fixtures**

{df_test_framework-4.10.1 → df_test_framework-4.10.2}/docs/guides/project-structure-standard.md

@@ -84,8 +84,9 @@ tests/
 ```
 config/
 ├── base.yaml                    # 全环境通用（含 http.response_contract、test.naming_registry 等）
-├── environments/{env}.yaml      # test/dev/staging/prod（+ local.yaml.example 模板）
-└── secrets/.env.local           # 敏感项（gitignore；DATABASE__PASSWORD 等 __ 嵌套键）
+├── environments/{env}.yaml      # test/dev/staging/prod（+ test.local.yaml.example 模板）
+├── environments/{env}.local.yaml # 本机覆盖（--local 显式启用）
+└── secrets/.env.{env}           # 敏感项（gitignore；DATABASE__PASSWORD 等 __ 嵌套键）
 ```
 
 - `scripts/` 只放**薄壳 CLI**（argparse + 调 src 引擎）与**在用工具**