Testing Scripts Guide

This guide documents all available testing, debugging, and development scripts for the BILL Agent. All scripts use the unified bun start <script-name> format for consistency.

🚀 Quick Reference

To see all available scripts:

bun start

---

📋 Script Categories

🔧 Core Services

Start Main Services

bun start logger-ui         # Start logging UI for monitoring
bun start twitter           # Start Twitter agent with auto-posting
bun start twitter:debug     # Start Twitter agent with debug logging
bun start website           # Start website with API server
bun start dev               # Start full development environment
bun start dev:logging       # Start logging UI only
bun start telegram:ngrok    # Start Telegram with ngrok tunnel

Use Cases:

• logger-ui: Monitor all agent activity in real-time web interface

• twitter: Run BILL's Twitter bot with automatic posting/replies

• dev: Start everything needed for development

• website: Test the web interface with chat functionality

🧪 Testing Scripts

Twitter Integration Tests

bun start test:twitter      # Full Twitter integration test
bun start test:twitter:debug # Twitter test with detailed debug info
bun start test:twitter:simple # Basic Twitter functionality test
bun start test:twitter:trace # Twitter autopost with trace logging
bun start test:twitter:quick # Quick Twitter functionality check
bun start test:twitter:dry-run # Test without actually posting tweets
bun start test:twitter:refresh # Test token refresh functionality

Use Cases:

• test:twitter:dry-run: Safe testing without posting to Twitter

• test:twitter:debug: Detailed debugging when tweets aren't working

• test:twitter:quick: Fast verification that Twitter API is working

Core Functionality Tests

bun start test:logger       # Test logging system
bun start test:logger:debug # Logger test with debug output
bun start test:llm-fallback # Test LLM fallback mechanisms

📊 Context & Analysis Scripts

Context System Testing

bun start context:inspect   # Inspect current context data (DIAGNOSTIC)
bun start context:test      # Run context generation tests
bun start context:test-all  # Run all context-related tests
bun start context:simple    # Simple context functionality test
bun start context:usage     # Show context usage examples
bun start context:events    # Test event-driven posting

Key Script: context:inspect

• Purpose: Diagnostic tool to see what context data BILL has access to

• Shows: Timeline tweets, posted tweets, market analysis, event detection

• Use: Troubleshoot context issues, verify timeline monitoring is working

• Note: Read-only - doesn't collect new data, just shows existing

Timeline Monitoring

bun start timeline:trigger [username]  # Manually fetch tweets from specific account
bun start timeline:monitor [username]  # Same as above (alias)

Examples:

bun start timeline:trigger elonmusk    # Fetch Elon Musk's tweets
bun start timeline:trigger MarketWatch # Fetch MarketWatch tweets
bun start timeline:trigger zerohedge   # Fetch Zero Hedge tweets

Use Cases:

• Populate timeline database for testing

• Get fresh market data for context generation

• Test image analysis on accounts with charts/graphs

🔒 Security & Safety Scripts

bun start security:leakage  # Test for prompt leakage vulnerabilities
bun start security:fallback # Test security fallback mechanisms

Use Cases:

• Verify BILL doesn't leak system prompts or internal instructions

• Test safety mechanisms are working correctly

🛠️ Utility Scripts

Database & Cache Management

bun start clear:cache       # Clear Supabase timeline cache
bun start clear:db          # Clear database cache (alias)
bun start clear:runtime     # Clear runtime cache
bun start clear:auth        # Clear authentication tokens

Authentication

bun start auth:twitter      # Authenticate with Twitter API

---

🎯 Common Testing Workflows

1. First Time Setup

# Authenticate with Twitter
bun start auth:twitter

# Start logging to monitor everything
bun start logger-ui

# Test basic functionality
bun start test:twitter:dry-run

2. Context System Testing

# Check current context data
bun start context:inspect

# If no timeline data, populate it
bun start timeline:trigger elonmusk
bun start timeline:trigger MarketWatch
bun start timeline:trigger zerohedge

# Re-check context
bun start context:inspect

3. Twitter Agent Testing

# Safe testing (no actual tweets)
bun start test:twitter:dry-run

# Debug posting issues
bun start test:twitter:debug

# Full integration test
bun start test:twitter

4. Debugging Issues

# Clear specific caches as needed
bun start clear:cache    # Clear database cache
bun start clear:runtime  # Clear runtime cache

# Re-authenticate if needed
bun start auth:twitter

# Check logs
bun start logger-ui

# Test specific functionality
bun start test:twitter:simple

5. Context Pipeline Validation

# Populate fresh timeline data
bun start timeline:trigger MarketWatch
bun start timeline:trigger zerohedge

# Verify context analysis
bun start context:inspect

# Test context-driven posting
bun start context:events

---

🔍 Diagnostic Tools

Timeline Monitoring Status

• context:inspect: Shows what tweets are in database and how they're being analyzed

• timeline:trigger: Manually collects tweets to populate database

• Environment vars: TWITTER_IMMEDIATE_FETCH_CONTEXT=true enables immediate timeline fetching

Context Analysis

• Shows: Market analysis, trending topics, recent events

• Includes: AI analysis of images in tweets (charts, graphs)

• Sources: @elonmusk, @MarketWatch, @zerohedge, @federalreserve, etc.

Logging & Monitoring

• Real-time logs: Available at http://localhost:3003 when logger-ui is running

• Debug output: Many scripts support :debug variants for detailed logging

• Safety checks: Built-in prompt leakage and safety detection

---

⚡ Performance Tips

1. Use dry-run tests for development to avoid rate limits

2. Start logger-ui first to monitor all activity

3. Clear cache regularly when testing context changes

4. Use specific timeline:trigger commands rather than waiting for automatic monitoring

5. Check context:inspect before testing context-driven features

---

🚨 Important Notes

• All scripts use Bun: Don't use npm commands

• Environment variables: Located in bill-agent/.env (not accessible to Cursor)

• Character source of truth: Always reference agent/src/character/bill.ts

• Timeline monitoring: Automatic in main agent, manual with timeline:trigger

• Context inspection: Read-only diagnostic, doesn't collect new data

---

📚 Related Documentation

• Twitter Testing Guide

• Development Setup

• Agent Architecture

• Plugin Migration