diff --git a/arch/tools/TESTING.md b/arch/tools/TESTING.md deleted file mode 100644 index 7dace775..00000000 --- a/arch/tools/TESTING.md +++ /dev/null @@ -1,342 +0,0 @@ -# Manual Testing & Development Guide for CLI - -This guide explains how to manually test and develop the `archgw` CLI tool. - -## Quick Start - Development Setup - -### 1. Set Up Development Environment - -From the `arch/tools` directory: - -```bash -# Create and activate virtual environment -python -m venv venv -source venv/bin/activate # On Mac/Linux -# OR -venv\Scripts\activate # On Windows - -# Install dependencies in development mode -poetry install -``` - -### 2. Run CLI in Development Mode - -You have two options to run the CLI during development: - -#### Option A: Run directly with Python (Fastest for iteration) - -```bash -# From arch/tools directory -python -m cli.main --help -python -m cli.main build -python -m cli.main up --path /path/to/config -``` - -#### Option B: Install in editable mode (Recommended) - -```bash -# Install the package in editable/development mode -pip install -e . - -# Now you can use 'archgw' command directly -archgw --help -archgw build -archgw up --path /path/to/config -``` - -**Note**: After making changes to the code, you don't need to reinstall - changes are immediately available with editable install! - -## Manual Testing Workflow - -### Testing Individual Commands - -Here's how to test each CLI command manually: - -### 1. Test `build` Command - -```bash -# Test building the Docker image -archgw build - -# Or with Python directly -python -m cli.main build -``` - -**What to check:** -- Docker image builds successfully -- No errors in output -- Image is created with correct tag - -### 2. Test `up` Command - -```bash -# Test with a config file path -archgw up --path /path/to/demo/arch_config.yaml - -# Test with explicit file -archgw up /path/to/arch_config.yaml - -# Test with foreground mode -archgw up --path /path/to/config --foreground - -# Test error case - non-existent file -archgw up --path /nonexistent/path -``` - -**What to check:** -- Config file is found correctly -- Validation runs -- Docker container starts -- Health checks pass -- Error messages are clear when things fail - -### 3. Test `down` Command - -```bash -# Stop the gateway -archgw down -``` - -**What to check:** -- Container stops cleanly -- No errors on shutdown - -### 4. Test `logs` Command - -```bash -# View logs -archgw logs - -# Follow logs in real-time -archgw logs --follow - -# View debug logs -archgw logs --debug --follow -``` - -**What to check:** -- Logs are readable -- Follow mode works correctly -- Debug mode shows additional information - -### 5. Test `generate_prompt_targets` Command - -```bash -# Generate targets from a Python file -archgw generate-prompt-targets --f /path/to/your/file.py -``` - -**What to check:** -- Targets are generated correctly -- Output format is valid -- Handles different Python function signatures - -### 6. Test `cli_agent` Command - -```bash -# Start CLI agent (requires archgw to be running) -archgw cli-agent claude --path /path/to/config - -# With custom settings -archgw cli-agent claude --path /path/to/config --settings '{"key": "value"}' -``` - -**What to check:** -- Agent connects to running gateway -- Settings are passed correctly -- Error handling when gateway isn't running - -### 7. Test Version Command - -```bash -# Check version -archgw --version -``` - -## Development Tips - -### Quick Iteration Cycle - -1. **Make changes** to CLI code in `cli/` directory -2. **Test immediately** - no reinstall needed with editable install: - ```bash - python -m cli.main - # OR if installed - archgw - ``` -3. **Check output** and iterate - -### Testing with Real Config Files - -Use the demo configs in the repo: - -```bash -# From arch/tools directory -cd ../../demos/samples_python/weather_forecast - -# Test with this config -archgw up arch_config.yaml - -# Or test from tools directory -archgw up ../../demos/samples_python/weather_forecast/arch_config.yaml -``` - -### Debugging Tips - -1. **Add print statements** for quick debugging: - ```python - import sys - print(f"DEBUG: Variable value: {variable}", file=sys.stderr) - ``` - -2. **Use Python debugger**: - ```python - import pdb; pdb.set_trace() - ``` - -3. **Check Docker status** manually: - ```bash - docker ps - docker logs archgw - docker inspect archgw - ``` - -4. **Test individual functions** in Python REPL: - ```bash - python - >>> from cli.utils import find_config_file - >>> find_config_file(".", None) - ``` - -### Common Test Scenarios - -#### Test Error Handling - -```bash -# Test missing config file -archgw up --path /nonexistent - -# Test invalid config file -archgw up /path/to/invalid_config.yaml - -# Test missing environment variables -# (remove required env vars and test) -archgw up --path /path/to/config -``` - -#### Test Edge Cases - -```bash -# Test with minimal config -archgw up --path /path/to/minimal_config.yaml - -# Test with complex config -archgw up --path /path/to/complex_config.yaml - -# Test with different paths -archgw up --path . -archgw up --path /absolute/path -archgw up relative/path/config.yaml -``` - -## Example: Testing a Specific Feature - -Let's say you're working on improving the `find_config_file` function. Here's how to test it: - -```bash -# Start Python REPL -python - -# Import and test ->>> from cli.utils import find_config_file ->>> import os ->>> find_config_file(".", None) -'/absolute/path/to/arch/tools/arch_config.yaml' - -# Test with explicit file ->>> find_config_file(".", "/path/to/config.yaml") -'/path/to/config.yaml' - -# Test error cases ->>> find_config_file("/nonexistent", None) -# Check what happens -``` - -## File Structure Reference - -When developing, you'll primarily work with: - -- `cli/main.py` - Main CLI commands and entry point -- `cli/core.py` - Core functionality (start_arch, stop_docker_container, etc.) -- `cli/utils.py` - Utility functions -- `cli/docker_cli.py` - Docker-related operations -- `cli/config_generator.py` - Config validation and generation -- `cli/targets.py` - Prompt target generation -- `cli/consts.py` - Constants - -## Quick Reference: Common Commands - -```bash -# Setup (one time) -cd arch/tools -python -m venv venv -source venv/bin/activate -poetry install -pip install -e . # For editable install - -# Development workflow -# 1. Edit code in cli/*.py -# 2. Test immediately: -python -m cli.main [args] - -# Or if installed: -archgw [args] - -# Common test commands: -archgw --version # Check version -archgw --help # See all commands -archgw build # Build Docker image -archgw up --path /path/to/config # Start gateway -archgw down # Stop gateway -archgw logs --follow # View logs -``` - -## Troubleshooting - -### CLI command not found -- Make sure you activated the virtual environment -- If using editable install, verify: `pip list | grep archgw` -- Try: `python -m cli.main` instead - -### Changes not reflected -- If using editable install, changes should be immediate -- If not, reinstall: `pip install -e .` -- Check you're editing the right file - -### Docker issues -- Ensure Docker is running: `docker ps` -- Check container status: `docker ps -a | grep archgw` -- View logs: `docker logs archgw` - -## Finding Demo Configs to Test With - -The repository has several demo configs you can use for testing: - -```bash -# List available demos -ls ../../demos/samples_python/*/arch_config.yaml - -# Examples: -# - ../../demos/samples_python/weather_forecast/arch_config.yaml -# - ../../demos/samples_python/currency_exchange/arch_config.yaml -# - ../../demos/samples_python/human_resources_agent/arch_config.yaml -``` - -## Tips for Effective Manual Testing - -1. **Test one thing at a time** - Make a small change, test it, then move on -2. **Test both success and failure cases** - Don't just test happy paths -3. **Use real configs** - Test with actual demo configs to catch real-world issues -4. **Check error messages** - Make sure error messages are helpful -5. **Test edge cases** - Empty files, missing fields, invalid values -6. **Keep notes** - Document what works and what doesn't as you develop