Terminal
Terminal/Skill
Guides Python test layout and fake-based testing across five layers, from fake checks to smoke tests, and where each test belongs.
By Dagster
Works with
npx skills add dagster-io/fake-driven-testing --skill fake-driven-testingUse this skill when: Writing tests, fixing bugs, adding features, or modifying gateway layers in Python projects.
No prerequisites. This skill is self-contained. It focuses on testing architecture, not language-specific style.
This skill provides a defense-in-depth testing strategy with five layers for Python applications:
┌─────────────────────────────────────────────────┐
│ Layer 5 "smoke": Business Logic Integration Tests (5%) │ ← Smoke tests over real system
├─────────────────────────────────────────────────┤
│ Layer 4 "logic": Business Logic Tests (70%) │ ← Tests over fakes (MOST TESTS)
├─────────────────────────────────────────────────┤
│ Layer 3 "pure": Pure Unit Tests (10%) │ ← Zero dependencies, isolated testing
├─────────────────────────────────────────────────┤
│ Layer 2 "real-sanity": Integration Sanity Tests (10%) │ ← Fast validation with mocking
├─────────────────────────────────────────────────┤
│ Layer 1 "fake-check": 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.
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
Wondering where the DI boundary is?
→ Read gateway-architecture.md#the-di-boundary-only-fake-gateways — only gateways get fakes
Need to understand non-ideal states vs exceptions?
→ Read non-ideal-states.md
Found tests using unittest.mock that should use fakes?
→ Read mock-to-fake-conversion.md
Need to implement a specific pattern (CliRunner, builders, etc.)?
→ Read patterns.md
Want to extend the gateway system (e.g., dry-run preview)?
→ Read advanced-extensions.md
Not sure if I'm doing it right?
→ Read anti-patterns.md
Just need a quick lookup?
→ Read quick-reference.md
gateway-architecture.mdRead when:
Contents:
non-ideal-states.mdRead when:
Contents:
mock-to-fake-conversion.mdRead when:
unittest.mock.patch or @patch decoratorsContents:
testing-strategy.mdRead when:
Contents:
python-specific.mdRead when:
Contents:
workflows.mdRead when:
Contents:
patterns.mdRead when:
Contents:
anti-patterns.mdRead when:
Contents:
quick-reference.mdRead when:
Contents:
quick-reference.md → Decision treeworkflows.md#adding-a-new-featurepatterns.md (CliRunner, builders)anti-patterns.md (speculative tests, hardcoded paths)workflows.md#fixing-a-bugpatterns.md#constructor-injection-for-fakesquick-reference.md#example-tests-to-referencegateway-architecture.mdworkflows.md#adding-a-gateway-methodquick-reference.md#quick-checklist-adding-a-new-gateway-methodanti-patterns.md#not-updating-all-layersquick-reference.md#decision-treetesting-strategy.mdquick-reference.md#example-tests-to-referencepatterns.mdquick-reference.md#common-test-patternsanti-patterns.mdworkflows.md┌──────────────────────────────────────────────────────────────┐
│ Layer 5 "smoke": 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 "logic": Business Logic Tests (70%) ← MOST TESTS │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 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": 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 "real-sanity": 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-check": 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 │ │
│ └──────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
Distinguishing Layer 3 "pure" from Layer 4 "logic":
Layer 3 "pure" (Pure Unit Tests): ZERO dependencies - no fakes, no mocks, no external state
sanitize_branch_name("feat/FOO") → "feat-foo"parse_git_status("## main") → {"branch": "main"}LinkedList.append() without any external dependenciesLayer 4 "logic" (Business Logic Tests): Uses fakes for external dependencies
create_worktree(fake_git, name="feature")submit_pr(fake_gh, fake_git, ...)If your test imports a Fake*, it belongs in Layer 4 "logic", not Layer 3 "pure".
When in doubt:
pytest with fixturestmp_path fixture (not hardcoded paths)quick-reference.mdFor quick tasks: Start with quick-reference.md
For understanding: Start with testing-strategy.md or gateway-architecture.md
For step-by-step guidance: Use workflows.md
For implementation details: Use patterns.md
For error handling design: Check non-ideal-states.md
For converting mocks to fakes: Check mock-to-fake-conversion.md
For validation: Check anti-patterns.md
For Python specifics: Check python-specific.md