bottest/PROMPT.md

# BotTest Development Prompt

**Version:** 6.1.0  
**Purpose:** Test infrastructure for General Bots ecosystem

---

## Weekly Maintenance - EVERY MONDAY

### Package Review Checklist

**Every Monday, review the following:**

1. **Dependency Updates**
   ```bash
   cargo outdated
   cargo audit
   ```

2. **Package Consolidation Opportunities**
   - Check if new crates can replace custom code
   - Look for crates that combine multiple dependencies
   - Review `Cargo.toml` for redundant dependencies

3. **Code Reduction Candidates**
   - Custom mock implementations that can use crates
   - Test utilities that have crate equivalents
   - Boilerplate that can be replaced with macros

4. **Test Infrastructure Updates**
   - Check for new testing patterns
   - Review mock server libraries
   - Update fixture generation approaches

### Packages to Watch

| Area | Potential Packages | Purpose |
|------|-------------------|---------|
| Mocking | `wiremock`, `mockall` | Simplify mock creation |
| Assertions | `assertables`, `pretty_assertions` | Better test output |
| Fixtures | `fake`, `proptest` | Generate test data |
| Async Testing | `tokio-test` | Async test utilities |

---

## CRITICAL RULE

🚫 **NO .md FILES IN ROOT OF ANY PROJECT**

All documentation goes in `botbook/src/17-testing/`:
- `README.md` - Testing overview
- `e2e-testing.md` - E2E test guide
- `architecture.md` - Testing architecture
- `performance.md` - Performance testing
- `best-practices.md` - Best practices

This PROMPT.md is the ONLY exception (it's for developers).

---

## Core Principle

**Reuse botserver bootstrap code** - Don't duplicate installation logic. The bootstrap module already knows how to install PostgreSQL, MinIO, Redis. We wrap it with test-specific configuration (custom ports, temp directories).

---

## Architecture

**IMPORTANT:** E2E tests always use `USE_BOTSERVER_BOOTSTRAP=1` mode. No global PostgreSQL or other services are required. The botserver handles all service installation during bootstrap.

```
TestHarness::full() / E2E Tests
    │
    ├── Allocate unique ports (15000+)
    ├── Create ./tmp/bottest-{uuid}/
    │
    ├── Start mock servers only
    │   ├── MockZitadel (wiremock)
    │   └── MockLLM (wiremock)
    │
    ├── Start botserver with --stack-path
    │   └── Botserver auto-installs:
    │       ├── PostgreSQL (tables)
    │       ├── MinIO (drive)
    │       └── Redis (cache)
    │
    └── Return TestContext

TestContext provides:
    - db_pool() -> Database connection
    - minio_client() -> S3 client
    - redis_client() -> Redis client
    - mock_*() -> Mock server controls

On Drop:
    - Stop all services
    - Remove temp directory
```

---

## Code Style

Same as botserver PROMPT.md:
- KISS, NO TALK, SECURED CODE ONLY
- No comments, no placeholders
- Complete, production-ready code
- Return 0 warnings

---

## Test Categories

### Unit Tests (no services)
```rust
#[test]
fn test_pure_logic() {
    // No TestHarness needed
    // Test pure functions directly
}
```

### Integration Tests (with services)
```rust
#[tokio::test]
async fn test_with_database() {
    let ctx = TestHarness::quick().await.unwrap();
    let pool = ctx.db_pool().await.unwrap();
    // Use real database
}
```

### E2E Tests (with browser)
```rust
#[tokio::test]
async fn test_user_flow() {
    let ctx = TestHarness::full().await.unwrap();
    let server = ctx.start_botserver().await.unwrap();
    let browser = Browser::new().await.unwrap();
    // Automate browser
}
```

---

## Mock Server Patterns

### Expect specific calls
```rust
ctx.mock_llm().expect_completion("hello", "Hi there!");
```

### Verify calls were made
```rust
ctx.mock_llm().assert_called_times(2);
```

### Simulate errors
```rust
ctx.mock_llm().next_call_fails(500, "Internal error");
```

---

## Fixture Patterns

### Factory functions
```rust
let user = fixtures::admin_user();
let bot = fixtures::bot_with_kb();
let session = fixtures::active_session(&user, &bot);
```

### Insert into database
```rust
ctx.insert(&user).await;
ctx.insert(&bot).await;
```

---

## Cleanup

Always automatic via Drop trait. But can force:
```rust
ctx.cleanup().await;  // Explicit cleanup
```

---

## Parallel Safety

- Each test gets unique ports via PortAllocator
- Each test gets unique temp directory
- No shared state between tests
- Safe to run with `cargo test -j 8`

---

## Documentation Location

For guides, tutorials, and reference:
→ Use `botbook/src/17-testing/`

Examples:
- E2E testing setup → `botbook/src/17-testing/e2e-testing.md`
- Architecture details → `botbook/src/17-testing/architecture.md`
- Performance tips → `botbook/src/17-testing/performance.md`

Never create .md files at:
- ✗ Root of bottest/
- ✗ Root of botserver/
- ✗ Root of botapp/
- ✗ Any project root

All non-PROMPT.md documentation belongs in botbook.