tests/unit/
├── core/              # Tests for src/cleveragents/core/
│   ├── test_application.py
│   ├── test_tool_command_processing.py  ✅
│   ├── test_json_sanitization.py        ✅
│   └── test_config.py
├── agents/            # Tests for src/cleveragents/agents/
│   ├── test_base.py
│   ├── test_llm.py
│   ├── test_tool.py
│   ├── test_chain.py
│   ├── test_composite.py
│   └── test_factory.py
├── reactive/          # Tests for src/cleveragents/reactive/
│   ├── test_stream_router.py
│   ├── test_config_parser.py
│   ├── test_route.py
│   └── test_route_bridge.py
├── langgraph/         # Tests for src/cleveragents/langgraph/
│   ├── test_bridge.py
│   ├── test_graph.py
│   ├── test_nodes.py
│   └── test_state.py
└── templates/         # Tests for src/cleveragents/templates/
    ├── test_registry.py
    ├── test_renderer.py
    ├── test_base.py
    └── test_yaml_template_engine.py

Existing Test Files

✅ `core/test_tool_command_processing.py`

Source Module: src/cleveragents/core/application.py

Tests: _process_tool_commands() method

Simple file operations with basic parameters
Nested JSON structures in tool parameters
Complex multi-level JSON from contract analysis
Multiple tool commands in one response
Regression test for nested JSON regex bug

Run: python -m tests.unit.core.test_tool_command_processing

Status: All 5 tests passing ✅

✅ `core/test_json_sanitization.py`

Source Module: src/cleveragents/core/application.py

Tests: _sanitize_json_string() method

JSON sanitization for malformed LLM responses
Control character handling and escape sequences
Valid JSON preservation

Run: pytest tests/unit/core/test_json_sanitization.py

Status: Requires pytest (optional dependency)

Running Tests

Run All Unit Tests:

# All unit tests
pytest tests/unit/

# Specific module
pytest tests/unit/core/
pytest tests/unit/agents/
pytest tests/unit/reactive/
pytest tests/unit/langgraph/
pytest tests/unit/templates/

Run Individual Test Files:

# Using module execution
python -m tests.unit.core.test_tool_command_processing

# Using pytest
pytest tests/unit/core/test_tool_command_processing.py

# Direct execution
python tests/unit/core/test_tool_command_processing.py

Run With Coverage:

pytest tests/unit/ --cov=cleveragents --cov-report=html

Test Organization Principles

1. Modular Structure

Each subdirectory mirrors the source code structure
Easy to locate tests for specific modules
Clear ownership and responsibility

2. One Test File Per Source File

src/cleveragents/core/application.py
  → tests/unit/core/test_application.py

src/cleveragents/agents/llm.py
  → tests/unit/agents/test_llm.py

3. Test Naming Convention

Test files: test_<source_module>.py
Test classes: Test<ClassName> or Test<Functionality>
Test methods: test_<specific_behavior>

4. Test Scope

Unit Tests: Test individual functions/methods in isolation
Integration Tests: Test component interactions (see tests/scripts/)
BDD Tests: Test user-facing features (see tests/features/)

Critical Bug Fixes Validated

1. Nested JSON Tool Execution Bug (Fixed)

File: src/cleveragents/core/application.py line 739

Issue: Regex pattern \{[^}]+\} couldn't handle nested braces in JSON parameters

Fix: Changed to (.*?) for non-greedy matching

Test: tests/unit/core/test_tool_command_processing.py

test_nested_json_file_write_command()
test_complex_nested_json_from_actual_usage()

Impact: Enables saving complex JSON analysis results to files (critical for Legal Contract Metadata Extractor)

Adding New Tests

When adding new unit tests:

Identify the source module you're testing
Create test file in corresponding tests/unit/<module>/ directory
Name file as test_<source_file>.py
Follow patterns from existing tests
Update README in the module folder
Run tests to ensure they pass

tests/features/ - BDD tests using Behave/Gherkin (75 feature files)
tests/scripts/ - Integration tests using shell scripts (3 scripts)
tests/fixtures/ - Test data and configuration files
tests/mocks/ - Mock implementations for external dependencies

Best Practices

Isolation: Unit tests should not depend on external services
Speed: Tests should run quickly (< 1 second each)
Clarity: Test names should clearly describe what's being tested
Coverage: Aim for high code coverage but focus on critical paths
Regression: Add tests for every bug fix to prevent recurrence

README.md

Unit Tests for CleverAgents

Directory Structure