Test Environment Debugger

Test failure debugging engine - captures full CI execution context (environment, network, resources), classifies failure root causes, and generates structured debug bundles with actionable fix suggestions.

Features

• Environment Capture - Records OS, Node.js version, memory, CPU, timezone, and locale information
• Network Diagnostics - Tests DNS resolution, port availability, and detects proxy configurations
• Resource Monitoring - Tracks memory usage, CPU load averages, disk space, and system uptime
• Failure Classification - Automatically categorizes failures into 6 root cause categories
• Actionable Suggestions - Generates prioritized fix suggestions based on failure classification
• Structured Debug Bundles - Produces JSON bundles combining all captured context and analysis
• REST API - Express server for programmatic bundle generation via HTTP
• CLI Interface - Command-line tool for quick capture and server management

How It Works

+---------------+     +------------------+     +----------------+     +--------------+
|  Test Fails   | --> | Context Capture  | --> | Classification | --> | Debug Bundle |
|               |     |                  |     |                |     |              |
| - Error msg   |     | - Environment    |     | - Pattern      |     | - Full ctx   |
| - Test name   |     | - Network        |     |   matching     |     | - Root cause |
|               |     | - Resources      |     | - State        |     | - Suggestions|
|               |     |                  |     |   analysis     |     |              |
+---------------+     +------------------+     +----------------+     +--------------+

Failure Categories

Category	Signal	Example
network	ECONNREFUSED, DNS failures, socket errors	Database connection refused in CI
resource-exhaustion	OOM, heap errors, ENOMEM	Jest worker runs out of memory
timing	Timeout, async deadline exceeded	API call takes longer in CI
environment-mismatch	ENOENT, EACCES, permission denied	Config file missing in CI container
dependency-version	Version mismatch, peer dependency conflicts	Package works locally but fails in CI
unknown	No recognizable patterns	Unclassified failures for manual review

Project Structure

test-environment-debugger/
+-- src/
|   +-- api/
|   |   +-- server.ts          # Express REST API
|   +-- analyzer/
|   |   +-- classifier.ts      # Failure classification engine
|   |   +-- suggestions.ts     # Fix suggestion generator
|   |   +-- index.ts
|   +-- bundle/
|   |   +-- builder.ts         # Debug bundle orchestrator
|   |   +-- index.ts
|   +-- capture/
|   |   +-- environment.ts     # OS/Node/env capture
|   |   +-- network.ts         # Network state capture
|   |   +-- resources.ts       # System resources capture
|   |   +-- index.ts
|   +-- config/
|   |   +-- defaults.ts        # Default configuration
|   |   +-- loader.ts          # Config loader
|   |   +-- logger.ts          # Winston logger setup
|   |   +-- index.ts
|   +-- index.ts               # CLI entry point
+-- tests/
|   +-- unit/
|       +-- analyzer/
|       |   +-- classifier.test.ts
|       |   +-- suggestions.test.ts
|       +-- capture/
|           +-- environment.test.ts
|           +-- resources.test.ts
+-- .github/
|   +-- workflows/
|       +-- ci.yml             # GitHub Actions CI pipeline
+-- Dockerfile                 # Multi-stage Docker build
+-- docker-compose.yml         # Container orchestration
+-- package.json
+-- tsconfig.json
+-- jest.config.ts
+-- README.md

Getting Started

Prerequisites

• Node.js 20 or higher
• npm 9 or higher
• Docker (optional, for containerized deployment)

Installation

git clone https://github.com/Djones-qa/test-environment-debugger.git
cd test-environment-debugger
npm install

Build

npm run build

Run

# Start the API server
npm run serve

# Or use development mode
npm run dev

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint

CLI Usage

# Start the debug API server
npx ts-node src/index.ts serve --port 3008

# Capture a debug bundle for a failed test
npx ts-node src/index.ts capture --test "user.auth.test" --error "ECONNREFUSED 127.0.0.1:5432"

