fake-driven-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fake-Driven Testing Architecture for Python

Python的Fake驱动测试架构

Use this skill when: Writing tests, fixing bugs, adding features, or modifying gateway layers in Python projects.

Prerequisites: For Python code standards, load the

dignified-python-313

skill first. This skill focuses on testing architecture, not Python syntax.

适用场景：在Python项目中编写测试、修复Bug、添加功能或修改网关层时。

前置要求：关于Python代码规范，请先加载

dignified-python-313

技能。本技能聚焦于测试架构，不涉及Python语法内容。

Overview

概述

This skill provides a defense-in-depth testing strategy with five layers for Python applications:

┌─────────────────────────────────────────┐
│  Layer 5: Business Logic Integration Tests (5%)  │  ← Smoke tests over real system
├─────────────────────────────────────────┤
│  Layer 4: Business Logic Tests (70%)   │  ← Tests over fakes (MOST TESTS)
├─────────────────────────────────────────┤
│  Layer 3: Pure Unit Tests (10%)        │  ← Zero dependencies, isolated testing
├─────────────────────────────────────────┤
│  Layer 2: Integration Sanity Tests (10%)│  ← Fast validation with mocking
├─────────────────────────────────────────┤
│  Layer 1: Fake Infrastructure Tests (5%)│  ← Verify test doubles work
└─────────────────────────────────────────┘

Philosophy: Test business logic extensively over fast in-memory fakes. Use real implementations sparingly for integration validation.

Terminology note: The "gateway layer" (also called adapters/providers) refers to thin wrappers around heavyweight external APIs (databases, filesystems, HTTP APIs, message queues, etc.). The pattern matters more than the name.

本技能为Python应用提供了包含五层的纵深防御测试策略：

┌─────────────────────────────────────────┐
│  Layer 5: Business Logic Integration Tests (5%)  │  ← 基于真实系统的冒烟测试
├─────────────────────────────────────────┤
│  Layer 4: Business Logic Tests (70%)   │  ← 基于Fake的测试（占比最高）
├─────────────────────────────────────────┤
│  Layer 3: Pure Unit Tests (10%)        │  ← 零依赖、隔离式测试
├─────────────────────────────────────────┤
│  Layer 2: Integration Sanity Tests (10%)│  ← 结合Mock的快速验证测试
├─────────────────────────────────────────┤
│  Layer 1: Fake Infrastructure Tests (5%)│  ← 验证测试替身的有效性
└─────────────────────────────────────────┘

核心理念：针对业务逻辑，优先使用轻量内存Fake进行全面测试；仅在必要时使用真实实现做集成验证。

术语说明：“网关层”（也称为适配器/提供者）是指对重量级外部API（数据库、文件系统、HTTP API、消息队列等）的轻量封装。模式本身比命名更重要。

Quick Decision: What Should I Read?

快速决策：我该阅读哪部分？

Adding a feature or fixing a bug? → Read

quick-reference.md

first, then

workflows.md#adding-a-new-feature

Need to understand where to put a test? → Read

testing-strategy.md

Working with Python-specific patterns? → Read

python-specific.md

Adding/changing a gateway interface? → Read

gateway-architecture.md

, then

workflows.md#adding-a-gateway-method

Creating a backend (higher-level abstraction over gateways)? → Read

gateway-architecture.md#gateways-vs-backends

- backends compose gateways and do NOT have fakes

Need to implement a specific pattern (CliRunner, builders, etc.)? → Read

patterns.md

Not sure if I'm doing it right? → Read

anti-patterns.md

Just need a quick lookup? → Read

quick-reference.md

添加功能或修复Bug？ → 先阅读

quick-reference.md

，再查看

workflows.md#adding-a-new-feature

需要确定测试的归属层级？ → 阅读

testing-strategy.md

处理Python特定模式？ → 阅读

python-specific.md

添加/修改网关接口？ → 阅读

gateway-architecture.md

，再查看

workflows.md#adding-a-gateway-method

创建Backend（基于网关的高层抽象）？ → 阅读

gateway-architecture.md#gateways-vs-backends

——Backend是网关的组合，不包含Fake实现

需要实现特定模式（CliRunner、构建器等）？ → 阅读

patterns.md

不确定当前做法是否正确？ → 阅读

anti-patterns.md

