test: Add integration tests with Mock NITRO API for Issue #12

[slauger]

Summary

This PR adds comprehensive integration tests with a fully functional Mock NITRO API server, enabling end-to-end testing without requiring a real NetScaler appliance.

Motivation

Related to #12 - Chain certificate rotation tracking

To implement and test the chain rotation feature (#12), we need:

1. A way to test the complete plugin workflow without NetScaler hardware
2. Accurate simulation of NITRO API behavior, especially certificate serial number tracking
3. Integration tests covering real-world scenarios including chain rotation

What's New

Integration Tests (tests/test_integration.py)

Six comprehensive end-to-end tests covering:

• ✅ Initial Installation - Fresh NetScaler setup with chain and main certificate
• ✅ Certificate Renewal - Renewal with same chain (serial number comparison)
• ✅ Idempotent Runs - No-op when certificates are already up-to-date
• ⏸️ Chain Rotation (Issue further automation? #12) - E6 → E7 rotation (test ready, waiting for implementation)
• ✅ Authentication Errors - Proper error handling for invalid credentials
• ✅ Custom Chain Names - Override auto-detection with --chain parameter

Enhanced Mock NITRO API

The mock server has been significantly improved:

New Capabilities:

• Stores uploaded certificate files in memory (Base64-encoded)
• Automatically extracts serial numbers from PEM certificates using PyOpenSSL
• Tracks certificate serials for renewal detection
• Simulates NetScaler behavior accurately

Key Implementation (tests/mock_nitro/state.py):

def extract_serial_from_cert(cert_path: str) -> Optional[str]:
    """Extract serial number from an uploaded certificate file."""
    filename = cert_path.split('/')[-1]
    cert_pem = base64.b64decode(_uploaded_files[filename])
    cert = crypto.load_certificate(crypto.FILETYPE_PEM, cert_pem)
    return hex(cert.get_serial_number())

This enables the mock to behave like a real NetScaler, automatically extracting and storing serial numbers when certificates are uploaded and installed.

Chain Rotation Test (Issue #12)

The test test_chain_rotation_issue_12 demonstrates the expected workflow:

# 1. Initial state: Main cert linked to E6
assert main_cert.get('linkcertkeyname') == 'E6'

# 2. Let's Encrypt rotates: chain.pem now contains E7
# (test simulates this by replacing the chain file)

# 3. Run hook with --update-chain --no-domain-check
run_hook('example.com', temp_certs, update_chain=True, no_domain_check=True)

# 4. Expected result: Main cert now linked to E7
assert main_cert.get('linkcertkeyname') == 'E7'

This test is currently skipped (not implemented yet), but provides a clear specification for the chain rotation feature.

Test Results

All existing tests still pass:

======================== test session starts =========================
tests/test_certificate_cn.py ............... [ 60%]   (15 passed)
tests/test_chain_rotation.py ....           [ 76%]   ( 4 passed)
tests/test_integration.py .....s            [100%]   ( 5 passed, 1 skipped)

================== 24 passed, 1 skipped in 8.87s ====================

Technical Details

Certificate Serial Number Tracking:
The mock API now accurately simulates NetScaler's serial number handling:

1. When a certificate file is uploaded via systemfile endpoint, it's stored
2. When a certificate object is created via sslcertkey endpoint, the serial is extracted from the uploaded file
3. When querying certificates, the serial is returned (enabling renewal detection)

Fixtures Used:

• mock_server - Flask server running in background thread
• temp_certs - Real X.509 certificates generated with PyOpenSSL
• env_vars - Environment variables for NITRO API connection

Next Steps

This PR provides the testing infrastructure for implementing #12. Once merged, the chain rotation feature can be developed with confidence, knowing that comprehensive tests are in place.

Checklist

• All new tests pass
• No existing tests were broken
• Mock NITRO API accurately simulates NetScaler behavior
• Tests cover realistic scenarios (installation, renewal, rotation)
• Chain rotation test is ready (skipped until feature is implemented)
• Documentation updated (Mock API README)

---

🤖 Generated with Claude Code