# Capture without network diagnostics (faster)
npx ts-node src/index.ts capture --test "api.test" --error "timeout exceeded" --no-network

Debug Bundle Output

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "testName": "user.auth.test",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "environment": {
    "os": { "platform": "linux", "release": "5.4.0", "arch": "x64", "type": "Linux" },
    "node": { "version": "v20.10.0", "execPath": "/usr/bin/node" },
    "envVarNames": ["PATH", "HOME", "CI", "NODE_ENV"],
    "memory": { "total": 8589934592, "free": 2147483648, "usedPercent": 75.0 },
    "cpuCount": 2,
    "timezone": "UTC",
    "locale": "en-US",
    "cwd": "/home/runner/work/project"
  },
  "network": {
    "hostname": "runner-abc123",
    "dnsResolution": { "able": true, "resolvedAddress": "142.250.80.46" },
    "portAvailability": [
      { "port": 5432, "available": false }
    ],
    "proxySettings": { "httpProxy": null, "httpsProxy": null, "noProxy": null }
  },
  "resources": {
    "memory": { "total": 8589934592, "free": 2147483648, "usedPercent": 75.0 },
    "cpu": { "count": 2, "loadAverage": [3.5, 2.1, 1.8], "model": "Intel Xeon" },
    "disk": { "total": 536870912000, "free": 214748364800, "usedPercent": 60.0 },
    "uptime": 3600,
    "processCount": 45
  },
  "classification": {
    "category": "network",
    "confidence": 0.67,
    "reasoning": "Error message matches network patterns",
    "indicators": ["network: matched pattern ECONNREFUSED"]
  },
  "suggestions": [
    {
      "title": "Check service dependencies",
      "description": "Verify that all required services are running and accessible",
      "priority": "high",
      "action": "docker-compose up -d && sleep 5 && npm test"
    }
  ],
  "metadata": {}
}

Suggestions Engine

The suggestions engine maps failure categories to actionable fixes:

+-------------------------+     +-----------------------------------------+
| Category: network       | --> | - Check service dependencies (high)     |
|                         |     | - Verify DNS resolution (medium)        |
|                         |     | - Check firewall rules (medium)         |
+-------------------------+     +-----------------------------------------+
| Category: resource-     | --> | - Increase memory limits (high)         |
| exhaustion              |     | - Reduce parallel execution (medium)    |
|                         |     | - Check for memory leaks (medium)       |
+-------------------------+     +-----------------------------------------+
| Category: timing        | --> | - Increase test timeout (high)          |
|                         |     | - Add retry logic (medium)              |
|                         |     | - Use waitFor utilities (medium)        |
+-------------------------+     +-----------------------------------------+

Configuration

Variable	Description	Default
PORT	API server port	3008
LOG_LEVEL	Logging level (debug, info, warn, error)	info
BUNDLE_OUTPUT_DIR	Directory for saved bundles	./debug-bundles
MAX_BUNDLE_AGE	Max bundle retention (ms)	604800000 (7 days)
CAPTURE_TIMEOUT	Timeout for capture operations (ms)	5000

API Endpoints

Method	Endpoint	Description
GET	/api/health	Health check - returns service status and uptime
POST	/api/bundle	Generate debug bundle - accepts testName and errorMessage

Example API Request

curl -X POST http://localhost:3008/api/bundle \
  -H "Content-Type: application/json" \
  -d '{"testName": "auth.test", "errorMessage": "ECONNREFUSED"}'

CI/CD Pipeline

The GitHub Actions workflow runs three sequential stages:

1. Lint - ESLint + TypeScript type checking
2. Test - Jest with coverage reporting
3. Docker - Build image and run container health check

Triggers on push/PR to master, main, and develop branches.

Author

Darrius Jones

• GitHub: @Djones-qa
• LinkedIn: darrius-jones-28226b350

License

MIT - 2026 Darrius Jones

See LICENSE for full text.