initial release

tests/README.md

@@ -0,0 +1,123 @@
+<!--
+SPDX-FileCopyrightText: 2025 Alexander Kalinovsky <a@k8y.ru>
+
+SPDX-License-Identifier: MIT
+-->
+
+# CLI Tests
+
+This directory contains comprehensive tests for the QuickBot CLI functionality.
+
+## Test Structure
+
+### `conftest.py`
+Contains pytest fixtures and configuration:
+- `cli_runner`: Typer CLI test runner
+- `temp_dir`: Temporary directory for testing
+- `mock_template_dir`: Mock template directory structure
+- `mock_typer_prompt`: Mock for typer.prompt to avoid interactive input
+- `mock_typer_secho`: Mock for typer.secho output
+- `mock_typer_echo`: Mock for typer.echo output
+- `mock_subprocess_run`: Mock for subprocess.run
+
+### `test_cli.py`
+Core unit tests covering:
+- Template specification loading
+- Variable prompting and validation
+- Template file rendering
+- Post-task execution
+- Optional module inclusion/exclusion
+- CLI command functionality
+- Help and argument parsing
+
+### `test_integration.py`
+Integration tests covering:
+- Full project generation workflow
+- Module inclusion/exclusion scenarios
+- Overwrite functionality
+- End-to-end CLI operations
+
+### `test_edge_cases.py`
+Edge case and error handling tests:
+- Boundary conditions
+- Error scenarios
+- Malformed input handling
+- Deep nesting and large files
+
+## Running Tests
+
+### Using pytest directly
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=src/quickbot_cli --cov-report=html
+
+# Run specific test file
+pytest tests/test_cli.py
+
+# Run specific test class
+pytest tests/test_cli.py::TestLoadTemplateSpec
+
+# Run specific test method
+pytest tests/test_cli.py::TestLoadTemplateSpec::test_load_template_spec_with_valid_file
+```
+
+### Using the test runner script
+```bash
+python run_tests.py
+```
+
+### Using development dependencies
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest
+```
+
+## Test Coverage
+
+The test suite covers:
+
+- **Template Loading**: YAML parsing, error handling, default values
+- **Variable Handling**: Interactive prompts, validation, choices, regex
+- **File Rendering**: Jinja2 templating, binary files, directory structure
+- **Post Tasks**: Conditional execution, subprocess handling, error recovery
+- **Optional Modules**: Alembic and Babel inclusion/exclusion
+- **CLI Interface**: Command parsing, help, arguments, error handling
+- **Integration**: End-to-end workflows, file operations, edge cases
+
+## Adding New Tests
+
+When adding new tests:
+
+1. **Unit Tests**: Add to appropriate test class in `test_cli.py`
+2. **Integration Tests**: Add to `test_integration.py`
+3. **Edge Cases**: Add to `test_edge_cases.py`
+4. **Fixtures**: Add to `conftest.py` if reusable
+
+### Test Naming Convention
+- Test files: `test_*.py`
+- Test classes: `Test*`
+- Test methods: `test_*`
+
+### Test Documentation
+Each test should have a descriptive docstring explaining what it tests and why.
+
+## Mocking Strategy
+
+- **External Dependencies**: Use `unittest.mock.patch` for file system, subprocess, etc.
+- **User Input**: Mock `typer.prompt` to avoid interactive input during tests
+- **Output**: Mock `typer.secho` and `typer.echo` to capture and verify output
+- **File Operations**: Use temporary directories to avoid affecting the real file system
+
+## Continuous Integration
+
+Tests are configured to run with:
+- Coverage reporting (HTML, XML, terminal)
+- Strict marker validation
+- Verbose output for debugging
+- Short traceback format for readability