Incidents

Connector Testing

Connector Testing Guide

Fast & Decisive connector validation for production readiness

Quick Start 

# 1. Set up credentials
cp config/connector-test.example.env .env
# Edit .env with your actual credentials

# 2. Run all connector tests
make connectors-verify

# 3. Check results
ls -la connector-test-report-*.json

Overview

The connector testing framework provides comprehensive validation of external service integrations with:

  • ✅ Live API Testing - Real authentication and CRUD operations
  • 🎥 Record/Replay - Cassette-based testing for CI/CD
  • 📊 Detailed Reports - JSON reports with performance metrics
  • 🔐 Credential Safety - Automatic sanitization of sensitive data
  • ⚡ Fast Execution - Parallel testing with timeout controls

Supported Connectors

Connector Status Operations Auth Method
ServiceNow ✅ Production Ready Create, Read, Update, Sync, Webhooks Basic Auth
Jira Service Management ✅ Production Ready Create, Read, Update, Sync, Webhooks API Token
PagerDuty 🚧 In Development Events, Incidents, Services API Key

Test Modes

1. Live Testing (Default)

Tests against real external services with actual credentials.

# Test all configured connectors
make connectors-verify

# Test specific connector
make test-servicenow
make test-jira

2. Record Mode

Records API interactions to cassettes for later replay.

# Record new interactions
CASSETTE_MODE=record make test-servicenow

# Recordings saved to tests/cassettes/
ls tests/cassettes/servicenow/

3. Replay Mode (CI/CD)

Uses recorded cassettes for fast, deterministic testing.

# Run tests in replay mode (no real API calls)
CASSETTE_MODE=replay make test-all

# Perfect for CI/CD pipelines

Setting Up Test Credentials

ServiceNow Developer Instance (Free)

  1. Sign up for ServiceNow Developer Instance

    • Go to https://developer.servicenow.com/
    • Click “Start Building” → “Request Instance”
    • You’ll get a unique instance like dev12345.service-now.com

  2. Configure Test User

    • Log into your instance as admin
    • Navigate to System Security → Users and Groups → Users
    • Create a test user with incident_manager or itil role
    • Ensure read/write access to the incident table

  3. Set Environment Variables

    export SERVICENOW_URL=https://dev12345.service-now.com
export SERVICENOW_USERNAME=test_user
export SERVICENOW_PASSWORD=test_password

Jira Service Management (Free Tier)

  1. Create Atlassian Account

    • Go to https://www.atlassian.com/
    • Sign up for Atlassian Cloud account
    • Create a site: yourname.atlassian.net
    • Enable Jira Service Management (free for up to 3 agents)

  2. Configure API Access

    • Create a “Service Management” project with key “ITSM”
    • Go to Settings → System → API tokens
    • Create API token for your account
    • Verify project has “Incident” issue type

  3. Set Environment Variables

    export JIRA_URL=https://yourname.atlassian.net
export JIRA_USERNAME=your-email@company.com
export JIRA_API_TOKEN=your-api-token
export JIRA_PROJECT_KEY=ITSM

Environment Configuration 

# Create .env file from template
cp config/connector-test.example.env .env

# Edit .env with your actual credentials
# The testing framework will automatically load these

What The Tests Validate

Connection Tests

  • Validate authentication credentials
  • Confirm API accessibility and permissions
  • Test rate limiting and error handling

CRUD Operations

  • Create test incidents in external systems
  • Read back created incidents to verify data
  • Update incident titles and descriptions
  • Validate field mappings (severity, status, priority)

Integration Validation

  • Test webhook payload parsing
  • Verify error handling (401, 404, 429, 500)
  • Benchmark performance (<1s connections, <2s operations)
  • Generate detailed JSON reports

Test Execution Results

Expected Output 

