Mooncake Testing Architecture¶
📚 Other Docs: Index | Quick Reference | Testing Guide | Implementation
Overview Diagram¶
┌─────────────────────────────────────────────────────────────────┐
│ Mooncake Test Infrastructure │
└─────────────────────────────────────────────────────────────────┘
┌──────────────────────────┐ ┌──────────────────────────────────┐
│ LOCAL DEVELOPMENT │ │ CI/CD (GitHub) │
└──────────────────────────┘ └──────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Makefile Commands │
│ ┌───────────┐ ┌──────────┐ ┌────────────┐ ┌──────────────┐ │
│ │make test │ │make test-│ │make test- │ │make test-all-│ │
│ │ │ │quick │ │docker-all │ │platforms │ │
│ └─────┬─────┘ └────┬─────┘ └──────┬─────┘ └──────┬───────┘ │
└────────┼─────────────┼───────────────┼────────────────┼─────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────┐ ┌──────────────────────────────────────────────┐
│ Native │ │ Docker Test Matrix │
│ Go Tests │ ├──────────┬──────────┬──────────┬─────────────┤
│ (10 sec) │ │ Ubuntu │ Alpine │ Debian │ Fedora │
└─────────────┘ │ 22.04 │ 3.19 │ 12 │ 39 │
│ 20.04 │ │ │ │
└──────────┴──────────┴──────────┴─────────────┘
│ │ │ │
└──────────┴──────────┴──────────┘
│
┌──────────▼──────────┐
│ test-runner.sh │
│ ┌────────────────┐ │
│ │ Smoke Tests │ │
│ │ Integration │ │
│ └────────────────┘ │
└─────────────────────┘
CI/CD Pipeline¶
GitHub Push
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GitHub Actions Workflow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ JOB: unit-tests (Matrix: 4 platforms) │ │
│ │ ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ ubuntu- │ │ macos- │ │ macos-13 │ │ windows- │ │ │
│ │ │ latest │ │ latest │ │ (Intel) │ │ latest │ │ │
│ │ │ (x86_64) │ │ (ARM) │ │ │ │ │ │ │
│ │ └─────────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ JOB: docker-tests (Matrix: 5 distros) │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ │Ubuntu│ │Ubuntu│ │Alpine│ │Debian│ │Fedora│ │ │
│ │ │22.04 │ │20.04 │ │ 3.19 │ │ 12 │ │ 39 │ │ │
│ │ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ │ │
│ │ │ │ │ │ │ │ │
│ │ └────────┴────────┴────────┴────────┘ │ │
│ │ │ │ │
│ │ Smoke + Integration │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ JOB: integration-tests (Needs: unit-tests) │ │
│ │ ┌─────────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ ubuntu- │ │ macos- │ │ windows- │ │ │
│ │ │ latest │ │ latest │ │ latest │ │ │
│ │ └─────────────┘ └──────────┘ └──────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
Pass Pass Pass
Test Fixture Organization¶
testing/fixtures/
├── configs/
│ ├── smoke/ # Fast validation (<1 min total)
│ │ ├── 001-version-check.yml # Binary works
│ │ ├── 002-simple-file.yml # File operations
│ │ ├── 003-simple-shell.yml # Shell execution
│ │ └── 004-simple-vars.yml # Variables
│ │
│ └── integration/ # Full features (5-10 min total)
│ ├── 010-file-operations.yml # Complete file workflow
│ ├── 020-loops.yml # Loop iteration
│ ├── 030-conditionals.yml # When conditions
│ └── 040-shell-commands.yml # Complex shell
│
└── templates/
└── test-template.j2 # Template rendering test
Docker Test Flow¶
┌─────────────────────────────────────────────────────────────┐
│ Docker Test Process │
└─────────────────────────────────────────────────────────────┘
Step 1: Build Binary
┌─────────────────────────────────────────────┐
│ env GOOS=linux GOARCH=amd64 \ │
│ go build -o out/mooncake-linux-amd64 ./cmd │
└──────────────────┬──────────────────────────┘
│
▼
Step 2: Build Docker Image
┌─────────────────────────────────────────────┐
│ docker build -f testing/docker/ubuntu. │
│ Dockerfile -t mooncake-test-ubuntu . │
│ │
│ Dockerfile: │
│ - FROM ubuntu:22.04 │
│ - Install: curl, git, sudo │
│ - COPY binary → /usr/local/bin/mooncake │
│ - COPY test-runner.sh → /test-runner.sh │
│ - COPY fixtures/ → /fixtures/ │
└──────────────────┬──────────────────────────┘
│
▼
Step 3: Run Tests
┌─────────────────────────────────────────────┐
│ docker run --rm mooncake-test-ubuntu smoke │
│ │
│ Container executes: │
│ /test-runner.sh smoke │
│ ↓ │
│ For each test in /fixtures/configs/smoke/│
│ mooncake run -c test.yml │
│ Save results to /workspace/results/ │
└─────────────────────────────────────────────┘
Test Runner Logic¶
test-runner.sh
├── Verify mooncake binary exists
├── Parse TEST_SUITE parameter (smoke|integration|all)
│
├── run_smoke_tests()
│ ├── Find all *.yml in /fixtures/configs/smoke/
│ ├── For each test:
│ │ ├── Run: mooncake run -c test.yml
│ │ ├── Capture output to results/
│ │ ├── Track pass/fail count
│ │ └── Print ✓ or ✗
│ └── Return status
│
├── run_integration_tests()
│ ├── Find all *.yml in /fixtures/configs/integration/
│ ├── For each test:
│ │ ├── Run: mooncake run -c test.yml
│ │ ├── Capture output to results/
│ │ ├── Track pass/fail count
│ │ └── Print ✓ or ✗
│ └── Return status
│
└── Exit with appropriate code
Script Orchestration¶
make test-all-platforms
├── Run native Go tests
│ └── go test -v ./...
│
└── Run Docker multi-distro tests
└── scripts/test-docker-all.sh
├── Build Linux binary once
├── For each distro:
│ ├── scripts/test-docker.sh <distro>
│ │ ├── Build Docker image
│ │ └── Run container with test suite
│ └── Track pass/fail
└── Print summary
Platform Coverage Matrix¶
┌─────────────────┬────────┬────────┬─────────┬──────────────┐
│ │ Local │ CI │ Docker │ Native │
├─────────────────┼────────┼────────┼─────────┼──────────────┤
│ Ubuntu 22.04 │ │ │ │ │
│ Ubuntu 20.04 │ │ │ │ │
│ Alpine 3.19 │ │ │ │ │
│ Debian 12 │ │ │ │ │
│ Fedora 39 │ │ │ │ │
│ macOS (ARM) │ │ │ │ │
│ macOS (Intel) │ │ │ │ │
│ Windows │ │ │ │ │
└─────────────────┴────────┴────────┴─────────┴──────────────┘
Legend:
= Tested
Local = Developer machine
CI = GitHub Actions
Docker = Container-based testing
Native = Direct OS execution
Test Types and Timing¶
┌──────────────┬─────────────┬─────────┬──────────────────────┐
│ Test Type │ Count │ Time │ Purpose │
├──────────────┼─────────────┼─────────┼──────────────────────┤
│ Unit │ Per package │ ~10s │ Go code validation │
│ Smoke │ 4 tests │ ~30s │ Basic functionality │
│ Integration │ 4 tests │ ~2-5m │ Feature validation │
│ Full Suite │ All above │ ~15m │ Complete validation │
└──────────────┴─────────────┴─────────┴──────────────────────┘
Smoke Tests:
- Binary execution ✓
- File operations ✓
- Shell commands ✓
- Variables ✓
Integration Tests:
- File workflow ✓
- Loops ✓
- Conditionals ✓
- Complex shell ✓
Directory Structure¶
mooncake/
│
├── .github/workflows/
│ └── ci.yml ────────────────► CI/CD configuration
│
├── testing/
│ ├── docker/ ───────────────► Dockerfiles (5 distros)
│ ├── common/
│ │ └── test-runner.sh ────► Test orchestration
│ ├── fixtures/
│ │ ├── configs/
│ │ │ ├── smoke/ ────────► 4 smoke tests
│ │ │ └── integration/ ──► 4 integration tests
│ │ └── templates/ ────────► Test templates
│ ├── results/ ──────────────► Test outputs (gitignored)
│ └── README.md ─────────────► Testing documentation
│
├── scripts/
│ ├── test-docker.sh ────────► Single distro test
│ ├── test-docker-all.sh ────► Multi-distro test
│ ├── test-all-platforms.sh ─► Complete test suite
│ └── run-integration-tests.sh ► Integration runner
│
├── Makefile ──────────────────► Test targets
└── out/ ──────────────────────► Compiled binaries
Data Flow¶
Developer
│
├─► Edit Code
│ │
│ ▼
│ make test ────► go test ./... ────► /
│
├─► make test-quick
│ │
│ ├─► Build Linux binary
│ ├─► Build Docker image (Ubuntu)
│ ├─► Run smoke tests
│ └─► /
│
├─► make test-all-platforms
│ │
│ ├─► go test ./...
│ ├─► Build Linux binary
│ ├─► For each distro:
│ │ ├─► Build image
│ │ └─► Run smoke + integration
│ └─► / Summary
│
└─► git push
│
▼
GitHub Actions
│
├─► unit-tests (4 platforms)
├─► docker-tests (5 distros)
└─► integration-tests (3 platforms)
│
▼
/ Status
Success Metrics¶
┌────────────────────────────────────────────────────┐
│ Testing Success Criteria │
├────────────────────────────────────────────────────┤
│ │
│ ⚡ Fast Feedback │
│ • Local smoke: < 2 minutes │
│ • CI complete: < 10 minutes │
│ │
│ 🔍 Comprehensive Coverage │
│ • 5 Linux distros tested │
│ • macOS Intel + ARM │
│ • Windows Server │
│ │
│ 👨💻 Developer Experience │
│ • Single command testing │
│ • Clear documentation │
│ • Easy to add tests │
│ │
│ Quality Assurance │
│ • Unit tests: >60% coverage │
│ • Smoke tests: 4 scenarios │
│ • Integration: 4 workflows │
│ │
└────────────────────────────────────────────────────┘
Future Architecture Enhancements¶
Potential Additions:
├── ARM64 Linux Testing
│ └── Add arm64 Docker builds
│
├── Performance Benchmarking
│ ├── Benchmark suite
│ └── Historical tracking
│
├── Test Result Dashboard
│ ├── Web UI for results
│ └── Trend analysis
│
└── Extended Platform Support
├── FreeBSD
├── OpenBSD
└── Additional Linux distros
Key Design Decisions¶
- Docker for Linux - Portable, reproducible, multi-distro support
- Native for macOS - Simplest, fastest, no containerization overhead
- CI-only for Windows - Avoid VM complexity, sufficient for validation
- Two-tier tests - Smoke (fast feedback) + Integration (thorough)
- Parallel execution - Maximize throughput in CI
- Cached layers - Docker caching for faster rebuilds
- Gitignored results - Keep repo clean, results are ephemeral
- Shell scripts - Portable, easy to debug, no extra dependencies
For detailed usage instructions, see: guide.md
For quick reference, see: quick-reference.md