Organize Test Layers

Purpose

Ensure new tests are placed in the correct test pyramid layer based on dependencies, mocking patterns, and scope. Prevents anti-patterns like unit tests with real databases or e2e tests with excessive mocking.

When to Use

Use this skill when:

•Creating new test files - Determining correct test layer placement
•Deciding test layer - Choosing between unit, integration, or e2e
•Organizing test structure - Structuring test directories by layer
•Determining fixture scope - Deciding function vs session scope fixtures
•Reviewing test architecture - Validating tests are in correct layers
•Refactoring tests - Moving tests to appropriate layers

Trigger phrases:

•"Where should this test go?"
•"Should this be unit or integration test?"
•"Organize test structure"
•"Test layer placement"
•"Test pyramid organization"

Core Sections

•Purpose - Test layer placement guidance
•When to Use - Scenarios for using this skill
•Quick Start - Fast decision tree for test placement
•
Instructions - Step-by-step layer determination
- •Step 1: Identify Test Dependencies - Analyze mocking patterns
- •Step 2: Determine Fixture Scope - Match fixtures to layers
- •Step 3: Choose Directory Structure - Place files correctly
- •Step 4: Apply Test Pyramid Guidelines - Follow distribution
- •Step 5: Validate Test Placement - Check for anti-patterns
•
Examples - Working examples by layer
- •Example 1: Unit Test for Service - Pure logic testing
- •Example 2: Integration Test for Repository - Real database
- •Example 3: E2E Test for Search Workflow - Full stack
•Requirements - pytest-asyncio, Clean Architecture knowledge
•See Also - Related conftest files and skills

Supporting Resources

•references/reference.md - Test pyramid theory and advanced patterns

Utility Scripts

•Analyze Test Pyramid - Analyze test distribution and compare to ideal pyramid ratios
•Move Test - Intelligently move tests between layers with automatic import updates
•Validate Test Placement - Find misplaced tests and suggest corrections
•Organize Tests - Master orchestration script for all test organization utilities

Quick Start

Creating a new test? Ask yourself:

•Do I mock ALL external dependencies? → Unit test (tests/unit/)
•Do I use REAL infrastructure (DB/filesystem) but mock external APIs? → Integration test (tests/integration/)
•Do I test the FULL stack end-to-end with real services? → E2E test (tests/e2e/)

Instructions

Step 1: Identify Test Dependencies

Analyze what the test needs to run:

•Unit Tests: Mock everything external (database, filesystem, network, time)
•Integration Tests: Real infrastructure (Neo4j, filesystem), mock external APIs (embeddings, LLMs)
•E2E Tests: Real everything, test complete workflows

Pattern Recognition:

python

# Unit test pattern - Mock objects
from unittest.mock import AsyncMock, Mock
mock_db = Mock(spec=Neo4jDatabase)

# Integration test pattern - Real fixtures
async def test_with_real_db(neo4j_database: Neo4jDatabase):

# E2E test pattern - Full system
async def test_workflow(search_handler, indexed_real_codebase):

Step 2: Determine Fixture Scope

Match fixture scope to test layer:

Unit Test Fixtures (function scope):

•mock_config - Mock Settings object
•temp_dir - Temporary directory
•mock_neo4j_rag - Mocked Neo4jRAG
•mock_repository_monitor - Mocked monitor

Integration Test Fixtures (function scope, real resources):

•real_settings - Settings from environment
•neo4j_database - Real Neo4jDatabase instance
•neo4j_driver - Real Neo4j driver
•test_database - Database name with cleanup

E2E Test Fixtures (session/function scope, full stack):

•indexed_real_codebase - Session-level codebase indexing
•search_handler - Real SearchCodeHandler
•neo4j_driver - Connected to indexed database

Step 3: Choose Directory Structure

Place test files following Clean Architecture layers:

code

tests/
├── unit/                          # Mock everything
│   ├── conftest.py               # Unit test fixtures
│   ├── config/                   # Domain/config tests
│   ├── application/              # Application layer tests
│   │   ├── services/
│   │   ├── commands/
│   │   └── queries/
│   ├── infrastructure/           # Infrastructure tests (mocked)
│   └── core/                     # Core logic tests
├── integration/                   # Real infrastructure, mock external APIs
│   ├── conftest.py               # Integration fixtures
│   ├── neo4j/                    # Neo4j integration tests
│   ├── infrastructure/           # Real infrastructure tests
│   └── clean_architecture/       # Cross-layer integration
└── e2e/                          # Full stack
    ├── conftest.py               # E2E fixtures
    ├── semantic_search/          # Search E2E tests
    └── test_*.py                 # Workflow tests

