# Debugging Integration Tests
This guide explains how to debug integration tests for low-level handlers, especially focusing on session management and lock operations.
## Environment Variables for Debugging
### DEBUG_TESTS=true
Enables detailed logging in test files. Shows:
- Test step execution (Validate, Create, Lock, Update, Unlock, Activate)
- Session state changes between operations
- Lock handle extraction and usage
- Session ID tracking
**Usage:**
```bash
DEBUG_TESTS=true npm test -- integration/domain
```
**Example output:**
```
[DEBUG] LOCK: Starting lock for ZADT_BLD_DOM02
[DEBUG] LOCK data: {
"session_id": "abc123...",
"has_session_state": true,
"session_state_cookies": "sap-usercontext=sap-client=100;..."
}
[DEBUG] LOCK: Lock completed, extracted session
[DEBUG] LOCK data: {
"lock_handle": "xyz789...",
"lock_session_id": "abc123...",
"session_from_lock": {...}
}
```
### DEBUG_HANDLERS=true
Enables detailed logging in handler functions. Shows:
- Handler entry/exit points
- Session state restoration
- Lock handle usage
- Property validation
- Error details
**Usage:**
```bash
DEBUG_HANDLERS=true npm test -- integration/domain
```
**Example output:**
```json
{
"level": "INFO",
"timestamp": "2025-01-25T10:30:00.000Z",
"handler": "LockDomain",
"step": "start",
"message": "Starting lock for ZADT_BLD_DOM02",
"session_id": "abc123...",
"has_session_state": true,
"session_state_cookies": "sap-usercontext=..."
}
```
### DEBUG_ADT_LIBS=true
Enables logging from `@mcp-abap-adt/adt-clients` library.
### DEBUG_CONNECTORS=true
Enables logging from `@mcp-abap-adt/connection` library. Shows:
- HTTP requests and responses
- CSRF token management
- Cookie handling
- Session state management in connection layer
**Usage:**
```bash
DEBUG_CONNECTORS=true npm test -- integration/domain
```
### DEBUG_CONNECTION_MANAGER=true
Enables logging for connection manager (`getManagedConnection`). Shows:
- Connection cache operations (creation, reuse, cleanup)
- Connection signature matching
- Refresh token configuration
- Session-specific connection management
**Usage:**
```bash
DEBUG_CONNECTION_MANAGER=true npm test -- integration/domain
```
**Example output:**
```json
{
"level": "DEBUG",
"timestamp": "2025-11-27T06:59:04.734Z",
"message": "[DEBUG] getManagedConnection - Reusing cached connection (signature matches)"
}
{
"level": "DEBUG",
"timestamp": "2025-11-27T06:59:04.735Z",
"message": "[DEBUG] getManagedConnection - Creating new connection (cached: false, signature changed: true)"
}
{
"level": "DEBUG",
"timestamp": "2025-11-27T06:59:04.736Z",
"message": "[DEBUG] getManagedConnection - Refresh token config:",
"hasRefreshToken": true,
"hasUaaUrl": true,
"canRefresh": true
}
```
**Note:** This is separate from `DEBUG_CONNECTORS=true`. Use `DEBUG_CONNECTION_MANAGER=true` to debug connection caching and management, while `DEBUG_CONNECTORS=true` shows HTTP-level connection logs.
## Combined Debugging
Enable all debug flags for maximum visibility:
```bash
DEBUG_TESTS=true DEBUG_HANDLERS=true DEBUG_ADT_LIBS=true DEBUG_CONNECTORS=true DEBUG_CONNECTION_MANAGER=true npm test -- integration/domain
```
**Common combinations:**
```bash
# Connection-level debugging (HTTP, sessions, connection management)
DEBUG_CONNECTORS=true DEBUG_CONNECTION_MANAGER=true npm test -- integration/domain
# Test execution debugging
DEBUG_TESTS=true DEBUG_HANDLERS=true npm test -- integration/domain
# Full visibility (everything)
DEBUG_TESTS=true DEBUG_HANDLERS=true DEBUG_ADT_LIBS=true DEBUG_CONNECTORS=true DEBUG_CONNECTION_MANAGER=true npm test -- integration/domain
```
## Critical Session Management Points
### 1. Lock Operation
The `LockDomain` handler returns:
- `lock_handle`: Required for Update and Unlock
- `session_id`: Must be passed to Update and Unlock
- `session_state`: Contains cookies, CSRF token, and cookie store
**What to check:**
- ✅ Lock returns a valid `lock_handle`
- ✅ Lock returns `session_id` and `session_state`
- ✅ Session state contains cookies and CSRF token
### 2. Update Operation
The `UpdateDomain` handler **MUST** receive:
- `lock_handle` from Lock operation
- `session_id` from Lock operation
- `session_state` from Lock operation
**What to check:**
- ✅ Update receives `session_id` from Lock (not from Create or Validate)
- ✅ Update receives `session_state` from Lock
- ✅ Session state is restored before calling `client.updateDomain()`
- ✅ Properties include `packageName` or `package_name`
### 3. Unlock Operation
The `UnlockDomain` handler **MUST** receive:
- `lock_handle` from Lock operation
- `session_id` from Lock operation
- `session_state` from Lock operation
**What to check:**
- ✅ Unlock receives `session_id` from Lock (same as Update)
- ✅ Unlock receives `session_state` from Lock (same as Update)
- ✅ Session state is restored before calling `client.unlockDomain()`
## Common Issues
### Issue: "Package name is required" during Update
**Cause:** `DomainBuilder.update()` requires `packageName` in the config, but it's not being passed correctly.
**Solution:**
```typescript
const properties = {
description: 'Updated description',
datatype: 'CHAR',
length: 10,
packageName: packageName, // ← Required (camelCase)
// OR
package_name: packageName // ← Also accepted
};
```
### Issue: "Invalid lock handle or session" during Unlock
**Cause:** Session state from Lock was not passed to Unlock, or session expired.
**Solution:**
1. Extract session from Lock response:
```typescript
const lockSession = extractLockSession(lockData);
```
2. Pass to Unlock:
```typescript
await handleUnlockDomain({
domain_name: domainName,
lock_handle: lockHandle,
session_id: lockSession.session_id, // ← From Lock
session_state: lockSession.session_state // ← From Lock
});
```
### Issue: Session state not persisting between operations
**Cause:** Session state is not being extracted and updated from handler responses.
**Solution:**
```typescript
// After each operation, update session:
session = updateSessionFromResponse(session, responseData);
```
## Debugging Workflow
1. **Enable debug flags:**
```bash
DEBUG_TESTS=true DEBUG_HANDLERS=true npm test -- integration/domain
```
2. **Check Lock operation:**
- Verify `lock_handle` is returned
- Verify `session_id` and `session_state` are returned
- Check session state contains cookies and CSRF token
3. **Check Update operation:**
- Verify it receives `session_id` from Lock
- Verify it receives `session_state` from Lock
- Verify session state is restored before update
- Check properties include `packageName`
4. **Check Unlock operation:**
- Verify it receives same `session_id` as Update
- Verify it receives same `session_state` as Update
- Verify session state is restored before unlock
## Example Debug Output
With `DEBUG_TESTS=true` and `DEBUG_HANDLERS=true`:
```
[DEBUG] LOCK: Starting lock for ZADT_BLD_DOM02
{
"level": "INFO",
"handler": "LockDomain",
"step": "restore_session",
"message": "Restoring session state",
"session_id": "abc123",
"cookies_length": 137
}
{
"level": "INFO",
"handler": "LockDomain",
"step": "success",
"message": "Lock completed for ZADT_BLD_DOM02",
"lock_handle": "xyz789",
"updated_session_state": {
"has_cookies": true,
"cookies_length": 137
}
}
[DEBUG] UPDATE: Starting update for ZADT_BLD_DOM02
{
"level": "INFO",
"handler": "UpdateDomain",
"step": "restore_session",
"message": "Restoring session state from Lock",
"session_id": "abc123",
"cookies_length": 137
}
```
## Tips
1. **Always use session from Lock** for Update and Unlock operations
2. **Check session state** contains cookies and CSRF token before each operation
3. **Verify lock handle** is the same across Lock, Update, and Unlock
4. **Check package name** is included in Update properties
5. **Use DEBUG_HANDLERS** to see exactly what handlers receive and return
---
# Debugging Server HTTP Requests
This section explains how to debug HTTP requests and MCP calls when running the server.
## Environment Variables for Server Debugging
### DEBUG_HTTP_REQUESTS=true
Enables logging of all incoming HTTP requests and MCP JSON-RPC calls. Shows:
- HTTP method, URL, headers (sensitive data is redacted)
- MCP JSON-RPC method, params (sensitive params are redacted)
- Session information
- Request/response flow
**Usage:**
```bash
DEBUG_HTTP_REQUESTS=true mcp-abap-adt --auth-broker
```
**Example output:**
```json
{
"level": "INFO",
"timestamp": "2025-01-25T10:30:00.000Z",
"type": "HTTP_REQUEST",
"message": "HTTP Request received",
"method": "POST",
"url": "/",
"headers": {
"content-type": "application/json",
"x-sap-destination": "TRIAL",
"authorization": "[REDACTED]"
},
"remoteAddress": "::1",
"remotePort": 54321
}
{
"level": "INFO",
"timestamp": "2025-01-25T10:30:01.000Z",
"type": "MCP_REQUEST",
"message": "MCP Request",
"method": "JSON-RPC",
"jsonrpc": "2.0",
"id": 1,
"params": {
"name": "tools/call",
"arguments": {
"tool": "get_class",
"class_name": "ZCL_TEST"
}
},
"sessionId": "abc123..."
}
```
### DEBUG_CONNECTORS=true
Enables all connection-level debugging, including:
- HTTP requests (same as `DEBUG_HTTP_REQUESTS=true`)
- CSRF token management
- Cookie handling
- Session state management
- Connection details
**Usage:**
```bash
DEBUG_CONNECTORS=true mcp-abap-adt --auth-broker
```
**Note:** `DEBUG_CONNECTORS=true` automatically enables `DEBUG_HTTP_REQUESTS=true`.
### DEBUG_AUTH_LOG=true or DEBUG_AUTH_BROKER=true
Enables debug logging for `auth-broker` package. Shows:
- Service key loading
- Token validation and refresh
- Browser authentication flow
- Session management
**Usage:**
```bash
# Using DEBUG_AUTH_LOG (original)
DEBUG_AUTH_LOG=true mcp-abap-adt --auth-broker
# Using DEBUG_AUTH_BROKER (alias, recommended)
DEBUG_AUTH_BROKER=true mcp-abap-adt --auth-broker
```
**Note:** `DEBUG_AUTH_BROKER=true` automatically sets `DEBUG_AUTH_LOG=true` for the auth-broker package.
### DEBUG_HANDLERS=true
Enables detailed logging in MCP handler functions. Shows:
- Handler entry/exit points
- Session state restoration
- Lock handle usage
- Property validation
- Error details
**Usage:**
```bash
DEBUG_HANDLERS=true mcp-abap-adt --auth-broker
```
### DEBUG_CONNECTION_MANAGER=true
Enables logging for connection manager (`getManagedConnection`). Shows:
- Connection cache operations (creation, reuse, cleanup)
- Connection signature matching
- Refresh token configuration
- Session-specific connection management
**Usage:**
```bash
DEBUG_CONNECTION_MANAGER=true mcp-abap-adt --auth-broker
```
## Combined Debugging
Enable all debug flags for maximum visibility:
```bash
DEBUG_HTTP_REQUESTS=true DEBUG_AUTH_LOG=true DEBUG_HANDLERS=true DEBUG_CONNECTORS=true DEBUG_CONNECTION_MANAGER=true mcp-abap-adt --auth-broker
```
**Common combinations:**
```bash
# HTTP requests and MCP calls only
DEBUG_HTTP_REQUESTS=true mcp-abap-adt --auth-broker
# Connection-level debugging (HTTP, sessions, connection management)
DEBUG_CONNECTORS=true DEBUG_CONNECTION_MANAGER=true mcp-abap-adt --auth-broker
# Authentication debugging
DEBUG_AUTH_BROKER=true mcp-abap-adt --auth-broker
# or
DEBUG_AUTH_LOG=true mcp-abap-adt --auth-broker
# Handler debugging
DEBUG_HANDLERS=true mcp-abap-adt --auth-broker
# Full visibility (everything)
DEBUG_HTTP_REQUESTS=true DEBUG_AUTH_BROKER=true DEBUG_HANDLERS=true DEBUG_CONNECTORS=true DEBUG_CONNECTION_MANAGER=true mcp-abap-adt --auth-broker
```
## Security Note
Sensitive data is automatically redacted in logs:
- `authorization` header → `[REDACTED]`
- `x-sap-jwt-token` → `[REDACTED]`
- `x-sap-refresh-token` → `[REDACTED]`
- `x-sap-password` → `[REDACTED]`
- `x-sap-uaa-client-secret` → `[REDACTED]`
- Any param containing `password`, `token`, or `secret` → `[REDACTED]`
## Output Format
All debug logs are written to `stderr` in JSON format to avoid interfering with MCP JSON-RPC protocol. This allows you to:
1. **View logs in terminal:**
```bash
DEBUG_HTTP_REQUESTS=true mcp-abap-adt --auth-broker 2>&1 | jq
```
2. **Save logs to file:**
```bash
DEBUG_HTTP_REQUESTS=true mcp-abap-adt --auth-broker 2>debug.log
```
3. **Filter specific log types:**
```bash
DEBUG_HTTP_REQUESTS=true mcp-abap-adt --auth-broker 2>&1 | grep "HTTP_REQUEST"
```
