Copier Template: Add custom slash command for systematic test writing.

Create write-tests.md command that guides LLMs through comprehensive test
creation following project testing principles. Command emphasizes dependency
injection over monkey-patching, performance-conscious patterns with pyfakefs,
and systematic numbering conventions.

Includes safety requirements, code analysis phases, and success criteria
checklist to ensure tests improve coverage while maintaining code quality
and architectural integrity.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: emcd

documentation/common/tests.rst

@@ -73,9 +73,10 @@ Test Directory Structure
         ├── fixtures.py              # Common test fixtures and utilities
         ├── test_000_package.py      # Package-level tests
         ├── test_010_internals.py    # Internal utilities
-        ├── test_100_core.py         # Core public API
-        ├── test_200_advanced.py     # Advanced features
-        └── test_900_integration.py  # Integration tests
+        ├── test_100_<layer 0>.py    # Lowest levels of public API
+        ├── test_200_<layer 1>.py    # Lower levels of public API
+        ├── ...                      # Higher levels of API
+        └── test_500_integration.py  # Top levels of API; Integration tests
 
 Numbering System
 -------------------------------------------------------------------------------
@@ -96,10 +97,10 @@ Within test modules, number test functions similarly::
 
     def test_000_basic_functionality():
         ''' Basic feature works as expected. '''
-        
+
     def test_100_error_handling():
         ''' Error conditions are handled gracefully. '''
-        
+
     def test_200_advanced_scenarios():
         ''' Advanced usage patterns work correctly. '''
 
@@ -133,7 +134,7 @@ The most important testing pattern. Inject dependencies via parameters::
     async def test_process_data():
         def mock_processor( data ):
             return f"processed: {data}"
-        
+
         result = await process_data( "test", processor = mock_processor )
         assert result == "processed: test"
 
@@ -142,7 +143,7 @@ Constructor injection for objects::
     @dataclass( frozen = True )
     class DataProcessor:
         validator: Callable[ [ str ], bool ] = default_validator
-        
+
         def process( self, data: str ) -> str:
             if not self.validator( data ):
                 raise ValueError( "Invalid data" )
@@ -152,7 +153,7 @@ Constructor injection for objects::
     def test_data_processor():
         def always_valid( data ):
             return True
-        
+
         processor = DataProcessor( validator = always_valid )
         result = processor.process( "test" )
         assert result == "TEST"
@@ -181,7 +182,7 @@ only when necessary::
             temp_path = Path( temp_dir )
             config_file = temp_path / 'config.toml'
             config_file.write_text( '[section]\nkey = "value"' )
-            
+
             result = await async_process_config_file( config_file )
             assert result.key == 'value'
 
@@ -198,14 +199,14 @@ When to Mock
 Example with third-party mock::
 
     import httpx
-    
+
     def test_http_client():
         def handler( request ):
             return httpx.Response( 200, json = { "result": "success" } )
-        
+
         transport = httpx.MockTransport( handler )
         client = httpx.Client( transport = transport )
-        
+
         response = client.get( "https://example.com/api" )
         assert response.json() == { "result": "success" }
 
@@ -250,7 +251,7 @@ Development Environment
 * **Always use hatch environment** for all testing commands::
 
     hatch --env develop run pytest          # run tests
-    hatch --env develop run linters         # run linters  
+    hatch --env develop run linters         # run linters
     hatch --env develop run testers         # run full test suite with coverage
 
 * **Test performance**: The elapsed time reported by ``pytest`` should be
@@ -287,11 +288,11 @@ Mock frame chains for call stack simulation (document justification)::
         external_frame = MagicMock()
         external_frame.f_code.co_filename = '/external/caller.py'
         external_frame.f_back = None
-        
+
         internal_frame = MagicMock()
         internal_frame.f_code.co_filename = '/internal/module.py'
         internal_frame.f_back = external_frame
