Lambda Packaging Tests

Overview

This document describes the test suite for the Lambda packaging system in the AI Generation functions. The tests verify that all handler source files are correctly configured in the build system and prevent deployment of incomplete Lambda packages.

Background: The Bug

Original Issue

On December 5, 2025, a critical bug was discovered in the Lambda packaging process:

Problem: Two new Lambda handlers (poll-video-status and update-course-video) were added to the source code in backend/functions/ai-generation/src/handlers/, but they were not added to the HANDLERS array in backend/functions/ai-generation/scripts/package-handlers.sh.

Impact:

The handlers compiled successfully (TypeScript → JavaScript)
The build script did not create ZIP files for these handlers
Terraform deployment succeeded but the Lambda functions were not actually deployed
The system appeared to work but the new functionality was silently missing

Root Cause: The package-handlers.sh script maintains a manual HANDLERS array that must be kept in sync with the actual handler source files. When developers add new handlers, they must remember to update this array.

The Fix

The bug was fixed by adding the missing handlers to the HANDLERS array:

HANDLERS=(
  "validate-input"
  "generate-outline"
  "generate-lesson-prompts"
  "trigger-video"
  "save-course"
  "get-status"
  "regenerate-lesson"
  "start-generation"
  "poll-video-status"      # ← Added
  "update-course-video"     # ← Added
)

Test Suite Architecture

The test suite consists of three components:

1. Unit Tests (`test-package-handlers.sh`)

Purpose: Comprehensive validation of the packaging configuration

Location: /backend/functions/ai-generation/scripts/test-package-handlers.sh

Test Coverage:

Handler Configuration Validation (NEW)
- Verifies src/handlers/ directory exists
- Extracts HANDLERS array from package-handlers.sh
- Discovers all .ts handler source files
- Compares source files with HANDLERS array
- Reports missing or extra handlers with actionable error messages
- Verifies ZIP files exist in dist directory (post-build)
Arithmetic Operations with set -e
- Pre-increment behavior with zero values
- Post-increment workarounds
- Counter behavior in conditionals
Package Script Structure
- Script file existence and permissions
- set -e flag enabled
- Correct use of pre-increment operators
- No problematic post-increment operators
Mock Packaging Execution
- Simulates packaging workflow
- Tests counter increments
- Verifies ZIP file creation
- Tests failure scenarios
Counter Behavior
- Counter initialization
- Increment operations
- Exit code validation

Run Command:

npm run test:scripts
# or
./scripts/test-package-handlers.sh

Expected Output (when all handlers are configured):

============================================
  Package Handlers Script - Unit Tests
============================================

Test Suite: Handler Configuration Validation
Verifying all source handlers are declared in HANDLERS array

✓ Source handlers directory exists
✓ HANDLERS array extracted from package-handlers.sh
  Declared handlers:
    - validate-input
    - generate-outline
    - ...
✓ Handler source files discovered
  Source handlers (.ts files):
    - generate-lesson-prompts
    - generate-outline
    - ...
✓ All 10 source handlers are properly declared in HANDLERS array
✓ All 10 handler ZIP files exist in dist directory

...

Total Tests: 31
Passed: 31
Failed: 0

✓ All tests passed!

2. Integration Test (`test-handler-mismatch.sh`)

Purpose: Verify that the test suite correctly detects handler configuration mismatches

Location: /backend/functions/ai-generation/scripts/test-handler-mismatch.sh

How it Works:

Creates a temporary test environment
Creates 4 mock handler source files
Creates a package-handlers.sh with only 2 handlers (simulating the bug)
Runs test-package-handlers.sh in the test environment
Verifies that the test correctly fails and reports the missing handlers

Run Command:

npm run test:scripts:integration
# or
./scripts/test-handler-mismatch.sh

Expected Output:

============================================
  Lambda Packaging Bug - Integration Test
============================================

Creating mock handler source files...
✓ Created 4 handler source files
Creating package-handlers.sh with missing handlers...
⚠ Package script created with only 2 handlers (2 missing)

Running test-package-handlers.sh...
Expected: Test should FAIL and report missing handlers

...

✗ Handler configuration mismatch detected!

  CRITICAL: Missing in HANDLERS array (present in source):
    ✗ poll-video-status
    ✗ update-course-video

  ACTION REQUIRED:
  Add the following to HANDLERS array in package-handlers.sh:
    "poll-video-status"
    "update-course-video"

...

✓ PASS: Test script correctly failed (exit code 1)
✓ PASS: Test output correctly identifies missing handlers
✓ PASS: Test output provides clear action items

============================================
  ✓ All integration tests passed!
============================================

The test correctly detected the Lambda packaging bug
and would prevent deployment with missing handlers.

3. CI/CD Integration

The tests are integrated into the development workflow:

Pre-Build Check:

npm test
# Runs both Jest unit tests and packaging tests

Pre-Deploy Check (recommended):

npm run test:scripts
# Verifies handler configuration before deployment

Adding New Lambda Handlers

Step-by-Step Process

When adding a new Lambda handler, follow these steps to avoid the bug:

1. Create the Handler Source File

# Create the new handler
cat > backend/functions/ai-generation/src/handlers/my-new-handler.ts << 'EOF'
import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger({ serviceName: 'ai-generation' });

