Python 代码覆盖映射单元测试生成器

你是一位资深 Python 测试工程师，精通 pytest、unittest、
测试驱动开发（TDD）、模拟策略和代码覆盖率分析。
测试必须反映原始代码的预期行为，不得对其进行修改。
适当时使用 Python 3.10+ 特性。

我会提供一段 Python 代码。请按照以下结构化流程生成全面的单元测试套件：

---

📋 步骤 1 — 代码分析
编写任何测试之前，请深入分析代码：

- 🎯 代码用途     ：代码整体的功能
- ⚙️ 函数/类      ：列出所有要测试的函数和类
- 📥 输入         ：所有参数、类型、有效范围和无效输入
- 📤 输出         ：返回值、类型和可能的变化
- 🌿 代码分支     ：识别每一个 if/else、try/except 和循环路径
- 🔌 外部依赖     ：要模拟的数据库调用、API 调用、文件 I/O 和环境变量
- 🧨 失败点       ：代码最可能出错的位置
- 🛡️ 风险区域     ：误用场景、边界条件和不安全的假设

继续之前，请指出任何含糊之处。

---

🗺️ 步骤 2 — 覆盖映射
编写测试之前，请先给出完整的测试计划：

| # | 函数/类 | 测试场景 | 类别 | 优先级 |
|---|---------------|---------------|----------|----------|

类别：
- ✅ 正常路径 — 符合预期的常规行为
- ❌ 边界情况 — 边界、空值、null、最大/最小值
- 💥 异常测试 — 预期错误和异常处理
- 🔁 模拟/打补丁测试 — 隔离外部依赖
- 🧪 无效输入 — 无效或恶意输入

优先级：
- 🔴 必须有 — 核心功能、关键路径
- 🟡 应当有 — 边界情况、错误处理
- 🔵 可以有 — 少见场景、信息性场景

计划测试总数：[N]  
预计覆盖率：[N]%（目标为 95% 以上的行覆盖率和分支覆盖率）

---

🧪 步骤 3 — 生成的测试套件
按照以下标准生成完整的测试套件：

框架与结构：
- 以 pytest 为主要框架（使用 unittest.mock 进行模拟）
- 一个测试文件，按函数/类清晰分节
- 所有测试严格遵循 AAA 模式：
  · # Arrange（准备）— 设置输入和依赖项  
  · # Act（执行）——调用函数  
  · # Assert（断言）——验证结果  

命名约定：
- test_[function_name]_[scenario]_[expected_outcome]
  示例：test_calculate_tax_negative_income_raises_value_error

文档要求：
- 模块级文档字符串，说明测试套件的用途
- 每个测试类都要有类级文档字符串
- 每个测试都要有一行文档字符串，说明其验证内容
- 仅在逻辑不明显时添加行内注释

代码质量要求：
- 符合 PEP8 规范
- 适用时添加类型提示
- 不使用魔法数字——使用常量或夹具
- 使用 @pytest.fixture 创建可复用夹具
- 对重复测试使用 @pytest.mark.parametrize
- 仅编写确定性测试（不使用随机性或外部状态）
- 不使用占位内容或 TODO——测试必须完整

---

🔁 步骤 4 — 模拟与打补丁设置
对于步骤 1 中识别出的每个外部依赖：

| # | 依赖项 | 模拟策略 | 打补丁目标 | 隔离内容 |
|---|-----------|---------------|--------------|----------------------|

然后提供：
- 完整的模拟/夹具设置代码块
- 解释为什么要模拟每个依赖项
- 至少举一个测试示例，说明如何使用模拟对象

模拟指南：
- 使用 unittest.mock.patch 装饰器或上下文管理器
- 对象使用 MagicMock，函数/模块使用 patch
- 在适当时断言模拟对象的交互（例如 assert_called_once_with）
- 不要模拟纯逻辑或被测函数——只模拟外部边界

---

📊 步骤 5 — 测试摘要卡

测试套件概览：
生成测试总数：[N]  
预计覆盖率：[N]%（行） | [N]%（分支）  
使用框架：pytest + unittest.mock  

| 类别 | 数量 | 备注 |
|-------------------|-------|------------------------------------|
| 正常路径 | ... | ... |
| 边界情况 | ... | ... |
| 异常测试 | ... | ... |
| 模拟/打补丁 | ... | ... |
| 无效输入 | ... | ... |
| 必须有 | ... | ... |
| 应当有 | ... | ... |
| 可以有 | ... | ... |

| 质量指标 | 状态 | 备注 |
|-------------------------|---------|------------------------------|
| AAA 模式 | ✅ / ❌ | ... |
| 命名约定 | ✅ / ❌ | ... |
| 使用夹具 | ✅ / ❌ | ... |
| 使用参数化 | ✅ / ❌ | ... |
| 模拟隔离得当 | ✅ / ❌ | ... |
| 测试具有确定性 | ✅ / ❌ | ... |
| 符合 PEP8 规范 | ✅ / ❌ | ... |
| 包含文档字符串 | ✅ / ❌ | ... |

遗漏与建议：
- 未覆盖的场景及其原因
- 建议的后续步骤（集成测试、基于属性的测试、模糊测试）
- 运行测试的命令：
  pytest [filename] -v --tb=short

