wheels test debug

Debug test execution with detailed diagnostics and troubleshooting tools.

Synopsis

wheels test debug [spec] [options]

Description

The wheels test debug command provides advanced debugging capabilities for your test suite. It helps identify why tests are failing, diagnose test environment issues, and provides detailed execution traces for troubleshooting complex test problems.

Arguments

Argument	Description	Default
spec	Specific test spec to debug	All tests

Options

Option	Description	Default
--bundles	Test bundles to debug	All bundles
--labels	Filter by test labels	None
--breakpoint	Set breakpoint at test	None
--step	Step through test execution	false
--trace	Show execution trace	false
--verbose	Verbose output level (1-3)	1
--slow	Highlight slow tests (ms)	1000
--dump-context	Dump test context	false
--inspect	Enable remote debugging	false
--port	Debug port for inspection	9229
--pause-on-failure	Pause when test fails	false
--replay	Replay failed tests	false
--help	Show help information

Examples

Debug specific test

wheels test debug UserModelTest

Debug with execution trace

wheels test debug --trace

Step through test execution

wheels test debug UserModelTest.testValidation --step

Debug with breakpoints

wheels test debug --breakpoint=UserModelTest.testLogin:15

Enable remote debugging

wheels test debug --inspect --port=9229

Debug slow tests

wheels test debug --slow=500 --verbose=2

Debug Output

Basic Debug Info

🔍 Test Debug Session Started
================================

Environment: testing
Debug Level: 1
Test Framework: TestBox 5.0.0
CFML Engine: Lucee 5.3.9.141

Running: UserModelTest.testValidation
Status: RUNNING

[DEBUG] Setting up test case...
[DEBUG] Creating test user instance
[DEBUG] Validating empty user
[DEBUG] Assertion: user.hasErrors() = true ✓
[DEBUG] Test completed in 45ms

Verbose Trace Output

With --trace --verbose=3:

🔍 Test Execution Trace
======================

▶ UserModelTest.setup()
  └─ [0.5ms] Creating test database transaction
  └─ [1.2ms] Loading test fixtures
  └─ [0.3ms] Initializing test context

▶ UserModelTest.testValidation()
  ├─ [0.1ms] var user = model("User").new()
  │   └─ [2.1ms] Model instantiation
  │   └─ [0.5ms] Property initialization
  ├─ [0.2ms] user.validate()
  │   └─ [5.3ms] Running validations
  │   ├─ [1.2ms] Checking required fields
  │   ├─ [2.1ms] Email format validation
  │   └─ [2.0ms] Custom validations
  ├─ [0.1ms] expect(user.hasErrors()).toBe(true)
  │   └─ [0.3ms] Assertion passed ✓
  └─ [0.1ms] Test completed

Total Time: 10.2ms
Memory Used: 2.3MB

Interactive Debugging

Step Mode

With --step:

▶ Entering step mode for UserModelTest.testLogin

[1] user = model("User").findOne(where="email='[e-mail]'")
    > (n)ext, (s)tep into, (c)ontinue, (v)ariables, (q)uit: v

Variables:
- arguments: {}
- local: { user: [undefined] }
- this: UserModelTest instance

    > n

[2] expect(user.authenticate("password123")).toBe(true)
    > v

Variables:
- arguments: {}
- local: { user: User instance {id: 1, email: "[e-mail]"} }

    > s

  [2.1] Entering: user.authenticate("password123")
       Parameters: { password: "password123" }

Breakpoints

Set breakpoints in code:

// In test file
function testComplexLogic() {
    var result = complexCalculation(data);
    
    debugBreak(); // Execution pauses here
    
    expect(result).toBe(expectedValue);
}

Or via command line:

wheels test debug --breakpoint=OrderTest.testCalculateTotal:25

Test Context Inspection

Dump Test Context

With --dump-context:

Test Context Dump
================

Test: UserModelTest.testPermissions
Phase: Execution

Application Scope:
- wheels.version: 2.5.0
- wheels.environment: testing
- Custom settings: { ... }

Request Scope:
- cgi.request_method: "GET"
- url: { testMethod: "testPermissions" }

Test Data:
- Fixtures loaded: users, roles, permissions
- Test user: { id: 999, email: "[e-mail]" }
- Database state: Transaction active

Component State:
- UserModelTest properties: { ... }
- Inherited properties: { ... }

Performance Analysis

