mirror of
https://github.com/katanemo/plano.git
synced 2026-06-17 15:25:17 +02:00
fix(www): remove from tools testing.md
This commit is contained in:
Musa
parent
d2386602e2
commit
8d4e0eccbe
1 changed files with 0 additions and 342 deletions
|
|
@ -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 <command>
|
||||
# OR if installed
|
||||
archgw <command>
|
||||
```
|
||||
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 <command> [args]
|
||||
|
||||
# Or if installed:
|
||||
archgw <command> [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
|
||||
Loading…
Add table
Add a link
Reference in a new issue