Asterisk Docker Build Test System

This document explains the comprehensive test system for validating Asterisk Docker images locally before CI/CD deployment.

Overview

The test system prevents build failures and configuration issues by validating all supported Asterisk versions with three levels of testing:

Config Mode: Fast template and configuration validation (~1-2 minutes)
Build Mode: Complete Docker image building (~30-60 minutes)
Validate Mode: Full functionality testing including container startup (~45-75 minutes)

All tests run AMD64 only and never push to registry - pure local validation.

Prerequisites

# Required tools
sudo apt install python3 python3-pip docker.io
pip3 install -r requirements.txt

# Python unit-test dependencies (runtime deps + pytest)
pip3 install -r requirements-dev.txt

# Docker buildx support
docker buildx create --use

Python Unit Tests (pytest)

Fast unit tests cover the tag-lifecycle logic, the README updater, and golden regeneration of the generated configs/Dockerfiles/build scripts - no Docker needed for the hermetic tier:

python3 -m pytest tests/

tests/test_tag_lifecycle.py - semantic-tag planning (lib/tag_lifecycle.py)
tests/test_apply_tag_lifecycle.py - YAML application, both phases (scripts/apply-tag-lifecycle.py)
tests/test_update_readme_versions.py - README version-table updater
tests/test_golden_regeneration.py - regenerates 7 representative versions in a throwaway git worktree and asserts byte-identity with the tracked goldens, catching both generator regressions and hand-edits to auto-generated files. The Dockerfile tier (dockerfmt-formatted output) runs when Docker is available and is skipped otherwise; the hermetic tier (configs/build.sh/healthcheck.sh/entrypoint.sh) always runs.

CI runs the suite on every push/PR touching lib/, scripts/, tests/, templates/, configs/generated/, asterisk/, schema/, config/, or the requirements files (.github/workflows/test.yml).

Test Modes Explained

Config Mode (Fastest - Recommended for Development)

What it validates:

✅ YAML configuration parsing and schema validation
✅ Jinja2 template rendering (Dockerfile, build.sh, healthcheck.sh)
✅ Template variable substitution (version, packages, settings)
✅ Configuration file generation without actual building

Example:

scripts/test-build.sh --mode config "22.10.1"

Real output:

2025-09-28 18:10:44 [INFO] Testing version: 22.10.1 (mode: config)
[INFO]  Starting Asterisk build for version: 22.10.1
[INFO]  OS filter: debian
[INFO]  Architecture filter: amd64
[INFO]  DRY RUN MODE - No actual builds will be performed
[INFO]  Build targets:
[INFO]    → debian/trixie (amd64) [from: custom_matrix]
[INFO]  DRY RUN - Would build 1 targets
2025-09-28 18:10:44 [SUCCESS] Version 22.10.1: All tests passed (0s)

=== BUILD STATISTICS ===
Total builds: 1
Successful: 1
Failed: 0
Success rate: 100%

What happens under the hood:

Parses asterisk/supported-asterisk-builds.yml matrix
Loads version configuration from configs/generated/asterisk-22.10.1-trixie.yml
Renders Dockerfile from templates/dockerfile/multi-stage.dockerfile.j2
Generates build script from templates/partials/build.sh.j2
Creates healthcheck from templates/partials/healthcheck.sh.j2
Validates all files were created successfully

Build Mode (Complete Docker Building)

What it validates:

✅ All config mode validations +
✅ Actual Docker image building with buildx
✅ Package installation and dependency resolution
✅ Multi-stage build process execution
✅ Image creation and tagging success

Example:

scripts/test-build.sh --mode build "22.10.1"

What happens under the hood:

All config mode validations
Calls docker buildx build with platform linux/amd64
Downloads Asterisk source tarball
Installs build packages (libicu76, libpqxx-7.10, etc.)
Compiles Asterisk with menuselect configuration
Creates optimized runtime image with only necessary packages
Tags image as 22.10.1_debian-trixie

Real Docker commands executed:

# Generated Dockerfile gets built with:
docker buildx build \
  --platform linux/amd64 \
  --tag 22.10.1_debian-trixie \
  --file Dockerfile \
  ./asterisk/22.10.1-trixie/

Validate Mode (Complete End-to-End Testing)

What it validates:

✅ All build mode validations +
✅ Container startup testing
✅ Asterisk functionality validation
✅ Configuration syntax checking
✅ CLI connectivity testing
✅ Image optimization analysis

Example:

scripts/test-build.sh --mode validate "22.10.1"

Detailed validation steps:

1. Container Startup Test

docker run --rm 22.10.1_debian-trixie asterisk -V

Expected output:

Asterisk 22.10.1 built by root @ buildnode on a x86_64 running Linux on 2025-09-28 18:00:00 UTC

2. Configuration Syntax Validation

docker run --rm 22.10.1_debian-trixie asterisk -T

What this tests:

