This directory contains the test suite for the Ansible Docker infrastructure using the Bats (Bash Automated Testing System) framework.
The test suite validates:
- Ansible configuration syntax and linting
- Ansible playbook execution
- Docker provisioning
- ansible-pull functionality
- Shell script syntax
tests/bash/
├── run-tests.sh # Test runner script
├── lint-test.bats # Linting tests (yamllint, ansible-lint)
├── syntax-test.bats # Syntax validation tests
├── docker-test.bats # Docker provisioning tests
├── ansible-pull-test.bats # ansible-pull functionality tests
├── github-ssh-keys-test.bats # github_ssh_keys role tests
└── git-repos-test.bats # git_repos role tests (github_user format + e2e clone)
./tests/bash/run-tests.sh./tests/bash/run-tests.sh --test lint-test.batsThis installs dependencies automatically and generates JUnit XML output:
./tests/bash/run-tests.sh --ci./tests/bash/run-tests.sh --help- Python 3.8+
- Bash 4.0+
- Bats (will be auto-installed if not present)
The test runner will automatically:
- Install Bats if not found (via npm, homebrew, or from source in CI mode)
- Install required Python packages (ansible, ansible-lint, yamllint)
- Install required Ansible collections
In CI mode (--ci flag), the script will:
- Install Bats from GitHub releases
- Generate JUnit XML test results (
test-results.xml) - Exit with non-zero status on failures
Each .bats file contains multiple test cases following this pattern:
#!/usr/bin/env bats
setup() {
# Runs before each test
REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/../.." && pwd)"
export REPO_ROOT
}
@test "descriptive test name" {
# Test commands
run command_to_test
[ "$status" -eq 0 ]
}Validates code quality and style:
- yamllint checks on YAML files
- ansible-lint checks on Ansible roles
- Excludes external roles (e.g., geerlingguy.docker)
Validates syntax without execution:
- Ansible playbook syntax
- Shell script syntax (bash and sh)
- Verifies required files exist
Tests Docker provisioning:
- Ansible can install required collections
- Test inventory can be created
- Playbook passes in check mode
- Docker role can be applied
- Docker is installed and running
Tests ansible-pull functionality:
- ansible-pull script exists and is valid
- ansible-pull can run from local repository
- Inventory files are in correct locations
Tests the git_repos role github_user enumeration format:
- Role task and defaults files exist (including
clone_shim.yml) github_user.ymlandclone_shim.ymltask files are valid YAMLmain.ymlwires in thegithub_usersub-tasks- All clone formats delegate to the shared
clone_shim.ymlshim task - The GitHub repos API is reachable for the test user
- End-to-end: applies the role against
localhostfor a real GitHub handle, capped to a single repository vialimit: 1, and asserts exactly one empty shim was created (remote configured, working tree empty), thatgit pullthen populates it, and that re-running the role fast-forwards the now-populated repo without emptying it (CI only — requires sudo and network)
The CI workflow (.github/workflows/ci.yml) runs the test suite on:
- Push to
mainorcopilot/**branches - Pull requests
- Manual workflow dispatch
Features:
- Automatic dependency installation
- Test result publishing
- Test artifacts upload
- Parallel execution support
Test results are published using the EnricoMi/publish-unit-test-result-action which provides:
- Test summary in PR checks
- Failed test details
- Test trends over time
- Create a new
.batsfile intests/bash/ - Add a
setup()function for test initialization - Write test cases using
@testblocks - Use
runcommand to capture command output and exit status - Make assertions using standard bash test operators
Example:
#!/usr/bin/env bats
setup() {
REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/../.." && pwd)"
export REPO_ROOT
}
@test "my new test" {
# Run a command
run echo "hello world"
# Assert exit status
[ "$status" -eq 0 ]
# Assert output content
[[ "$output" =~ "hello" ]]
}
@test "test with skip condition" {
if [ ! -f /some/optional/file ]; then
skip "Optional file not present"
fi
run cat /some/optional/file
[ "$status" -eq 0 ]
}- Use descriptive test names: Make it clear what is being tested
- Use
skipfor conditional tests: Don't fail tests for missing optional dependencies - Clean up after tests: Remove temporary files and directories
- Test in isolation: Each test should be independent
- Use setup/teardown: Initialize test environment properly
- Handle CI differences: Some tests may need to skip in CI environments
The test runner will attempt to install Bats automatically. If this fails:
- macOS:
brew install bats-core - Ubuntu/Debian:
sudo apt-get install bats - npm:
npm install -g bats - Manual: See Bats installation guide
This usually indicates environment differences. Common causes:
- Missing system packages
- Different Python/Ansible versions
- File permissions issues
- sudo configuration differences
Run linting tests individually to see specific errors:
./tests/bash/run-tests.sh --test lint-test.batsFix yamllint errors in your YAML files according to the yamllint rules.
Fix ansible-lint errors according to Ansible best practices.