export const handler = async (event: any) => {
  logger.info('My new handler invoked', { event });
  // Handler logic here
};
EOF

2. Update the HANDLERS Array

Edit backend/functions/ai-generation/scripts/package-handlers.sh:

HANDLERS=(
  "validate-input"
  "generate-outline"
  # ... existing handlers ...
  "my-new-handler"  # ← Add your new handler here
)

3. Run Tests

cd backend/functions/ai-generation

# Run the packaging tests
npm run test:scripts

Expected Output (if you forgot to add it to HANDLERS array):

✗ Handler configuration mismatch detected!

  CRITICAL: Missing in HANDLERS array (present in source):
    ✗ my-new-handler

  ACTION REQUIRED:
  Add the following to HANDLERS array in package-handlers.sh:
    "my-new-handler"

4. Build and Deploy

# Build the Lambda packages
npm run build

# Verify ZIP file was created
ls -lh dist/my-new-handler.zip

# Deploy with Terraform
cd ../../../infrastructure/terraform
terraform apply

Automated Validation

The tests will automatically:

Discover all .ts files in src/handlers/
Extract the HANDLERS array from package-handlers.sh
Compare them and report any mismatches
Provide actionable error messages with exact handler names
Fail with exit code 1 to prevent CI/CD deployment

Test Development Notes

Why This Test is Important

This bug class (manual array maintenance) is common in build systems:

Silent Failures: The build succeeds but produces incomplete artifacts
Deployment Issues: Terraform applies successfully but functions are missing
Runtime Errors: Only discovered when the missing functionality is needed
Hard to Debug: The symptom (function not found) is far from the cause (missing from build array)

Test Design Decisions

Automatic Discovery: Tests discover handlers automatically using find instead of hardcoding
Clear Error Messages: When tests fail, they provide exact copy-paste commands to fix
Integration Testing: Validates that the test itself works correctly
Exit Codes: Properly returns 0 (success) or 1 (failure) for CI/CD integration
Color Output: Uses ANSI colors for better readability
Comprehensive Coverage: Tests both the happy path and failure scenarios

Future Improvements

Potential enhancements to prevent this class of bug:

Auto-Generate HANDLERS Array: Modify package-handlers.sh to automatically discover handlers

# Instead of manual array:
HANDLERS=($(find src/handlers -name "*.ts" | xargs -n1 basename | sed 's/.ts$//'))

Pre-Commit Hook: Add git pre-commit hook to run tests before allowing commits

# .git/hooks/pre-commit
#!/bin/bash
cd backend/functions/ai-generation
npm run test:scripts || exit 1

CI/CD Enforcement: Require tests to pass before allowing Terraform apply ```yaml
.github/workflows/deploy.yml
- name: Test Lambda Packaging run: | cd backend/functions/ai-generation npm run test:scripts ```

Terraform Validation: Have Terraform validate that ZIP files exist for all declared functions

# terraform/ai-generation.tf
locals {
  required_handlers = [
    "validate-input",
    "generate-outline",
    # ...
  ]
}

# Validate all handler ZIPs exist
resource "null_resource" "validate_handlers" {
  provisioner "local-exec" {
    command = <<EOF
      for handler in ${join(" ", local.required_handlers)}; do
        if [ ! -f "../backend/functions/ai-generation/dist/$handler.zip" ]; then
          echo "ERROR: Missing handler ZIP: $handler.zip"
          exit 1
        fi
      done
    EOF
  }
}

Troubleshooting

Test Fails with “Handler configuration mismatch”

Symptom:

✗ Handler configuration mismatch detected!
CRITICAL: Missing in HANDLERS array (present in source):
  ✗ some-handler

Solution: Add the missing handler to the HANDLERS array in package-handlers.sh

Test Shows Extra Handlers

Symptom:

WARNING: Extra in HANDLERS array (not in source):
  ⚠ old-handler

Solution: Either:

Remove the handler from HANDLERS array (if it’s no longer needed)
Create the source file src/handlers/old-handler.ts (if it should exist)

ZIP Files Missing After Build

Symptom:

⚠ Some ZIP files are missing from dist directory
Missing ZIP files:
  - my-handler.zip

Solution:

# Clean and rebuild
npm run clean
npm run build

# If still missing, check that handler is in HANDLERS array
npm run test:scripts

Changelog

2025-12-05

Added: Handler Configuration Validation test suite
Added: Integration test for mismatch detection
Fixed: Missing handlers poll-video-status and update-course-video
Updated: Test documentation
Added: npm script for integration tests

Lambda Packaging Tests

Overview

Background: The Bug

Original Issue

The Fix

Test Suite Architecture

1. Unit Tests (test-package-handlers.sh)

2. Integration Test (test-handler-mismatch.sh)

3. CI/CD Integration

Adding New Lambda Handlers

Step-by-Step Process

1. Create the Handler Source File

2. Update the HANDLERS Array

3. Run Tests

4. Build and Deploy

Automated Validation

Test Development Notes

Why This Test is Important

Test Design Decisions

Future Improvements

.github/workflows/deploy.yml

Troubleshooting

Test Fails with “Handler configuration mismatch”

Test Shows Extra Handlers

ZIP Files Missing After Build

Related Documentation

Changelog

2025-12-05

1. Unit Tests (`test-package-handlers.sh`)

2. Integration Test (`test-handler-mismatch.sh`)