Slow Test Detection

With --slow=500:

⚠️ Slow Tests Detected
=====================

1. OrderModelTest.testLargeOrderProcessing - 2,345ms 🐌
   - Database queries: 45 (1,234ms)
   - Model operations: 892ms
   - Assertions: 219ms

2. UserControllerTest.testBulkImport - 1,567ms 🐌
   - File I/O: 623ms
   - Validation: 512ms
   - Database inserts: 432ms

3. ReportTest.testGenerateYearlyReport - 987ms ⚠️
   - Data aggregation: 654ms
   - PDF generation: 333ms

Remote Debugging

Enable Inspector

wheels test debug --inspect

Connect with Chrome DevTools:

1. Open Chrome/Edge

2. Navigate to chrome://inspect

3. Click "Configure" and add localhost:9229

4. Click "inspect" on the target

Debug Protocol

wheels test debug --inspect-brk --port=9230

• --inspect: Enable debugging

• --inspect-brk: Break on first line

• Custom port for multiple sessions

Failure Analysis

Pause on Failure

With --pause-on-failure:

✗ Test Failed: UserModelTest.testUniqueEmail

Test paused at failure point.

Failure Details:
- Expected: true
- Actual: false
- Location: UserModelTest.cfc:45

Debug Options:
(i) Inspect variables
(s) Show stack trace
(d) Dump database state
(r) Retry test
(c) Continue
(q) Quit

> i

Local Variables:
- user1: User { email: "[e-mail]", id: 1 }
- user2: User { email: "[e-mail]", errors: ["Email already exists"] }

Stack Trace Analysis

Stack Trace:
-----------
1. TestBox.expectation.toBe() at TestBox/system/Expectation.cfc:123
2. UserModelTest.testUniqueEmail() at tests/models/UserModelTest.cfc:45
3. TestBox.runTest() at TestBox/system/BaseSpec.cfc:456
4. Model.validate() at wheels/Model.cfc:789
5. Model.validatesUniquenessOf() at wheels/Model.cfc:1234

Test Replay

Replay Failed Tests

wheels test debug --replay

Replays last failed tests with debug info:

Replaying 3 failed tests from last run...

1/3 UserModelTest.testValidation
    - Original failure: Assertion failed at line 23
    - Replay status: PASSED ✓
    - Possible flaky test

2/3 OrderControllerTest.testCheckout
    - Original failure: Database connection timeout
    - Replay status: FAILED ✗
    - Consistent failure

Configuration

Debug Configuration

.wheels-test-debug.json:

{
  "debug": {
    "defaultLevel": 1,
    "slowThreshold": 1000,
    "breakpoints": [
      "UserModelTest.testComplexScenario:45",
      "OrderTest.testEdgeCase:78"
    ],
    "trace": {
      "includeFramework": false,
      "maxDepth": 10
    },
    "output": {
      "colors": true,
      "timestamps": true,
      "saveToFile": "./debug.log"
    }
  }
}

Debugging Strategies

1. Isolate Failing Test

# Run only the failing test
wheels test debug UserModelTest.testValidation --trace

2. Check Test Environment

# Dump environment and context
wheels test debug --dump-context > test-context.txt

3. Step Through Execution

# Interactive debugging
wheels test debug FailingTest --step --pause-on-failure

4. Compare Working vs Failing

# Debug working test
wheels test debug WorkingTest --trace > working.log

# Debug failing test
wheels test debug FailingTest --trace > failing.log

# Compare outputs
diff working.log failing.log

Common Issues

Test Pollution

Debug test isolation:

wheels test debug --trace --verbose=3 | grep -E "(setup|teardown|transaction)"

Race Conditions

Debug timing issues:

wheels test debug --slow=100 --trace

Database State

wheels test debug --dump-context | grep -A 20 "Database state"

Best Practices

1. Start Simple: Use basic debug before advanced options

2. Isolate Issues: Debug one test at a time

3. Use Breakpoints: Strategic breakpoints save time

4. Check Environment: Ensure test environment is correct

5. Save Debug Logs: Keep logs for complex issues

Notes

• Debug mode affects test performance

• Some features require specific CFML engine support

• Remote debugging requires network access

• Verbose output can be overwhelming - filter as needed

See Also

• wheels test - Run tests normally
• wheels test run - Run specific tests
• wheels test coverage - Coverage analysis
• Debugging Guide