bottest/README_E2E_TESTING.md

E2E Testing for General Bots Platform

Quick Start

Run the complete platform flow test (loads UI → starts BotServer → login → chat → logout):

cd gb/bottest

# Without browser (HTTP-only tests)
cargo test --test e2e test_platform_loading_http_only -- --nocapture
cargo test --test e2e test_botserver_startup -- --nocapture

# With browser (requires WebDriver)
# 1. Start WebDriver first:
chromedriver --port=4444

# 2. In another terminal:
cargo test --test e2e test_complete_platform_flow_login_chat_logout -- --nocapture

What Gets Tested

The complete platform flow test validates:

1. Platform Loading ✓

   • UI assets are served
   • API endpoints respond
   • Database migrations completed

2. BotServer Initialization ✓

   • Service is running
   • Health checks pass
   • Configuration loaded

3. User Authentication ✓

   • Login page loads
   • Credentials accepted
   • Session created
   • Redirected to dashboard/chat

4. Chat Interaction ✓

   • Chat interface loads
   • Messages can be sent
   • Bot responses received
   • Message history persists

5. Logout Flow ✓

   • Logout button works
   • Session invalidated
   • Redirect to login page
   • Protected routes blocked

Test Files

File	Purpose
tests/e2e/platform_flow.rs	⭐ Complete user journey test
tests/e2e/auth_flow.rs	Authentication scenarios
tests/e2e/chat.rs	Chat message flows
tests/e2e/dashboard.rs	Dashboard functionality
tests/e2e/mod.rs	Test context and setup

Running Specific Tests

# Platform flow (complete journey)
cargo test --test e2e test_complete_platform_flow_login_chat_logout -- --nocapture

# Platform loading only (no browser needed)
cargo test --test e2e test_platform_loading_http_only -- --nocapture

# BotServer startup
cargo test --test e2e test_botserver_startup -- --nocapture

# Simpler login + chat
cargo test --test e2e test_login_and_chat_flow -- --nocapture

# Platform responsiveness
cargo test --test e2e test_platform_responsiveness -- --nocapture

# All E2E tests
cargo test --test e2e -- --nocapture

Environment Variables

# Show browser window (for debugging)
HEADED=1 cargo test --test e2e -- --nocapture

# Custom WebDriver URL
WEBDRIVER_URL=http://localhost:4445 cargo test --test e2e -- --nocapture

# Skip E2E tests
SKIP_E2E_TESTS=1 cargo test

# Verbose logging
RUST_LOG=debug cargo test --test e2e -- --nocapture

# Run single-threaded (clearer output)
cargo test --test e2e -- --nocapture --test-threads=1

Prerequisites

For HTTP-only Tests

• Rust toolchain
• BotServer compiled

For Browser Tests (Full E2E)

• Chrome/Chromium installed
• WebDriver (chromedriver) running on port 4444
• All HTTP test prerequisites

Setup WebDriver

Option 1: Local Installation

# Download chromedriver from https://chromedriver.chromium.org/
# Place in PATH, then:
chromedriver --port=4444

Option 2: Docker

docker run -d -p 4444:4444 selenium/standalone-chrome

Option 3: Docker Compose

# Use provided docker-compose.yml if available
docker-compose up -d webdriver

Architecture: Temporary Stack (Future)

The E2E tests are designed to work with temporary, isolated stacks:

# When implemented, this will spawn a temporary environment:
botserver --temp-stack

# This creates: /tmp/botserver-test-{timestamp}-{random}/
# With: PostgreSQL, Redis, MinIO, Mock LLM, Mock Auth
# Automatic cleanup after tests

Benefits:

• ✓ Isolation - Each test runs in separate environment
• ✓ Reproducibility - Same setup every time
• ✓ Automation - No manual setup required
• ✓ Cleanup - Automatic resource management
• ✓ Debugging - Optionally preserve stack on failure

See TEMP_STACK_SETUP.md for implementation details.

Common Issues

WebDriver Not Available

# Solution: Start WebDriver first
chromedriver --port=4444
# or
docker run -d -p 4444:4444 selenium/standalone-chrome