Parses all configuration files in /etc/asterisk/
Validates syntax without starting Asterisk daemon
Checks for missing files or syntax errors
Tests module loading configuration

3. CLI Functionality Test

docker run --rm 22.10.1_debian-trixie sh -c "asterisk -rx 'core show version'"

What this tests:

Basic Asterisk CLI connectivity
Core module initialization
Remote console functionality
Essential service availability

4. Image Optimization Analysis

# Size validation
docker image inspect 22.10.1_debian-trixie --format '{{.Size}}'

# Layer count analysis
docker image inspect 22.10.1_debian-trixie --format '{{len .RootFS.Layers}}'

Validation criteria:

✅ Image size < 2GB (optimized multi-stage build)
✅ Layer count < 50 (efficient Docker layers)
✅ No unnecessary build dependencies in final image

Usage Examples

Quick Development Testing

# Test latest version config only (30 seconds)
scripts/test-build.sh --mode config "23.4.1"

# Test specific version build (5-10 minutes)
scripts/test-build.sh --mode build "22.10.1"

Pattern Matching

# Test all version 2x releases
scripts/test-build.sh --mode config "2*"
# Matches: 20.20.1, 20.7-cert11, 21.12.3, 22.10.1, 22.8-cert3, 23.4.1

# Test all certified releases
scripts/test-build.sh --mode config "*cert*"
# Matches: 11.6-cert18, 13.21-cert6, 16.8-cert14, 18.9-cert18, 20.7-cert11, 22.8-cert3

Performance Optimization

# Parallel testing for faster validation
scripts/test-build.sh --mode config --parallel --max-parallel 5

# All versions with detailed logging
scripts/test-build.sh --mode config --verbose

CI/CD Integration

# Validate all configs before deployment
scripts/test-build.sh --mode config

# Full validation for release candidates
scripts/test-build.sh --mode validate "23.*"

Real Test Output Examples

Successful Config Test

2025-09-28 18:10:44 [INFO] Initializing Asterisk Docker Build Test System
2025-09-28 18:10:44 [INFO] Test mode: config
2025-09-28 18:10:44 [INFO] Filtered to 1 versions matching pattern: 22.10.1

2025-09-28 18:10:44 [INFO] Testing version: 22.10.1 (mode: config)
[INFO]  Build targets:
[INFO]    → debian/trixie (amd64) [from: custom_matrix]
[INFO]  DRY RUN - Would build 1 targets

2025-09-28 18:10:44 [SUCCESS] Version 22.10.1: All tests passed (0s)

=== DETAILED TEST REPORT ===
Test Mode: config
Architecture: amd64
Tested Versions: 1

=== BUILD STATISTICS ===
Total builds: 1
Successful: 1
Failed: 0
Success rate: 100%

Failed Validation Example

2025-09-28 18:10:37 [INFO] Testing version: 1.4.44 (mode: config)
[INFO]  Build targets:
[INFO]    → debian/jessie (amd64) [template: debian-jessie-legacy-addons]
[ERROR] Config generation failed for 1.4.44

2025-09-28 18:10:37 [ERROR] Version 1.4.44: Tests failed (0s) - Config generation failed for debian/jessie/amd64

=== BUILD STATISTICS ===
Total builds: 1
Failed: 1
Success rate: 0%

=== FAILED BUILDS ===
[ERROR] FAILED: 1.4.44_1.4.44_amd64 - Config generation failed for debian/jessie/amd64

Complete Validation Report

scripts/test-build.sh --mode validate "22.10.1" --verbose

Generated Image Report:

=== IMAGE REPORT: 22.10.1_debian-trixie ===
Size: 876.4MB (918425600 bytes)
Created: 2025-09-28
Asterisk Version: Asterisk 22.10.1 built by root @ buildnode
Container Startup: ✅ PASS
Asterisk Functionality: ✅ PASS
Image Optimization: ✅ PASS

Validation Function Details

`validate_container_startup()`

timeout 30 docker run --rm IMAGE asterisk -V >/dev/null 2>&1

Tests basic container execution
Verifies Asterisk binary functionality
Validates runtime environment setup

`validate_asterisk_functionality()`

# Test 1: Version check
docker run --rm IMAGE asterisk -V

# Test 2: Configuration syntax validation
docker run --rm IMAGE asterisk -T

# Test 3: CLI functionality
docker run --rm IMAGE sh -c "asterisk -rx 'core show version'"

Comprehensive Asterisk functionality testing
Configuration file parsing validation
CLI and core module verification

`validate_image_optimization()`

Size analysis (< 2GB threshold)
Layer count optimization (< 50 layers)
Multi-stage build verification
Runtime dependency validation

Integration with Build Infrastructure

The test system leverages existing build scripts:

# Test system calls build-asterisk.sh with specific flags:
./scripts/build-asterisk.sh 22.10.1 debian amd64 \
  --platforms linux/amd64 \
  --dry-run \        # Config mode only
  --force-config \   # Always regenerate
  --verbose          # Detailed logging