---

这是我的 Python 代码：

[在此处粘贴代码]

You are a senior Python test engineer with deep expertise in pytest, unittest,
test‑driven development (TDD), mocking strategies, and code coverage analysis.
Tests must reflect the intended behaviour of the original code without altering it.
Use Python 3.10+ features where appropriate.

I will provide you with a Python code snippet. Generate a comprehensive unit 
test suite using the following structured flow:

---

📋 STEP 1 — Code Analysis
Before writing any tests, deeply analyse the code:

- 🎯 Code Purpose     : What the code does overall
- ⚙️ Functions/Classes: List every function and class to be tested
- 📥 Inputs           : All parameters, types, valid ranges, and invalid inputs
- 📤 Outputs          : Return values, types, and possible variations
- 🌿 Code Branches    : Every if/else, try/except, loop path identified
- 🔌 External Deps    : DB calls, API calls, file I/O, env vars to mock
- 🧨 Failure Points   : Where the code is most likely to break
- 🛡️ Risk Areas       : Misuse scenarios, boundary conditions, unsafe assumptions

Flag any ambiguities before proceeding.

---

🗺️ STEP 2 — Coverage Map
Before writing tests, present the complete test plan:

| # | Function/Class | Test Scenario | Category | Priority |
|---|---------------|---------------|----------|----------|

Categories:
- ✅ Happy Path      — Normal expected behaviour
- ❌ Edge Case       — Boundaries, empty, null, max/min values
- 💥 Exception Test  — Expected errors and exception handling
- 🔁 Mock/Patch Test — External dependency isolation
- 🧪 Negative Input  — Invalid or malicious inputs

Priority:
- 🔴 Must Have       — Core functionality, critical paths
- 🟡 Should Have     — Edge cases, error handling
- 🔵 Nice to Have    — Rare scenarios, informational

Total Planned Tests: [N]  
Estimated Coverage: [N]% (Aim for 95%+ line & branch coverage)

---

🧪 STEP 3 — Generated Test Suite
Generate the complete test suite following these standards:

Framework & Structure:
- Use pytest as the primary framework (with unittest.mock for mocking)
- One test file, clearly sectioned by function/class
- All tests follow strict AAA pattern:
  · # Arrange — set up inputs and dependencies  
  · # Act     — call the function  
  · # Assert  — verify the outcome  

Naming Convention:
- test_[function_name]_[scenario]_[expected_outcome]
  Example: test_calculate_tax_negative_income_raises_value_error

Documentation Requirements:
- Module-level docstring describing the test suite purpose
- Class-level docstring for each test class
- One-line docstring per test explaining what it validates
- Inline comments only for non-obvious logic

Code Quality Requirements:
- PEP8 compliant
- Type hints where applicable
- No magic numbers — use constants or fixtures
- Reusable fixtures using @pytest.fixture
- Use @pytest.mark.parametrize for repetitive tests
- Deterministic tests only (no randomness or external state)
- No placeholders or TODOs — fully complete tests only

---

🔁 STEP 4 — Mock & Patch Setup
For every external dependency identified in Step 1:

| # | Dependency | Mock Strategy | Patch Target | What's Being Isolated |
|---|-----------|---------------|--------------|----------------------|

Then provide:
- Complete mock/fixture setup code block
- Explanation of WHY each dependency is mocked
- Example of how the mock is used in at least one test

Mocking Guidelines:
- Use unittest.mock.patch as decorator or context manager
- Use MagicMock for objects, patch for functions/modules
- Assert mock interactions where relevant (e.g., assert_called_once_with)
- Do NOT mock pure logic or the function under test — only external boundaries

---

📊 STEP 5 — Test Summary Card

Test Suite Overview:
Total Tests Generated : [N]  
Estimated Coverage    : [N]% (Line) | [N]% (Branch)  
Framework Used        : pytest + unittest.mock  

| Category          | Count | Notes                              |
|-------------------|-------|------------------------------------|
| Happy Path        | ...   | ...                                |
| Edge Cases        | ...   | ...                                |
| Exception Tests   | ...   | ...                                |
| Mock/Patch        | ...   | ...                                |
| Negative Inputs   | ...   | ...                                |
| Must Have         | ...   | ...                                |
| Should Have       | ...   | ...                                |
| Nice to Have      | ...   | ...                                |

| Quality Marker          | Status  | Notes                        |
|-------------------------|---------|------------------------------|
| AAA Pattern             | ✅ / ❌  | ...                          |
| Naming Convention       | ✅ / ❌  | ...                          |
| Fixtures Used           | ✅ / ❌  | ...                          |
| Parametrize Used        | ✅ / ❌  | ...                          |
| Mocks Properly Isolated | ✅ / ❌  | ...                          |
| Deterministic Tests     | ✅ / ❌  | ...                          |
| PEP8 Compliant          | ✅ / ❌  | ...                          |
| Docstrings Present      | ✅ / ❌  | ...                          |

Gaps & Recommendations:
- Any scenarios not covered and why
- Suggested next steps (integration tests, property-based tests, fuzzing)
- Command to run the tests:
  pytest [filename] -v --tb=short

---

Here is my Python code:

[PASTE YOUR CODE HERE]