Step 4: Apply Test Pyramid Guidelines

Follow test distribution and characteristics:

Unit Tests (70% of tests):

•Fast (<10ms per test)
•No external dependencies
•Test single responsibility
•Use @pytest.mark.unit marker

Integration Tests (20% of tests):

•Medium speed (<500ms per test)
•Real infrastructure, mocked external services
•Test component interactions
•Use @pytest.mark.integration marker

E2E Tests (10% of tests):

•Slow (1-10s per test)
•Full system integration
•Test user workflows
•Use @pytest.mark.e2e marker

Step 5: Validate Test Placement

Check test placement against patterns:

Red Flags (Wrong Layer):

•❌ Unit test with neo4j_database fixture → Should be integration
•❌ Integration test with all mocks → Should be unit
•❌ E2E test testing single method → Should be unit
•❌ Unit test with network calls → Should be integration or e2e

Green Flags (Correct Layer):

•✅ Unit test with Mock(spec=ServiceClass)
•✅ Integration test with real_settings and neo4j_database
•✅ E2E test with search_handler and indexed_real_codebase

Examples

Example 1: Unit Test for Service

Scenario: Testing ChunkingService logic without database

python

# tests/unit/application/services/test_chunking_service.py
from unittest.mock import Mock
import pytest
from project_watch_mcp.application.services.chunking_service import ChunkingService

@pytest.mark.unit
async def test_chunk_size_calculation(mock_config):
    """Test chunk size calculation logic (pure function)."""
    service = ChunkingService(settings=mock_config)

    # Mock dependencies
    content = "def foo():\n    pass\n" * 100

    # Test logic without external dependencies
    chunks = service.calculate_chunks(content)

    assert len(chunks) > 0
    assert all(chunk.size <= mock_config.chunking.max_chunk_lines for chunk in chunks)

Why Unit: No database, no filesystem, tests pure logic.

Example 2: Integration Test for Repository

Scenario: Testing Neo4jCodeRepository with real database

python

# tests/integration/infrastructure/neo4j/test_code_repository.py
import pytest
from project_watch_mcp.infrastructure.neo4j.code_repository import Neo4jCodeRepository

@pytest.mark.integration
async def test_store_and_retrieve_chunk(neo4j_database, real_settings):
    """Test chunk persistence in real Neo4j database."""
    repository = Neo4jCodeRepository(neo4j_database.driver, real_settings)

    # Create test chunk
    chunk = Chunk(
        chunk_hash="test_hash",
        file_path="/test/file.py",
        content="test content",
        start_line=1,
        end_line=5
    )

    # Test with REAL database
    result = await repository.store_chunk(chunk)
    assert result.success

    # Verify persistence
    retrieved = await repository.get_chunk("test_hash")
    assert retrieved.data.content == "test content"

Why Integration: Uses real Neo4j database, tests actual persistence.

Example 3: E2E Test for Search Workflow

Scenario: Testing complete semantic search workflow

python

# tests/e2e/semantic_search/test_semantic_search_methods.py
import pytest

@pytest.mark.e2e
async def test_search_for_methods(search_handler, indexed_real_codebase):
    """Test searching for methods across real indexed codebase."""
    query = SearchCodeQuery(
        query_text="chunk validation",
        project_name="project-watch-mcp",
        search_type=SearchType.SEMANTIC,
        limit=10
    )

    # Execute REAL search with REAL embeddings and REAL database
    result = await search_handler.handle(query)

    assert result.success
    assert len(result.data) > 0

    # Verify result quality (LLM usability test)
    first_result = result.data[0]
    assert "file_path" in first_result
    assert "content" in first_result
    assert first_result["score"] > 0.5

Why E2E: Full stack (indexed codebase, real embeddings, real Neo4j, real search).

Requirements

•pytest with pytest-asyncio installed
•Understand project's Clean Architecture layers
•Access to conftest.py files in each test layer
•Familiarity with fixture scopes (function, module, session)

test-organize-layers

Organize Test Layers

Purpose

When to Use

Table of Contents

Core Sections

Supporting Resources

Utility Scripts

Quick Start

Instructions

Step 1: Identify Test Dependencies

Step 2: Determine Fixture Scope

Step 3: Choose Directory Structure

Step 4: Apply Test Pyramid Guidelines

Step 5: Validate Test Placement

Examples

Example 1: Unit Test for Service

Example 2: Integration Test for Repository

Example 3: E2E Test for Search Workflow

Requirements

See Also