-        
+
         with patch( 'inspect.currentframe', return_value = internal_frame ):
             result = module._discover_invoker_location()
             assert result == Path( '/external' )
@@ -302,7 +303,7 @@ Resource Management
 Use ``ExitStack`` for multiple temporary resources::
 
     from contextlib import ExitStack
-    
+
     def test_multiple_temp_files():
         with ExitStack() as stack:
             temp1 = stack.enter_context(
@@ -321,7 +322,7 @@ Test error conditions and recovery paths::
             config[ 'application' ][ 'safe_mode' ] = True
         except Exception:
             config[ 'fallback' ] = True  # Apply fallback
-    
+
     @pytest.mark.asyncio
     async def test_error_recovery():
         async with contextlib.AsyncExitStack() as exits:
@@ -406,4 +407,4 @@ Benefits of This Approach
 3. **Maintainable tests** - less fragile than monkey-patching
 4. **Preserved architecture** - immutability provides thread safety
 5. **Optimized performance** - strategic use of in-memory filesystems
-6. **Comprehensive coverage** - systematic targeting of uncovered branches
+6. **Comprehensive coverage** - systematic targeting of uncovered branches

template/.auxiliary/configuration/claude/commands/write-tests.md

@@ -0,0 +1,182 @@
+---
+allowed-tools: Bash(hatch --env develop run:*), Bash(git status), Bash(git log:*), Bash(echo:*), Bash(ls:*), Bash(find:*), LS, Read, Glob, Grep, Write, Edit, MultiEdit
+description: Write comprehensive tests following project testing guidelines and improve coverage
+---
+
+# Write Tests
+
+**NOTE: This is an experimental workflow! If anything seems unclear or missing,
+please stop for consultation with the user.**
+
+For systematic test creation following project testing guidelines and conventions.
+
+Test requirements: `$ARGUMENTS`
+
+**CRITICAL**: Apply project testing principles consistently.
+**HALT if**:
+- No test requirements are provided
+- Target code cannot be analyzed
+- Testing principles would be violated
+
+## Context
+
+- Current git status: !`git status --porcelain`
+- Current branch: !`git branch --show-current`
+- Current test coverage: !`hatch --env develop run coverage report --skip-covered || echo "No coverage data available"`
+- Existing test structure: !`find tests -name "*.py" | head -20`
+- Test README: !`ls tests/README.md 2>/dev/null && echo "Present" || echo "Missing"`
+
+## Prerequisites
+
+Ensure that you:
+- have verified access to / read target code modules
+- understand what specific tests need to be written
+- have read any relevant `CLAUDE.md` file
+- understand the [test-writing guidelines](https://raw.githubusercontent.com/emcd/python-project-common/refs/heads/master/documentation/common/tests.rst)
+
+## Testing Principles (from project guidelines)
+
+**Core Principles:**
+1. **Dependency Injection Over Monkey-Patching**: Use injectable dependencies
+   for testability
+2. **Performance-Conscious**: Prefer in-memory filesystems (pyfakefs) over temp
+   directories
+3. **Avoid Monkey-Patching**: Never patch internal code; use dependency
+   injection instead
+4. **100% Coverage Goal**: Aim for complete line and branch coverage
+5. **Test Behavior, Not Implementation**: Focus on observable behavior and
+   contracts
+
+**Anti-Patterns to Avoid:**
+- Monkey-patching internal code (will fail with immutable objects)
+- Excessive mocking of internal components
+- Testing implementation details vs. behavior
+- Using temp directories when pyfakefs suffices
+
+**Organization:**
+- Follow the systematic numbering conventions detailed in the test guidelines
+
+## Safety Requirements
+
+**CRITICAL**: You MUST halt the process and consult with the user if ANY of the
+following occur:
+
+- **Anti-Pattern Detection**: If proposed tests violate project principles
+- **Coverage Regression**: If tests would reduce existing coverage
+- **Architecture Conflicts**: If tests require monkey-patching internal code
+- **Numbering Conflicts**: If test numbering clashes with existing conventions
+- **Missing Dependencies**: If required test fixtures or dependencies are
+  unavailable
+
+**Your responsibilities:**
+- Follow project style and test-writing conventions exactly.
+- Use dependency injection patterns consistently.
+- Prefer pyfakefs for filesystem operations.
+- Maintain systematic test numbering.
+- Ensure tests validate behavior, not implementation.
+
+## Test Writing Process
+
+Execute the following steps for test requirements: `$ARGUMENTS`
+
+### 1. Code Analysis Phase
+Examine the target code to understand testing needs:
+
+**For each target file:**
+- Read the source code to understand public API
+- Identify functions/classes that need testing
+- Note dependency injection points
+- Check for existing test coverage gaps
+
+### 2. Test Structure Planning
+Determine appropriate test organization and categories:
+
+**Review existing test structure and plan test numbering following project conventions.**
+
+**Test Categories to Include:**
+- **Basic Functionality Tests (000-099):** Happy path scenarios, input validation, basic error conditions
+- **Feature-Specific Tests (100+ blocks):** Each public function/class gets its own 100-block with normal usage patterns, edge cases, and error handling
+- **Integration Tests (higher numbers):** Cross-module interactions and end-to-end workflows
+
+### 3. Test Implementation
+Create tests following project conventions:
+
+**Key Implementation Guidelines:**
+- Use dependency injection for all external dependencies
+- Prefer `pyfakefs.Patcher()` for filesystem operations
+- Mock only third-party services, never internal code
+- Include docstrings explaining what behavior is tested
+- Follow existing naming conventions and code style
+
+### 5. Coverage Validation
+Verify tests improve coverage without regressions:
+```bash
+hatch --env develop run testers
+hatch --env develop run coverage report --show-missing
+```
+
+**CRITICAL - VERIFY COVERAGE IMPROVEMENT:**
+- Run full test suite to ensure no regressions
+- Check that new tests increase overall coverage
+- Verify no existing functionality is broken
+- Confirm tests follow project numbering conventions
+
+### 6. Code Quality Validation
+Ensure tests meet project standards:
+```bash
+hatch --env develop run linters
+```
+
+**Requirements:**
+- All linting checks must pass
+- No violations of project coding standards
+- Test docstrings are clear and descriptive
+- Proper imports and dependencies
+
+## Test Pattern Examples
+
+**Dependency Injection Pattern:**
+```python
+async def test_100_process_with_custom_processor( ):
+    ''' Process function accepts custom processor via injection. '''
+    def mock_processor( data ):
+        return f"processed: {data}"
+    
+    result = await process_data( "test", processor = mock_processor )
+    assert result == "processed: test"
+```
+
+**Filesystem Operations (Preferred):**
+```python
+def test_200_config_file_processing( ):
+    ''' Configuration files are processed correctly. '''
+    with Patcher( ) as patcher:
+        fs = patcher.fs
+        fs.create_file( '/fake/config.toml', contents = '[section]\nkey="value"' )
+        
+        result = process_config_file( Path( '/fake/config.toml' ) )
+        assert result.key == 'value'
+```
+
+**Error Handling:**
+```python
+def test_300_invalid_input_handling( ):
+    ''' Invalid input raises appropriate exceptions. '''
+    with pytest.raises( ValueError, match = "Invalid data format" ):
+        process_invalid_data( "malformed" )
+```
+
+## Success Criteria
+
+Tests are complete when:
+- [ ] Coverage has measurably improved
+- [ ] All new tests pass consistently
+- [ ] No existing tests are broken
+- [ ] Linting passes without issues
+- [ ] Tests follow project numbering conventions
+- [ ] Dependency injection is used appropriately
+- [ ] No monkey-patching of internal code
+- [ ] Performance-conscious patterns are applied
+
+**Note**: Always run full validation (`hatch --env develop run testers && hatch
+--env develop run linters`) before considering the task complete.