# TestPyPI Verification Guide

This guide explains how to verify your fluxibly package installation from TestPyPI.

## Quick Start

### Option 1: Automated Test Script (Recommended)

Run the automated test script that handles everything:

```bash
# Test latest version
./scripts/test_testpypi.sh

# Test specific version
./scripts/test_testpypi.sh 0.1.0
```

This script will:
1. Create a fresh virtual environment
2. Install fluxibly from TestPyPI
3. Run comprehensive tests
4. Clean up automatically

### Option 2: Manual Testing

Create a test environment and run tests manually:

```bash
# Create and activate virtual environment
python3 -m venv test-env
source test-env/bin/activate

# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ \
            --extra-index-url https://pypi.org/simple/ \
            fluxibly

# Run the test suite
python tests/test_testpypi_install.py

# Cleanup
deactivate
rm -rf test-env
```

## Test Suite Details

The test suite ([tests/test_testpypi_install.py](tests/test_testpypi_install.py)) includes:

### Test 1: Imports
Verifies all main components can be imported:
- `fluxibly` package
- `WorkflowEngine`, `WorkflowConfig`, `WorkflowSession`
- `MCPClientManager`, `OrchestratorAgent`
- `run_workflow`, `run_batch_workflow`

### Test 2: Version
Checks that version information is accessible and valid.

### Test 3: Config Creation
Tests `WorkflowConfig` object creation with various parameters.

### Test 4: WorkflowEngine Creation
Verifies `WorkflowEngine` can be instantiated:
- From `WorkflowConfig` object
- Using `from_profile()` factory method

### Test 5: Workflow Execution (Optional)
If API keys are present, tests actual workflow execution:
- Requires `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
- Skipped in CI/CD environments (expected behavior)

### Test 6: MCPClientManager
Tests MCP client manager creation and basic properties.

### Test 7: Package Metadata
Verifies package documentation and exports.

## Expected Output

A successful test run should look like:

```
======================================================================
FLUXIBLY TESTPYPI INSTALLATION TEST SUITE
======================================================================

======================================================================
Test 1: Testing Imports
======================================================================
✓ Successfully imported fluxibly version 0.1.0
✓ Successfully imported MCPClientManager
✓ Successfully imported OrchestratorAgent
✓ Successfully imported WorkflowConfig
✓ Successfully imported WorkflowEngine
✓ Successfully imported WorkflowSession
✓ Successfully imported run_workflow
✓ Successfully imported run_batch_workflow

✓ All imports successful!

... [additional tests] ...

======================================================================
TEST SUMMARY
======================================================================
✓ PASS: Imports
✓ PASS: Version
✓ PASS: Config Creation
✓ PASS: Package Metadata
✓ PASS: WorkflowEngine Creation
✓ PASS: MCPClientManager
✓ PASS: Workflow Execution

Results: 7/7 tests passed

✓ All tests passed! Package is working correctly.
```

## Testing Specific Features

### Test Basic Import

```python
import fluxibly
print(f"Version: {fluxibly.__version__}")
```

### Test Workflow Engine

```python
from fluxibly import WorkflowEngine

# Create engine from profile
engine = WorkflowEngine.from_profile("default")
print(f"Engine created: {engine.name}")
```

### Test Configuration

```python
from fluxibly import WorkflowConfig

config = WorkflowConfig(
    name="test_workflow",
    agent_type="agent",
    profile="default",
    stateful=False
)
print(f"Config: {config.name}")
```

### Test With Profile Path

```python
from fluxibly import WorkflowEngine

# Test path-based profile loading
engine = WorkflowEngine.from_profile("/path/to/profile.yaml")
```

### Test Convenience Functions

```python
import asyncio
from fluxibly import run_workflow

async def test():
    # Note: Requires API key in environment
    response = await run_workflow(
        "What is 2+2?",
        profile="default"
    )
    print(response)

asyncio.run(test())
```

## Common Issues and Solutions

### Issue: Package Not Found

```
ERROR: Could not find a version that satisfies the requirement fluxibly
```

**Solution**: Make sure you're using both index URLs:
```bash
pip install --index-url https://test.pypi.org/simple/ \
            --extra-index-url https://pypi.org/simple/ \
            fluxibly
```

### Issue: Dependency Installation Fails

```
ERROR: Could not find a version that satisfies the requirement langchain
```

**Solution**: The `--extra-index-url https://pypi.org/simple/` ensures dependencies are installed from the main PyPI. Make sure both URLs are included.

### Issue: Import Errors

```
ModuleNotFoundError: No module named 'fluxibly'
```

**Solution**:
1. Verify installation: `pip list | grep fluxibly`
2. Check Python environment: `which python`
3. Reinstall if needed

### Issue: Configuration Not Found

```
FileNotFoundError: Framework configuration not found
```

**Solution**: When testing installed package, configuration files aren't included. Either:
1. Create minimal test configs
2. Use default settings that don't require external configs
3. Test only import and object creation (not initialization)

## Verification Checklist

Before publishing to PyPI, verify:

- [ ] Package installs without errors
- [ ] All main components import successfully
- [ ] Version number is correct
- [ ] Package metadata is accurate
- [ ] README renders correctly (check TestPyPI project page)
- [ ] All dependencies install from PyPI
- [ ] Basic functionality works (config creation, engine creation)
- [ ] No unexpected errors in test output

## Automated CI/CD Testing

You can integrate this test into your CI/CD pipeline:

```yaml
# .github/workflows/test-testpypi.yml
name: Test TestPyPI Installation

on:
  workflow_dispatch:
  release:
    types: [published]

jobs:
  test-testpypi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Run TestPyPI installation test
        run: |
          chmod +x scripts/test_testpypi.sh
          ./scripts/test_testpypi.sh
```

## Next Steps

After successful TestPyPI verification:

1. **Review package on TestPyPI**:
   - Visit: https://test.pypi.org/project/fluxibly/
   - Check README rendering
   - Verify metadata display
   - Review version history

2. **Test in different environments**:
   - Different Python versions (3.11, 3.12)
   - Different operating systems (macOS, Linux, Windows)
   - Different installation methods (pip, uv, poetry)

3. **Publish to PyPI**:
   - Follow [PUBLISHING.md](PUBLISHING.md) for production release
   - Use `python3 -m twine upload dist/*`

## Resources

- TestPyPI Project Page: https://test.pypi.org/project/fluxibly/
- PyPI Publishing Guide: [PUBLISHING.md](PUBLISHING.md)
- Test Suite: [tests/test_testpypi_install.py](tests/test_testpypi_install.py)
- Automated Test Script: [scripts/test_testpypi.sh](scripts/test_testpypi.sh)