File Generation Process:

configs/generated/asterisk-22.10.1-trixie.yml → Configuration loaded
templates/distributions/debian-trixie.yml → Distribution template resolved
asterisk/22.10.1-trixie/Dockerfile → Generated
asterisk/22.10.1-trixie/build.sh → Generated
asterisk/22.10.1-trixie/healthcheck.sh → Generated

Troubleshooting

Common Issues

No versions found:

# Check available versions
python3 -c "
import yaml
with open('asterisk/supported-asterisk-builds.yml') as f:
    data = yaml.safe_load(f)
for build in data['latest_builds']:
    print(build['version'])
"

Docker buildx issues:

# Ensure buildx is available
docker buildx version
docker buildx create --use

Template errors:

# Test template syntax (variant templates carry {{VERSION}} placeholders)
python3 -c "
import yaml
template = open('templates/variants/modern.yml.template').read()
config = template.replace('{{VERSION}}', '22.10.1')
yaml.safe_load(config)
"

# Distribution templates are plain YAML
python3 -c "import yaml; yaml.safe_load(open('templates/distributions/debian-trixie.yml'))"

Performance Tips

For frequent testing:

# Use config mode for development (fastest)
scripts/test-build.sh --mode config "22.10.1"

# Parallel testing for multiple versions
scripts/test-build.sh --mode config --parallel "2*"

For CI/CD pipelines:

# Full validation before releases
scripts/test-build.sh --mode validate

Docker cache optimization:

# Clean build cache if needed
docker buildx prune -f

Test System Architecture

Modular Components

lib/build-common.sh - Shared functions library
- YAML parsing and version management
- Docker validation functions
- Build result tracking and statistics
- Logging and error handling
scripts/test-build.sh - Main test orchestration
- Three test modes (config/build/validate)
- Pattern matching and filtering
- Parallel processing support
- Comprehensive reporting
Integration Points:
- Leverages scripts/build-asterisk.sh infrastructure
- Uses existing YAML matrix from asterisk/supported-asterisk-builds.yml
- Validates generated configs in configs/generated/
- Tests output in asterisk/VERSION-DISTRIBUTION/ directories

Error Prevention Strategy

The test system prevents the GitHub Actions failures we previously encountered:

Silent Python failures → Comprehensive error reporting with traceback
Configuration generation issues → Config validation mode
Build process validation → Actual build testing with timeouts
Container functionality → Startup and Asterisk CLI testing
Template variable issues → Template rendering validation

Future Extensions

The modular design allows easy extension:

Security scanning: Add container vulnerability tests
Performance benchmarks: Measure startup time and resource usage
Network testing: Validate SIP/RTP connectivity
Integration tests: Test with external services
Regression testing: Compare versions for compatibility

Quick Start:

# Test your changes quickly
scripts/test-build.sh --mode config "22.10.1"

# Full validation before commit
scripts/test-build.sh --mode validate "22.10.1"

# Test all modern versions
scripts/test-build.sh --mode config "2*" --parallel

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Asterisk Docker Build Test System

Overview

Prerequisites

Python Unit Tests (pytest)

Test Modes Explained

Config Mode (Fastest - Recommended for Development)

Build Mode (Complete Docker Building)

Validate Mode (Complete End-to-End Testing)

1. Container Startup Test

2. Configuration Syntax Validation

3. CLI Functionality Test

4. Image Optimization Analysis

Usage Examples

Quick Development Testing

Pattern Matching

Performance Optimization

CI/CD Integration

Real Test Output Examples

Successful Config Test

Failed Validation Example

Complete Validation Report

Validation Function Details

`validate_container_startup()`

`validate_asterisk_functionality()`

`validate_image_optimization()`

Integration with Build Infrastructure

Troubleshooting

Common Issues

Performance Tips

Test System Architecture

Modular Components

Error Prevention Strategy

Future Extensions

Uh oh!

FilesExpand file tree

README-tests.md

Latest commit

History

README-tests.md

File metadata and controls

Asterisk Docker Build Test System

Overview

Prerequisites

Python Unit Tests (pytest)

Test Modes Explained

Config Mode (Fastest - Recommended for Development)

Build Mode (Complete Docker Building)

Validate Mode (Complete End-to-End Testing)

1. Container Startup Test

2. Configuration Syntax Validation

3. CLI Functionality Test

4. Image Optimization Analysis

Usage Examples

Quick Development Testing

Pattern Matching

Performance Optimization

CI/CD Integration

Real Test Output Examples

Successful Config Test

Failed Validation Example

Complete Validation Report

Validation Function Details

validate_container_startup()

validate_asterisk_functionality()

validate_image_optimization()

Integration with Build Infrastructure

Troubleshooting

Common Issues

Performance Tips

Test System Architecture

Modular Components

Error Prevention Strategy

Future Extensions

`validate_container_startup()`

`validate_asterisk_functionality()`

`validate_image_optimization()`