🧪 Testing ServiceNow Connector
════════════════════════════════════════
  📋 Connection           ... ✅ PASSED (245ms)
  📋 Health Check         ... ✅ PASSED (123ms)
  📋 Create Incident      ... ✅ PASSED (567ms)
  📋 Get Incident         ... ✅ PASSED (234ms)
  📋 Update Incident      ... ✅ PASSED (445ms)
  📋 Field Mappings       ... ✅ PASSED (12ms)
  📋 Webhook Validation   ... ✅ PASSED (34ms)

📊 Test Results Summary
=======================
ServiceNow: 7/7 passed
Jira: 6/6 passed
Overall: 13/13 tests passed (100.0%)

📄 Detailed report saved to: connector-test-report-20240824-103045.json

Report Format

Test reports include:

  • Connection metrics - Response times, authentication status
  • API coverage - Endpoints tested, success rates
  • Performance data - P50, P95, P99 response times
  • Error analysis - Failed requests with detailed diagnostics
  • Field mapping validation - Data transformation accuracy

Troubleshooting

Authentication Failures 

❌ Connection ... FAILED (1.2s)
   Error: authentication failed with status 401

Solutions:

  • Verify credentials in .env file
  • Check user permissions in ServiceNow/Jira
  • Confirm API endpoints are accessible
  • Validate API token hasn’t expired

Network Issues 

❌ Connection ... FAILED (30.0s)
   Error: connection timeout

Solutions:

  • Check internet connectivity
  • Verify ServiceNow/Jira instance URLs
  • Confirm firewall/proxy settings
  • Test direct browser access to APIs

Rate Limiting 

⚠️  Create Incident ... PASSED (2.1s)
   Warning: Rate limited, automatically retried

Expected behavior - Tests include automatic retry logic with exponential backoff.

Advanced Configuration

Custom Test Scenarios

Create custom test files:

# Create custom test scenario
cat > tests/scenarios/custom.json << EOF
{
  "name": "Custom Incident Test",
  "steps": [
    {"action": "create", "severity": "SEV-1", "title": "Custom test incident"},
    {"action": "update", "field": "description", "value": "Updated description"},
    {"action": "close", "resolution": "Resolved"}
  ]
}
EOF

# Run custom scenario
make test-scenario SCENARIO=custom

Performance Benchmarking 

# Run performance benchmarks
make benchmark-connectors

# Results include:
# - Connection establishment times
# - API operation latencies
# - Throughput measurements
# - Resource utilization

Cassette Management 

# List existing cassettes
ls -la tests/cassettes/

# Clean old cassettes
make clean-cassettes

# Record specific test scenarios
CASSETTE_MODE=record TEST_FILTER=ServiceNow make test-connectors

CI/CD Integration

GitHub Actions Example 

name: Connector Tests
on: [push, pull_request]

jobs:
  test-connectors:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run connector tests (replay mode)
        run: |
          CASSETTE_MODE=replay make test-all
        env:
          # No real credentials needed in replay mode
          SERVICENOW_URL: https://mock.service-now.com
          JIRA_URL: https://mock.atlassian.net

Production Gates 

# Add to deployment pipeline
make connectors-verify || exit 1

# Requires 100% test pass rate for deployment

Security Considerations

Credential Protection

  • Never commit real credentials to version control
  • Use environment variables or secure credential stores
  • Rotate test credentials regularly
  • Monitor test account activity in external systems

Data Sanitization

Test framework automatically sanitizes:

  • Authentication tokens and passwords
  • Personal identifiable information (PII)
  • Internal system identifiers
  • Sensitive configuration values

Network Security

  • Use HTTPS-only connections for all API calls
  • Validate SSL certificates in production mode
  • Implement request signing where supported
  • Enable audit logging for test activities

Getting Help

Debug Mode 

# Enable verbose logging
DEBUG=true make test-servicenow

# Save detailed logs
make test-servicenow 2>&1 | tee connector-debug.log

Support Resources

Next Steps:

Edit this page on GitHub
Prev
CLI Reference
Next
ServiceNow Troubleshooting