Testing Internal Operations

Testing Internal Operations

This guide explains how to test ChronoTrace with internal Laravel operations using the chronotrace:test-internal command.

Overview

The chronotrace:test-internal command addresses a common limitation where chronotrace:record primarily captures external HTTP events. This command allows you to test ChronoTrace's ability to capture internal Laravel operations like database queries, cache operations, and custom events.

Why Use chronotrace:test-internal vs chronotrace:record?

chronotrace:record - Real Application Debugging

• Purpose: Capture real HTTP requests in production/staging
• Data: Genuine user requests with actual business logic
• Use when: Debugging real bugs, analyzing user workflows, production monitoring
• Example: chronotrace:record /api/orders/123 captures a real order request

chronotrace:test-internal - Configuration Validation

• Purpose: Validate that ChronoTrace is properly configured and working
• Data: Artificial test operations to verify capture mechanisms
• Use when: Installation validation, testing after config changes, CI/CD
• Example: chronotrace:test-internal --with-db tests database event capture

Key Difference: record captures real application behavior, while test-internal validates that ChronoTrace itself is working correctly.

Usage

php artisan chronotrace:test-internal [options]

Available Options

• --with-db: Include database operation tests
• --with-cache: Include cache operation tests
• --with-events: Include custom event tests

Examples

Test all internal operations:

php artisan chronotrace:test-internal --with-db --with-cache --with-events

Test only database operations:

php artisan chronotrace:test-internal --with-db

Test cache and events:

php artisan chronotrace:test-internal --with-cache --with-events

What Gets Tested

Database Operations (--with-db)

• Creates a test table
• Performs INSERT, UPDATE, SELECT, and DELETE operations
• Tests both Eloquent ORM and Query Builder operations

Cache Operations (--with-cache)

• Sets cache values with different drivers
• Retrieves cached data
• Tests cache invalidation
• Note: May fail in minimal environments without cache table setup

Custom Events (--with-events)

• Fires custom Laravel events
• Tests event listener registration
• Validates event data capture

Understanding the Output

When you run the command, you'll see:

1. Trace ID Generation: A unique identifier for this test session
2. Operation Results: Success/failure status for each tested operation
3. ChronoTrace Activity: Debug information showing what ChronoTrace captured
4. Usage Instructions: How to replay or generate tests from the captured trace

Example output:

🧪 Testing ChronoTrace with internal Laravel operations...
📎 Starting trace: ct_neOhAT0HI3v0a8Rg_1754050787
🗄️  Testing database operations...
💾 Testing cache operations...
📡 Testing custom events...
✅ Internal operations test completed!
📊 Trace ID: ct_neOhAT0HI3v0a8Rg_1754050787
💡 Use: php artisan chronotrace:replay ct_neOhAT0HI3v0a8Rg_1754050787 to view the captured trace
🧪 Use: php artisan chronotrace:replay ct_neOhAT0HI3v0a8Rg_1754050787 --generate-test to create a test file

Detailed Testing Scenarios

Database Testing Details

The command tests various database operations:

// Table creation
Schema::create('chronotrace_test', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
});

// Insert operations
DB::table('chronotrace_test')->insert(['name' => 'Test Item']);

// Query operations  
DB::table('chronotrace_test')->where('name', 'Test Item')->first();

// Update operations
DB::table('chronotrace_test')->where('id', 1)->update(['name' => 'Updated Item']);

// Delete operations
DB::table('chronotrace_test')->delete();

Cache Testing Details

Tests different cache operations:

// Cache storage
Cache::put('chronotrace_test_key', 'test_value', 60);

// Cache retrieval
Cache::get('chronotrace_test_key');

// Cache invalidation
Cache::forget('chronotrace_test_key');

// Bulk operations
Cache::many(['key1' => 'value1', 'key2' => 'value2']);

Event Testing Details

Tests custom event handling:

// Fire custom events
event(new ChronoTraceTestEvent(['data' => 'test']));

// Test event listeners
Event::listen('chronotrace.test', function ($data) {
    // Event handling logic
});

Integration with CI/CD

Use in automated testing:

# GitHub Actions example
- name: Test ChronoTrace Configuration
  run: |
    php artisan chronotrace:test-internal --with-db --with-cache --with-events
    
# Check exit code for success/failure
- name: Validate ChronoTrace
  run: |
    if php artisan chronotrace:test-internal --with-db; then
      echo "✅ ChronoTrace is properly configured"
    else
      echo "❌ ChronoTrace configuration issues detected"
      exit 1
    fi

Next Steps

After running the test:

1. View the captured trace:

   php artisan chronotrace:replay [trace-id]

2. Generate a test file from the captured operations:

   php artisan chronotrace:replay [trace-id] --generate-test

3. Analyze the results to understand what ChronoTrace captured during internal operations

Troubleshooting

Common Issues

Cache operations failing: This is expected in minimal test environments. The database operations and events should still work correctly.

No operations captured: Check that ChronoTrace is enabled in your configuration and that the middleware is properly installed.

Permission errors: Ensure your application has proper database and file system permissions.

Debugging Tips

• Use --verbose flag for more detailed output
• Check your ChronoTrace configuration in config/chronotrace.php
• Verify that required listeners are registered in your EventServiceProvider

Expected vs Actual Behavior

✅ Expected Results:

• Database operations should always be captured
• Events should be captured if properly configured
• Cache operations may fail in minimal environments

❌ Troubleshooting Failed Tests:

• Check database connection and permissions
• Verify event listeners are registered
• Ensure ChronoTrace is enabled in configuration

Related Commands

• chronotrace:record - Record HTTP requests
• chronotrace:replay - Replay captured traces
• chronotrace:list - List available traces
• chronotrace:diagnose - Diagnose configuration issues

Next Steps

• Learn about choosing the right command
• Master basic usage workflows
• Explore troubleshooting guides