仅需快速查阅？ → 阅读

quick-reference.md

When to Read Each Reference Document

各参考文档的适用场景

📖

gateway-architecture.md

📖

gateway-architecture.md

Read when:

Adding or changing gateway/ABC interfaces
Understanding the ABC/Real/Fake/DryRun pattern
Need examples of gateway implementations
Want to understand what gateways are (and why they're thin)
Creating a backend (higher-level abstraction that composes gateways)

Contents:

What are gateway classes? (naming: gateways/adapters/providers)
The four implementations (ABC, Real, Fake, DryRun)
Code examples for each
When to add/change gateway methods
Design principles (keep gateways thin)
Common gateway types (Database, API, FileSystem, MessageQueue)
Gateways vs Backends - critical distinction for DI boundaries

适用场景：

添加或修改网关/ABC接口
理解ABC/Real/Fake/DryRun模式
需要网关实现示例
想了解网关的定义（以及为何需保持轻量）
创建Backend（组合网关的高层抽象）

内容包含：

网关类是什么？（命名：gateways/adapters/providers）
四种实现方式（ABC、Real、Fake、DryRun）
每种实现的代码示例
何时添加/修改网关方法
设计原则（保持网关轻量）
常见网关类型（Database、API、FileSystem、MessageQueue）
网关 vs Backends——依赖注入边界的关键区别

📖

testing-strategy.md

📖

testing-strategy.md

Read when:

Deciding where to put a test
Understanding the five testing layers
Need test distribution guidance (5/70/10/10/5 rule)
Want to know which layer tests what

Contents:

Layer 1: Unit tests of fakes (verify test infrastructure)
Layer 2: Integration sanity tests with mocking (quick validation)
Layer 3: Pure unit tests (zero dependencies, isolated testing)
Layer 4: Business logic over fakes (majority of tests)
Layer 5: Business logic integration tests (smoke tests over real systems)
Decision tree: where should my test go?
Test distribution examples

适用场景：

确定测试的归属层级
理解五层测试架构
需要测试分布指导（5/70/10/10/5规则）
想了解各层级的测试范围

内容包含：

第1层：Fake的单元测试（验证测试基础设施）
第2层：结合Mock的集成 sanity 测试（快速验证）
第3层：纯单元测试（零依赖、隔离式测试）
第4层：基于Fake的业务逻辑测试（占测试总量的大部分）
第5层：业务逻辑集成测试（基于真实系统的冒烟测试）
决策树：我的测试该放在哪一层？
测试分布示例

📖

python-specific.md

📖

python-specific.md

Read when:

Working with pytest fixtures
Need Python mocking patterns
Testing Flask/FastAPI/Django applications
Understanding Python testing tools
Need Python-specific commands

Contents:

pytest fixtures and parametrization
Mocking with unittest.mock and pytest-mock
Testing web frameworks (Flask, FastAPI, Django)
Python testing commands
Type hints in tests
Python packaging for test utilities

适用场景：

使用pytest fixtures
需要Python Mock模式
测试Flask/FastAPI/Django应用
了解Python测试工具
需要Python特定命令

内容包含：

pytest fixtures和参数化
使用unittest.mock和pytest-mock进行Mock
Web框架测试（Flask、FastAPI、Django）
Python测试命令
测试中的类型提示
测试工具的Python打包

📖

workflows.md

📖

workflows.md

Read when:

Adding a new feature (step-by-step)
Fixing a bug (step-by-step)
Adding a gateway method (complete checklist)
Changing an interface (what to update)
Managing dry-run features

Contents:

Adding a new feature (TDD workflow)
Fixing a bug (reproduce → fix → regression test)
Adding a gateway method (8-step checklist with examples)
Changing an interface (update all layers)
Managing dry-run features (wrapping pattern)
Testing with builder patterns

适用场景：

新增功能（分步指导）
修复Bug（分步指导）
添加网关方法（完整检查清单）
修改接口（需更新的内容）
管理DryRun功能

内容包含：

新增功能（TDD工作流）
修复Bug（复现→修复→回归测试）
添加网关方法（含示例的8步检查清单）
修改接口（更新所有层级）
管理DryRun功能（封装模式）
使用构建器模式进行测试

📖

patterns.md

📖

patterns.md

Read when:

Implementing constructor injection for fakes
Adding mutation tracking to fakes
Using CliRunner for CLI tests
Building complex test scenarios with builders
Testing dry-run behavior
Need code examples of specific patterns

Contents:

Constructor injection (how and why)
Mutation tracking properties (read-only access)
Using CliRunner (not subprocess)
Builder patterns for complex scenarios
Simulated environment pattern
Error injection pattern
Dry-run testing pattern

适用场景：

为Fake实现构造函数注入
为Fake添加变更跟踪
使用CliRunner进行CLI测试
使用构建器构建复杂测试场景
测试DryRun行为
需要特定模式的代码示例

内容包含：

构造函数注入（方式及原因）
变更跟踪属性（只读访问）
使用CliRunner（而非subprocess）
复杂场景的构建器模式
模拟环境模式
错误注入模式
DryRun测试模式

📖

anti-patterns.md

📖

anti-patterns.md

Read when:

Unsure if your approach is correct
Want to avoid common mistakes
Reviewing code for bad patterns
Debugging why tests are slow/brittle

Contents:

❌ Testing speculative features
❌ Hardcoded paths in tests (catastrophic)
❌ Not updating all layers
❌ Using subprocess in unit tests
❌ Complex logic in gateway classes
❌ Fakes with I/O operations
❌ Testing implementation details
❌ Incomplete test coverage for gateways

适用场景：

不确定当前做法是否正确
想避免常见错误
代码评审中识别不良模式
调试测试缓慢/脆弱的原因

内容包含：

❌ 测试推测性功能
❌ 测试中使用硬编码路径（严重问题）
❌ 未更新所有层级
❌ 单元测试中使用subprocess
❌ 网关类中包含复杂逻辑
❌ Fake包含I/O操作
❌ 测试实现细节
❌ 网关的测试覆盖不完整

📖

quick-reference.md

📖

quick-reference.md

Read when:

Quick lookup for file locations
Finding example tests to reference
Looking up common fixtures
Need command reference
Want test distribution guidelines

Contents:

Decision tree (where to add test)
File location map (source + tests)
Common fixtures (tmp_path, CliRunner, etc.)
Common test patterns (code snippets)
Example tests to reference
Useful commands (pytest, ty, etc.)
Quick checklist for adding gateway methods

适用场景：

快速查阅文件位置
查找可参考的测试示例
查阅常用fixtures
需要命令参考
想了解测试分布指南

内容包含：

决策树（新增测试的归属）
文件位置映射（源码+测试）
常用fixtures（tmp_path、CliRunner等）
常见测试模式（代码片段）
可参考的测试示例
实用命令（pytest、ty等）
添加网关方法的快速检查清单

Quick Navigation by Task

按任务快速导航

I'm adding a new feature

我要新增功能

Quick start:
```
quick-reference.md
```
→ Decision tree
Step-by-step:
```
workflows.md#adding-a-new-feature
```
Patterns:
```
patterns.md
```
(CliRunner, builders)
Avoid:
```
anti-patterns.md
```
(speculative tests, hardcoded paths)

快速入门：
```
quick-reference.md
```
→ 决策树
分步指导：
```
workflows.md#adding-a-new-feature
```
模式参考：
```
patterns.md
```
（CliRunner、构建器）
避坑指南：
```
anti-patterns.md
```
（推测性测试、硬编码路径）

I'm fixing a bug

我要修复Bug

Step-by-step:
```
workflows.md#fixing-a-bug
```

Patterns:

patterns.md#constructor-injection-for-fakes

Examples:

quick-reference.md#example-tests-to-reference

分步指导：
```
workflows.md#fixing-a-bug
```

模式参考：

patterns.md#constructor-injection-for-fakes

示例参考：

quick-reference.md#example-tests-to-reference

I'm adding/changing a gateway method

我要添加/修改网关方法

Understanding:
```
gateway-architecture.md
```
Step-by-step:
```
workflows.md#adding-a-gateway-method
```

Checklist:

quick-reference.md#quick-checklist-adding-a-new-gateway-method

Avoid:

anti-patterns.md#not-updating-all-layers

概念理解：
```
gateway-architecture.md
```
分步指导：
```
workflows.md#adding-a-gateway-method
```

检查清单：

quick-reference.md#quick-checklist-adding-a-new-gateway-method

避坑指南：

anti-patterns.md#not-updating-all-layers

I don't know where my test should go

我不知道测试该放在哪一层

Decision tree:
```
quick-reference.md#decision-tree
```
Detailed guide:
```
testing-strategy.md
```

Examples:

quick-reference.md#example-tests-to-reference

决策树：
```
quick-reference.md#decision-tree
```
详细指南：
```
testing-strategy.md
```

示例参考：

quick-reference.md#example-tests-to-reference

I need to implement a pattern

我需要实现特定模式

All patterns:
```
patterns.md
```
Examples:
```
quick-reference.md#common-test-patterns
```

模式全集：
```
patterns.md
```
示例参考：
```
quick-reference.md#common-test-patterns
```

I think I'm doing something wrong

我觉得当前做法有问题

Anti-patterns:
```
anti-patterns.md
```
Correct approach:
```
workflows.md
```

反模式参考：
```
anti-patterns.md
```
正确方案：
```
workflows.md
```

Visual Layer Guide

可视化层级指南

┌──────────────────────────────────────────────────────────────┐
│ Layer 5: Business Logic Integration Tests (5%)               │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Real database, filesystem, APIs, actual subprocess        │ │
│ │ Purpose: Smoke tests, catch integration issues           │ │
│ │ When: Sparingly, for critical workflows                  │ │
│ │ Speed: Seconds per test                                   │ │
│ │ Location: tests/e2e/ or tests/integration/               │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 4: Business Logic Tests (70%) ← MOST TESTS HERE       │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ FakeDatabase, FakeApiClient, FakeFileSystem              │ │
│ │ Purpose: Test features and business logic extensively    │ │
│ │ When: For EVERY feature and bug fix                      │ │
│ │ Speed: Milliseconds per test                              │ │
│ │ Location: tests/unit/, tests/services/, tests/commands/  │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 3: Pure Unit Tests (10%)                               │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Zero dependencies, no fakes, no mocks                    │ │
│ │ Purpose: Test isolated utilities and helpers             │ │
│ │ When: For pure functions, data structures, parsers       │ │
│ │ Speed: Milliseconds per test                              │ │
│ │ Location: tests/unit/                                     │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 2: Integration Sanity Tests (10%)                      │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ RealDatabase with mocked connections                     │ │
│ │ Purpose: Quick validation, catch syntax errors           │ │
│ │ When: When adding/changing real implementation           │ │
│ │ Speed: Fast (mocked)                                      │ │
│ │ Location: tests/integration/test_real_*.py               │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 1: Fake Infrastructure Tests (5%)                      │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Test FakeDatabase itself                                 │ │
│ │ Purpose: Verify test infrastructure is reliable          │ │
│ │ When: When adding/changing fake implementation           │ │
│ │ Speed: Milliseconds per test                              │ │
│ │ Location: tests/unit/fakes/test_fake_*.py               │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 5: Business Logic Integration Tests (5%)               │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Real database, filesystem, APIs, actual subprocess        │ │
│ │ Purpose: Smoke tests, catch integration issues           │ │
│ │ When: Sparingly, for critical workflows                  │ │
│ │ Speed: Seconds per test                                   │ │
│ │ Location: tests/e2e/ or tests/integration/               │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 4: Business Logic Tests (70%) ← MOST TESTS HERE       │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ FakeDatabase, FakeApiClient, FakeFileSystem              │ │
│ │ Purpose: Test features and business logic extensively    │ │
│ │ When: For EVERY feature and bug fix                      │ │
│ │ Speed: Milliseconds per test                              │ │
│ │ Location: tests/unit/, tests/services/, tests/commands/  │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 3: Pure Unit Tests (10%)                               │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Zero dependencies, no fakes, no mocks                    │ │
│ │ Purpose: Test isolated utilities and helpers             │ │
│ │ When: For pure functions, data structures, parsers       │ │
│ │ Speed: Milliseconds per test                              │ │
│ │ Location: tests/unit/                                     │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 2: Integration Sanity Tests (10%)                      │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ RealDatabase with mocked connections                     │ │
│ │ Purpose: Quick validation, catch syntax errors           │ │
│ │ When: When adding/changing real implementation           │ │
│ │ Speed: Fast (mocked)                                      │ │
│ │ Location: tests/integration/test_real_*.py               │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│ Layer 1: Fake Infrastructure Tests (5%)                      │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Test FakeDatabase itself                                 │ │
│ │ Purpose: Verify test infrastructure is reliable          │ │
│ │ When: When adding/changing fake implementation           │ │
│ │ Speed: Milliseconds per test                              │ │
│ │ Location: tests/unit/fakes/test_fake_*.py               │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

Key Principles

核心原则

Thin gateway layer: Wrap external state, push complexity to business logic
Fast tests over fakes: 70% of tests should use in-memory fakes
Defense in depth: Fakes → sanity tests → pure unit → business logic → integration
Test what you're building: No speculative tests, only active work
Update all layers: When changing interfaces, update ABC/real/fake/dry-run
Gateways vs Backends: Gateways have fakes; backends compose gateways and do NOT have fakes

轻量网关层：封装外部状态，将复杂逻辑转移至业务层
基于Fake的快速测试：70%的测试应使用内存Fake
纵深防御：Fake → Sanity测试 → 纯单元测试 → 业务逻辑测试 → 集成测试
测试当前开发内容：不测试推测性功能，仅针对正在开发的内容
更新所有层级：修改接口时，同步更新ABC/Real/Fake/DryRun
网关 vs Backends：网关包含Fake实现；Backend是网关的组合，不包含Fake实现

Layer Selection Guide

层级选择指南

Distinguishing Layer 3 (Pure Unit) from Layer 4 (Business Logic):

Layer 3 (Pure Unit Tests): ZERO dependencies - no fakes, no mocks, no external state
- Testing string utilities:
```
sanitize_branch_name("feat/FOO")
```
  →
```
"feat-foo"
```
- Testing parsers:
```
parse_git_status("## main")
```
  →
```
{"branch": "main"}
```
- Testing data structures:
```
LinkedList.append()
```
  without any external dependencies
Layer 4 (Business Logic Tests): Uses fakes for external dependencies
- Testing commands:
```
create_worktree(fake_git, name="feature")
```
- Testing workflows:
```
submit_pr(fake_gh, fake_git, ...)
```
- Testing business logic that coordinates multiple integrations

If your test imports a Fake*, it belongs in Layer 4, not Layer 3.

区分第3层（纯单元测试）与第4层（业务逻辑测试）：

第3层（纯单元测试）：零依赖——无Fake、无Mock、无外部状态
- 测试字符串工具：
```
sanitize_branch_name("feat/FOO")
```
  →
```
"feat-foo"
```
- 测试解析器：
```
parse_git_status("## main")
```
  →
```
{"branch": "main"}
```
- 测试无外部依赖的数据结构：
```
LinkedList.append()
```
第4层（业务逻辑测试）：使用Fake处理外部依赖
- 测试命令：
```
create_worktree(fake_git, name="feature")
```
- 测试工作流：
```
submit_pr(fake_gh, fake_git, ...)
```
- 测试协调多个集成的业务逻辑

如果你的测试导入了Fake，则属于第4层，而非第3层。*

Default Testing Strategy

默认测试策略

When in doubt:

Write test over fakes (Layer 4) for business logic
Write pure unit test (Layer 3) for utilities/helpers with no dependencies
Use
```
pytest
```
with fixtures
Use
```
tmp_path
```
fixture (not hardcoded paths)
Follow examples in
```
quick-reference.md
```

存疑时：

针对业务逻辑，编写基于Fake的测试（第4层）
针对无依赖的工具/辅助函数，编写纯单元测试（第3层）
使用
```
pytest
```
及fixtures
使用
```
tmp_path
```
fixture（而非硬编码路径）
参考
```
quick-reference.md
```
中的示例

Summary

总结

For quick tasks: Start with

quick-reference.md

For understanding: Start with

testing-strategy.md

gateway-architecture.md

For step-by-step guidance: Use

workflows.md

For implementation details: Use

patterns.md

For validation: Check

anti-patterns.md

For Python specifics: Check

python-specific.md

快速任务：从

quick-reference.md

开始

概念理解：从

testing-strategy.md

或

gateway-architecture.md

开始

分步指导：使用

workflows.md

实现细节：使用

patterns.md

验证检查：查看

anti-patterns.md

Python特定内容：查看

python-specific.md