polyfill-rs/docs/TESTING.md

Testing polyfill-rs

This document describes how to run tests for polyfill-rs, with a focus on integration tests that verify our client can actually communicate with the real Polymarket API.

Test Types

Unit Tests

• Location: Scattered throughout source files (src/*.rs)
• Purpose: Test individual functions and components in isolation
• Dependencies: None (pure functions)
• Speed: Fast

Integration Tests

• Location: tests/integration_tests.rs
• Purpose: Verify the client can communicate with the real Polymarket API
• Dependencies: Network connectivity, optional authentication credentials
• Speed: Slower (network calls)

Running Tests

Quick Start (Basic Tests)

# Run all unit tests
cargo test

# Run only integration tests
cargo test --test integration_tests

# Run with verbose output
cargo test --test integration_tests -- --nocapture

Full Integration Testing

1. Set up Environment Variables

Create a .env file or export variables:

# Required for authentication tests
export POLYMARKET_PRIVATE_KEY="your_private_key_here"

# Required for order management tests
export POLYMARKET_API_KEY="your_api_key"
export POLYMARKET_API_SECRET="your_api_secret"
export POLYMARKET_API_PASSPHRASE="your_passphrase"

# Optional (defaults provided)
export POLYMARKET_HOST="https://clob.polymarket.com"
export POLYMARKET_CHAIN_ID="137"

2. Run Integration Tests

# Using the test runner script
./scripts/run_integration_tests.sh

# Or directly with cargo
cargo test --test integration_tests -- --nocapture

Test Categories

Always Run (No Auth Required)

• API Connectivity: Basic connection to Polymarket API
• Market Data Endpoints: Order book, prices, spreads, etc.
• Error Handling: Invalid requests and error responses
• Rate Limiting: Multiple rapid requests
• API Compatibility: Verify our API matches polymarket-rs-client
• Performance: Response time measurements

Authentication Required

• Authentication: API key creation and validation
• Advanced Client Features: Full client configuration
• WebSocket Connectivity: Real-time data streaming

API Credentials Required

• Order Management: Order creation and management (read-only tests)

Test Results

Success Indicators

API connectivity test passed
Market data endpoints test passed
Error handling test passed
Rate limiting test passed
API compatibility test passed
Performance test passed
  Server time: 234ms
  Markets request: 1.2s
  Markets returned: 50

Skip Indicators

Skipping authentication test - no private key provided
Skipping order management test - missing auth credentials

Failure Indicators

API connectivity test failed: Network error: connection refused
Market data endpoints test failed: API error (404): Token not found

Performance Benchmarks

Our integration tests include performance measurements:

Operation	Expected Time	Actual Time
Server Time	< 5s	234ms
Markets Request	< 10s	1.2s
Order Book	< 5s	890ms
Price Quote	< 3s	156ms

Troubleshooting

Common Issues

Network Connectivity

# Test basic connectivity
curl -I https://clob.polymarket.com/

# Check DNS resolution
nslookup clob.polymarket.com

Authentication Issues

# Verify private key format
echo $POLYMARKET_PRIVATE_KEY | wc -c  # Should be 66 characters (0x + 64 hex)

# Test with minimal credentials
export POLYMARKET_PRIVATE_KEY="0x1234567890123456789012345678901234567890123456789012345678901234"
cargo test test_authentication

Rate Limiting

# If tests fail due to rate limiting, add delays
export POLYMARKET_TEST_DELAY=1000  # 1 second between requests

Debug Mode

Run tests with detailed logging:

# Enable debug logging
RUST_LOG=debug cargo test --test integration_tests -- --nocapture

# Enable trace logging for maximum detail
RUST_LOG=trace cargo test --test integration_tests -- --nocapture

Continuous Integration

GitHub Actions

Our CI runs integration tests automatically:

# .github/workflows/ci.yml
- name: Run Integration Tests
  env:
    POLYMARKET_HOST: ${{ secrets.POLYMARKET_HOST }}
    POLYMARKET_CHAIN_ID: ${{ secrets.POLYMARKET_CHAIN_ID }}
  run: cargo test --test integration_tests

Local CI

Run the same tests locally:

# Install cargo-nextest for faster test execution
cargo install cargo-nextest

# Run with nextest
cargo nextest run --test integration_tests

Test Coverage

Our integration tests cover:

• API Endpoints: All major REST endpoints
• Authentication: EIP-712 signing and API key management
• Error Handling: Network errors, API errors, validation errors
• Performance: Response time and throughput measurements
• WebSocket: Real-time data streaming (when available)
• Compatibility: API compatibility with polymarket-rs-client

Adding New Tests

Template for New Integration Test

#[tokio::test]
async fn test_new_feature() -> Result<()> {
    let config = TestConfig::from_env();
    
    // Skip if requirements not met
    if !config.has_auth() {
        TestReporter::skip("test_new_feature", "no private key");
        return Ok(());
    }
    
    // Test implementation
    let client = config.create_auth_client()?;
    let result = client.some_new_method().await?;
    
    // Assertions
    assert!(result.is_valid());
    
    TestReporter::success("test_new_feature");
    Ok(())
}

Best Practices

1. Use TestConfig: Always use the shared test configuration
2. Handle Missing Credentials: Skip tests gracefully when credentials aren't available
3. Measure Performance: Include timing measurements for performance-critical operations
4. Provide Context: Use descriptive test names and error messages
5. Clean Up: Don't leave test data in the system

Security Notes

• Never commit credentials: All test credentials are loaded from environment variables
• Use test accounts: If testing with real credentials, use dedicated test accounts
• Read-only tests: Order management tests only create orders, they don't execute them
• Rate limiting: Tests include delays to respect API rate limits