Tests Hang or Timeout

# Run with timeout and single thread
timeout 120s cargo test --test e2e test_name -- --nocapture --test-threads=1

# With verbose logging
RUST_LOG=debug timeout 120s cargo test --test e2e test_name -- --nocapture --test-threads=1

Port Already in Use

# Kill existing processes
pkill -f chromedriver
pkill -f "botserver"
pkill -f "postgres"
pkill -f "redis-server"

Browser Connection Issues

# Use different WebDriver port
WEBDRIVER_URL=http://localhost:4445 cargo test --test e2e -- --nocapture

Test Structure

Each test follows this pattern:

#[tokio::test]
async fn test_example() {
    // 1. Setup context
    let ctx = E2ETestContext::setup_with_browser().await?;
    
    // 2. Get browser
    let browser = ctx.browser.as_ref().unwrap();
    
    // 3. Run test steps
    browser.navigate(&ctx.base_url()).await?;
    
    // 4. Verify results
    assert!(some_condition);
    
    // 5. Cleanup (automatic)
    ctx.close().await;
}

Debugging

View Test Output

# Show all output
cargo test --test e2e test_name -- --nocapture

# Show with timestamps
RUST_LOG=debug cargo test --test e2e test_name -- --nocapture

# Save to file
cargo test --test e2e test_name -- --nocapture 2>&1 | tee test_output.log

See Browser in Action

# Run with visible browser
HEADED=1 cargo test --test e2e test_name -- --nocapture --test-threads=1

# This shows what the test is doing in real-time

Check Server Logs

# BotServer logs while tests run
tail -f /tmp/bottest-*/botserver.log

# In another terminal:
cargo test --test e2e test_name -- --nocapture

Performance

• Platform loading test: ~2-3 seconds
• BotServer startup test: ~5-10 seconds
• Complete flow with browser: ~30-45 seconds
• Full E2E test suite: ~2-3 minutes

Integration with CI/CD

Example GitHub Actions workflow:

name: E2E Tests
on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    services:
      chromedriver:
        image: selenium/standalone-chrome
    steps:
      - uses: actions/checkout@v3
      - uses: actions-rs/toolchain@v1
      - run: cd gb/bottest && cargo test --test e2e -- --nocapture

What's Tested in Each Scenario

test_complete_platform_flow_login_chat_logout

✓ Platform health check ✓ API responsiveness
✓ Login with credentials ✓ Dashboard/chat visibility ✓ Send message to bot ✓ Receive bot response ✓ Message appears in history ✓ Logout button works ✓ Session invalidated ✓ Protected routes blocked

test_platform_loading_http_only

✓ Platform health endpoint ✓ API endpoints available ✓ No browser required

test_botserver_startup

✓ Server process running ✓ Health checks pass ✓ No browser required

test_login_and_chat_flow

✓ Minimal path through login and chat ✓ Requires browser

Next Steps

1. Run a simple test first:

   cargo test --test e2e test_platform_loading_http_only -- --nocapture
   

2. Setup WebDriver for browser tests:

   chromedriver --port=4444
   

3. Run the complete flow:

   cargo test --test e2e test_complete_platform_flow_login_chat_logout -- --nocapture
   

4. Add custom tests in tests/e2e/ using the same pattern

5. Integrate into CI/CD using the GitHub Actions example above

Documentation

• E2E Testing Plan - Architecture and design
• Temporary Stack Setup - Advanced: Using isolated test stacks
• Test Harness - Test utilities and helpers
• Platform Flow Tests - Complete implementation

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review test output with --nocapture flag
3. Run with RUST_LOG=debug for detailed logging
4. Check server logs in /tmp/bottest-*/
5. Use HEADED=1 to watch browser in action

Key Metrics

Running test_complete_platform_flow_login_chat_logout provides:

• Response Times: Platform, API, and chat latencies
• Resource Usage: Memory and CPU during test
• Error Rates: Login failures, message timeouts, etc.
• Session Management: Login/logout cycle validation
• Message Flow: End-to-end chat message delivery

These metrics help identify performance bottlenecks and regressions.