pumpfun-bonkfun-bot/.cursor/rules/tests.mdc

---
description: Performance testing and listener comparison scripts for token detection systems. Apply when benchmarking listener performance or validating detection accuracy.
globs: tests/*.py
alwaysApply: true
---

# Listener Performance Testing Guide

## Overview

The test scripts provide performance comparison and validation tools for different listener implementations. These are standalone scripts designed to measure which listener is fastest at discovering new tokens, helping optimize the bot's detection capabilities.

## Individual Listener Tests

Each listener has a dedicated test script for standalone performance analysis:

### Geyser Listener Test

@tests/test_geyser_listener.py tests the fastest detection method:
- Direct gRPC connection to Geyser endpoint
- Real-time token creation monitoring
- Performance measurement and token logging

```bash
# Run Geyser listener test for 30 seconds
uv run tests/test_geyser_listener.py
```

### Logs Listener Test

@tests/test_logs_listener.py validates log-based monitoring:
- WebSocket subscription to program logs
- Pattern matching for token creation events
- Detection accuracy verification

```bash
# Run logs listener test
uv run tests/test_logs_listener.py
```

### Block Listener Test

@tests/test_block_listener.py tests block-based scanning:
- Full block processing for token discovery
- Transaction analysis and extraction
- Comprehensive but potentially slower detection

```bash
# Run block listener test
uv run tests/test_block_listener.py
```

## Comparative Performance Analysis

### Listener Comparison Tool

@tests/compare_listeners.py runs all listeners simultaneously:
- Side-by-side performance measurement
- Detection speed comparison with timing data
- Accuracy analysis (tokens detected by each method)
- Statistical reporting on detection overlap

```bash
# Compare all listeners for 60 seconds
uv run tests/compare_listeners.py 60

# Default 60-second comparison
uv run tests/compare_listeners.py
```

### Performance Metrics

The comparison tool provides:

| Metric | Description |
|--------|-------------|
| Detection Speed | Time to detect each token (microsecond precision) |
| Detection Count | Total tokens found by each listener |
| Overlap Analysis | Tokens detected by multiple listeners |
| Unique Detections | Tokens found only by specific listeners |

## Test Output Analysis

### Individual Test Results

Each listener test displays:
```
==================================================
NEW TOKEN: TokenName
Symbol: SYMBOL
Mint: TokenMintAddress
URI: MetadataURI
Creator: CreatorAddress
==================================================
```

### Comparison Results

The comparison tool generates:
```
Geyser detected: 15 tokens
Logs detected: 12 tokens
Block detected: 18 tokens

Token | Geyser | Logs | Block | Fastest
------|--------|------|-------|--------
ABC123... | 1.234567 | N/A | 2.345678 | Geyser
DEF456... | 0.987654 | 1.123456 | 1.567890 | Geyser
```

## Environment Configuration

Tests require these environment variables:
```bash
export SOLANA_NODE_RPC_ENDPOINT="https://api.mainnet-beta.solana.com"
export SOLANA_NODE_WSS_ENDPOINT="wss://api.mainnet-beta.solana.com"
export GEYSER_ENDPOINT="wss://your-geyser-endpoint"
export GEYSER_API_TOKEN="your-api-token"
```

## Common Usage Patterns

### Quick Performance Check
```bash
# 30-second comparison of all listeners
uv run tests/compare_listeners.py 30
```

### Extended Performance Analysis
```bash
# 10-minute deep analysis
uv run tests/compare_listeners.py 600
```

### Individual Listener Validation
```bash
# Test specific listener implementation
uv run tests/test_geyser_listener.py
```

## Use Cases

1. **Performance Optimization**: Determine fastest listener for production
2. **Reliability Testing**: Verify consistent token detection
3. **Configuration Tuning**: Optimize listener parameters
4. **Debugging**: Isolate listener-specific issues

## Related Files

- @tests/test_geyser_listener.py: Geyser performance testing
- @tests/test_logs_listener.py: Logs listener validation
- @tests/test_block_listener.py: Block listener analysis
- @tests/compare_listeners.py: Multi-listener performance comparison