Lambda CI/CD Coverage Tests

Overview

This document describes the comprehensive test suite for validating that all Lambda functions in the Momentum backend have proper CI/CD coverage in the GitHub Actions workflow.

Purpose

The test suite (scripts/testing/test-workflow-lambda-coverage.sh) ensures that:

All Lambda functions are properly configured for deployment
No Lambda function is accidentally excluded from the CI/CD pipeline
The workflow configuration stays in sync with the codebase structure
New Lambda functions are automatically validated

Test Suites

1. Package Lock Files

Purpose: Verify all Lambda functions have package-lock.json for dependency caching.

What it checks:

Each Lambda function directory in backend/functions/ has a package-lock.json file

Why it matters:

Package lock files ensure consistent dependency versions across builds
Required for npm cache in GitHub Actions
Missing lock files cause slower builds and potential version drift

Fix if failing:

cd backend/functions/<function-name>
npm install  # Generates package-lock.json

2. Workflow Cache Dependencies

Purpose: Ensure all Lambda package-lock.json files are in the workflow cache path.

What it checks:

Each Lambda function’s package-lock.json is listed in the cache-dependency-path section of the workflow

Why it matters:

Caching dependencies speeds up CI/CD builds significantly
Missing from cache means slower builds (re-downloads all dependencies every time)

Fix if failing: Add to .github/workflows/deploy-infrastructure.yml:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: $
    cache: 'npm'
    cache-dependency-path: |
      backend/functions/courses/package-lock.json
      backend/functions/lessons/package-lock.json
      # ... add missing function here:
      backend/functions/your-function/package-lock.json

3. Workflow Build Steps

Purpose: Verify all Lambda functions have build steps in the workflow.

What it checks:

Each Lambda function has a “Build function" step in the workflow
Special handling for ai-generation which uses “Build AI generation functions” (plural)

Why it matters:

Without a build step, the Lambda function won’t be compiled
Missing build step means deployment will fail (no ZIP file created)

Fix if failing: Add to .github/workflows/deploy-infrastructure.yml in the build-lambdas job:

- name: Build your-function function
  working-directory: backend/functions/your-function
  run: |
    npm ci
    npm run build

4. Workflow Artifact Upload

Purpose: Ensure all Lambda ZIP files are uploaded as artifacts.

What it checks:

Each Lambda function’s dist/index.zip is in the artifact upload path
Special handling for ai-generation which uses dist/*.zip (wildcard for multiple handlers)

Why it matters:

Artifacts are required for the deployment job
Missing artifact path means deployment will fail (ZIP file not found)

Fix if failing: Add to .github/workflows/deploy-infrastructure.yml in the “Upload Lambda artifacts” step:

- name: Upload Lambda artifacts
  uses: actions/upload-artifact@v4
  with:
    name: lambda-packages
    path: |
      backend/functions/courses/dist/index.zip
      # ... add missing function here:
      backend/functions/your-function/dist/index.zip

5. Workflow Deployment Steps

Purpose: Verify all Lambda functions have deployment steps.

What it checks:

Each Lambda function has a “Deploy Lambda" step in the workflow
Special handling for ai-generation which has a separate multi-handler deployment step

Why it matters:

Without deployment step, changes won’t be deployed to AWS
Missing deployment means the Lambda will continue running old code

Fix if failing: Add to .github/workflows/deploy-infrastructure.yml in the deploy-lambdas job:

- name: Deploy Your-Function Lambda
  run: |
    aws lambda update-function-code \
      --function-name momentum-your-function-$ \
      --zip-file fileb://backend/functions/your-function/dist/index.zip \
      --region $

6. Lambda Update Wait Steps

Purpose: Ensure all Lambda functions are in the wait loop for update completion.

What it checks:

Each Lambda function (except ai-generation) is in the FUNCTIONS array in the wait step
AI generation handlers are not checked (they have separate deployment logic)

Why it matters:

Ensures the workflow waits for Lambda updates to stabilize before completing
Missing from wait array can cause race conditions or incomplete deployments

Fix if failing: Add to .github/workflows/deploy-infrastructure.yml in the “Wait for Lambda updates to complete” step:

FUNCTIONS=(
  "momentum-courses-$"
  "momentum-lessons-$"
  # ... add missing function here:
  "momentum-your-function-$"
)

7. AI Generation Handler Coverage

Purpose: Verify all AI generation handlers are in the workflow deployment array.

What it checks:

All handlers in backend/functions/ai-generation/scripts/package-handlers.sh are in the workflow
All handlers in the workflow exist in the package script

Why it matters:

AI generation uses multiple Lambda functions (one per handler)
Missing handler means it won’t be deployed
Extra handler in workflow means deployment will fail

Fix if failing:

If missing in workflow, add to .github/workflows/deploy-infrastructure.yml in “Deploy AI Generation Lambdas”:

AI_HANDLERS=(
  "start-generation"
  "validate-input"
  # ... add missing handler here:
  "your-new-handler"
)

If extra in workflow, either:

Remove from workflow AI_HANDLERS array, OR
Create the handler source file: backend/functions/ai-generation/src/handlers/your-handler.ts

8. Deployment Summary Coverage

Purpose: Verify all Lambda functions are listed in the deployment summary.

What it checks:

Each Lambda function is mentioned in the deployment summary job
AI generation functions are mentioned as a group

Why it matters:

Provides visibility into what was deployed
Missing from summary doesn’t break deployment but reduces transparency

Fix if failing (optional - warnings only): Add to .github/workflows/deploy-infrastructure.yml in the deployment-summary job:

echo "- momentum-your-function-$" >> $GITHUB_STEP_SUMMARY

Running the Tests

Locally

# From project root
./scripts/testing/test-workflow-lambda-coverage.sh

In CI/CD

The tests run automatically on every push to main or when the workflow file changes, as part of the validate-handlers job.

Test Output

Success

============================================
  CI/CD Workflow Lambda Coverage Tests
============================================

...

Total Tests: 58
Passed: 58

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

Failure

Total Tests: 58
Passed: 51
Failed: 7

Failed Tests:
  ✗ your-function in cache-dependency-path
  ✗ your-function has build step
  ...

============================================
  ✗ 7 test(s) failed
============================================

Please fix the issues listed above and re-run the tests.

Adding a New Lambda Function

When adding a new Lambda function, ensure you:

Create the function directory:

mkdir -p backend/functions/your-function

Initialize with package.json:

cd backend/functions/your-function
npm init -y
npm install

Add build configuration:
- Add TypeScript/build configuration
- Add build script to package.json
- Test build locally: npm run build
Update workflow (add to .github/workflows/deploy-infrastructure.yml):
- Add to cache-dependency-path
- Add build step in build-lambdas job
- Add to artifact upload path
- Add deployment step in deploy-lambdas job
- Add to wait FUNCTIONS array
- Add to deployment summary

Run validation tests:

./scripts/testing/test-workflow-lambda-coverage.sh

Fix any failures reported by the test

Test Maintenance

When to Update Tests

Update the test script when:

Changing the workflow structure
Renaming Lambda functions
Changing build/deployment patterns
Adding new validation requirements

Test Dependencies

The test script depends on:

Bash 4.0+
Standard Unix tools (grep, sed, awk)
Access to the repository file structure

Test Limitations

The test script does NOT validate:

AWS infrastructure (Terraform resources)
Lambda function code quality
Runtime behavior
Integration with other services

These aspects are covered by other test suites (unit tests, integration tests, E2E tests).

Troubleshooting

Test fails but workflow looks correct

Check for whitespace issues in YAML
Verify function names match exactly (case-sensitive)
Check for special characters or typos

Run test with set -x for debugging:

bash -x ./scripts/testing/test-workflow-lambda-coverage.sh

Test passes but deployment fails

The test only validates workflow configuration, not runtime behavior
Check AWS credentials and permissions
Verify Lambda function code builds successfully
Check CloudWatch logs for Lambda errors

Need to skip a function temporarily

Add to placeholder check in test script (not recommended)
Better: Fix the function to have proper structure
Or: Move to a _archived directory if truly not needed

CI/CD Integration

This test is integrated into the GitHub Actions workflow as the first validation step:

Job: validate-handlers
Runs: On every push to main or workflow file changes
Blocks: Deployment if validation fails
Reports: Detailed errors in GitHub Actions UI

Future Enhancements

Planned improvements:

Add validation for Terraform Lambda resources
Check Lambda function naming conventions
Validate environment variable consistency
Test IAM role/policy coverage
Add JSON/YAML linting for workflow file
Generate coverage report (HTML/JSON)

Lambda CI/CD Coverage Tests

Overview

Purpose

Test Suites

1. Package Lock Files

2. Workflow Cache Dependencies

3. Workflow Build Steps

4. Workflow Artifact Upload

5. Workflow Deployment Steps

6. Lambda Update Wait Steps

7. AI Generation Handler Coverage

8. Deployment Summary Coverage

Running the Tests

Locally

In CI/CD

Test Output

Success

Failure

Adding a New Lambda Function

Test Maintenance

When to Update Tests

Test Dependencies

Test Limitations

Troubleshooting

Test fails but workflow looks correct

Test passes but deployment fails

Need to skip a function temporarily

Related Documentation

CI/CD Integration

Future Enhancements