mirror of
https://github.com/mod-playerbots/azerothcore-wotlk.git
synced 2026-01-27 23:56:25 +00:00
feat(bash): startup-scripts reworked + bash scripts workflow integration (#22401)
This commit is contained in:
Yehonal
335
apps/test-framework/README.md
Normal file
335
apps/test-framework/README.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# AzerothCore Test Framework
|
||||
|
||||
This is the centralized test framework for all AzerothCore bash scripts. It provides a unified way to write, run, and manage tests across all modules.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
apps/test-framework/
|
||||
├── run-tests.sh # Universal test runner (single entry point)
|
||||
├── README.md # This documentation
|
||||
├── bats_libs/ # Custom BATS libraries
|
||||
│ ├── acore-support.bash # Test setup and helpers
|
||||
│ └── acore-assert.bash # Custom assertions
|
||||
└── helpers/ # Test utilities
|
||||
└── test_common.sh # Common test functions and setup
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### From any module directory:
|
||||
```bash
|
||||
# Run tests for current module
|
||||
../test-framework/run-tests.sh --dir .
|
||||
|
||||
```
|
||||
|
||||
### From test-framework directory:
|
||||
```bash
|
||||
# Run all tests in all modules
|
||||
./run-tests.sh --all
|
||||
|
||||
# Run tests for specific module
|
||||
./run-tests.sh startup-scripts
|
||||
|
||||
# List available modules
|
||||
./run-tests.sh --list
|
||||
|
||||
# Run tests with debug info
|
||||
./run-tests.sh --all --debug
|
||||
```
|
||||
|
||||
### From project root:
|
||||
```bash
|
||||
# Run all tests
|
||||
apps/test-framework/run-tests.sh --all
|
||||
|
||||
# Run specific module
|
||||
apps/test-framework/run-tests.sh startup-scripts
|
||||
|
||||
# Run with verbose output
|
||||
apps/test-framework/run-tests.sh startup-scripts --verbose
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Commands
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
./run-tests.sh --all
|
||||
|
||||
# Run tests for specific module
|
||||
./run-tests.sh startup-scripts
|
||||
|
||||
# Run tests matching pattern
|
||||
./run-tests.sh --filter starter
|
||||
|
||||
# Run tests in specific directory
|
||||
./run-tests.sh --dir apps/docker
|
||||
|
||||
# Show available modules
|
||||
./run-tests.sh --list
|
||||
|
||||
# Show test count
|
||||
./run-tests.sh --count
|
||||
```
|
||||
|
||||
### Output Formats
|
||||
|
||||
```bash
|
||||
# Pretty output (default)
|
||||
./run-tests.sh --pretty
|
||||
|
||||
# TAP output for CI/CD
|
||||
./run-tests.sh --tap
|
||||
|
||||
# Verbose output with debug info
|
||||
./run-tests.sh --verbose --debug
|
||||
```
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Basic Test Structure
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bats
|
||||
|
||||
# Load the AzerothCore test framework
|
||||
load '../../test-framework/bats_libs/acore-support'
|
||||
load '../../test-framework/bats_libs/acore-assert'
|
||||
|
||||
setup() {
|
||||
acore_test_setup # Standard setup
|
||||
# or
|
||||
startup_scripts_setup # For startup scripts
|
||||
# or
|
||||
compiler_setup # For compiler tests
|
||||
# or
|
||||
docker_setup # For docker tests
|
||||
}
|
||||
|
||||
teardown() {
|
||||
acore_test_teardown
|
||||
}
|
||||
|
||||
@test "my test description" {
|
||||
run my_command
|
||||
assert_success
|
||||
assert_output "expected output"
|
||||
}
|
||||
```
|
||||
|
||||
### Available Setup Functions
|
||||
|
||||
- `acore_test_setup` - Basic setup for all tests
|
||||
- `startup_scripts_setup` - Setup for startup script tests
|
||||
- `compiler_setup` - Setup for compiler tests
|
||||
- `docker_setup` - Setup for docker tests
|
||||
- `extractor_setup` - Setup for extractor tests
|
||||
|
||||
### Custom Assertions
|
||||
|
||||
```bash
|
||||
# Assert binary exists and is executable
|
||||
assert_binary_exists "$TEST_DIR/bin/authserver"
|
||||
|
||||
# Assert server started correctly
|
||||
assert_acore_server_started "$output" "authserver"
|
||||
|
||||
# Assert config was loaded
|
||||
assert_config_loaded "$output" "authserver.conf"
|
||||
|
||||
# Assert build success
|
||||
assert_build_success "$output"
|
||||
|
||||
# Assert timeout occurred (for long-running processes)
|
||||
assert_timeout "$status"
|
||||
|
||||
# Assert log contains content
|
||||
assert_log_contains "$log_file" "Server started"
|
||||
```
|
||||
|
||||
### Test Environment Variables
|
||||
|
||||
When using the framework, these variables are automatically set:
|
||||
|
||||
- `$TEST_DIR` - Temporary test directory
|
||||
- `$AC_TEST_ROOT` - Project root directory
|
||||
- `$AC_TEST_APPS` - Apps directory
|
||||
- `$BUILDPATH` - Build directory path
|
||||
- `$SRCPATH` - Source directory path
|
||||
- `$BINPATH` - Binary directory path
|
||||
- `$LOGS_PATH` - Logs directory path
|
||||
|
||||
### Helper Functions
|
||||
|
||||
```bash
|
||||
# Create test binary
|
||||
create_test_binary "authserver" 0 2 "Server started"
|
||||
|
||||
# Create test config
|
||||
create_test_config "authserver.conf" "Database.Info = \"127.0.0.1;3306;root;pass;db\""
|
||||
|
||||
# Create AzerothCore specific binaries and configs
|
||||
create_acore_binaries
|
||||
create_acore_configs
|
||||
|
||||
# Run command with timeout
|
||||
run_with_timeout 5s my_command
|
||||
|
||||
# Wait for condition
|
||||
wait_for_condition "test -f $TEST_DIR/ready" 10 1
|
||||
|
||||
# Debug test failure
|
||||
debug_on_failure
|
||||
```
|
||||
|
||||
## Module Integration
|
||||
|
||||
### Adding Tests to a New Module
|
||||
|
||||
1. Create a `test/` directory in your module:
|
||||
```bash
|
||||
mkdir apps/my-module/test
|
||||
```
|
||||
|
||||
2. Create test files (ending in `.bats`):
|
||||
```bash
|
||||
touch apps/my-module/test/test_my_feature.bats
|
||||
```
|
||||
|
||||
3. Write your tests using the framework (see examples above)
|
||||
|
||||
### Running Tests
|
||||
|
||||
From your module directory:
|
||||
```bash
|
||||
../test-framework/run-tests.sh --dir .
|
||||
```
|
||||
|
||||
From the test framework:
|
||||
```bash
|
||||
./run-tests.sh my-module
|
||||
```
|
||||
|
||||
From project root:
|
||||
```bash
|
||||
apps/test-framework/run-tests.sh my-module
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
For continuous integration, use TAP output:
|
||||
|
||||
```bash
|
||||
# In your CI script
|
||||
cd apps/test-framework
|
||||
./run-tests.sh --all --tap > test-results.tap
|
||||
|
||||
# Or from project root
|
||||
apps/test-framework/run-tests.sh --all --tap > test-results.tap
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
All functionality is available through the single `run-tests.sh` script:
|
||||
|
||||
### Basic Test Execution
|
||||
- `./run-tests.sh --all` - Run all tests in all modules
|
||||
- `./run-tests.sh <module>` - Run tests for specific module
|
||||
- `./run-tests.sh --dir <path>` - Run tests in specific directory
|
||||
- `./run-tests.sh --list` - List available modules
|
||||
- `./run-tests.sh --count` - Show test count
|
||||
|
||||
### Output Control
|
||||
- `./run-tests.sh --verbose` - Verbose output with debug info
|
||||
- `./run-tests.sh --tap` - TAP output for CI/CD
|
||||
- `./run-tests.sh --debug` - Debug mode with failure details
|
||||
- `./run-tests.sh --pretty` - Pretty output (default)
|
||||
|
||||
### Test Filtering
|
||||
- `./run-tests.sh --filter <pattern>` - Run tests matching pattern
|
||||
- `./run-tests.sh <module> --filter <pattern>` - Filter within module
|
||||
|
||||
### Utility Functions
|
||||
- `./run-tests.sh --help` - Show help message
|
||||
- Install BATS: Use your system package manager (`apt install bats`, `brew install bats-core`, etc.)
|
||||
|
||||
|
||||
### Direct Script Usage
|
||||
|
||||
## Examples
|
||||
|
||||
### Running Specific Tests
|
||||
```bash
|
||||
# Run only starter-related tests
|
||||
./run-tests.sh --filter starter
|
||||
|
||||
# Run only tests in startup-scripts module
|
||||
./run-tests.sh startup-scripts
|
||||
|
||||
# Run all tests with verbose output
|
||||
./run-tests.sh --all --verbose
|
||||
|
||||
# Run tests in specific directory with debug
|
||||
./run-tests.sh --dir apps/docker --debug
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
```bash
|
||||
# While developing, run tests frequently from module directory
|
||||
cd apps/my-module
|
||||
../test-framework/run-tests.sh --dir .
|
||||
|
||||
# Debug failing tests
|
||||
../test-framework/run-tests.sh --dir . --debug --verbose
|
||||
|
||||
# Run specific test pattern
|
||||
../test-framework/run-tests.sh --dir . --filter my-feature
|
||||
|
||||
# From project root - run all tests
|
||||
apps/test-framework/run-tests.sh --all
|
||||
|
||||
# Quick test count check
|
||||
apps/test-framework/run-tests.sh --count
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **No Boilerplate**: Minimal setup required for new test modules
|
||||
2. **Consistent Environment**: All tests use the same setup/teardown
|
||||
3. **Reusable Utilities**: Common functions available across all tests
|
||||
4. **Centralized Management**: Single place to update test infrastructure
|
||||
5. **Flexible Execution**: Run tests for one module, multiple modules, or all modules
|
||||
6. **CI/CD Ready**: TAP output format supported
|
||||
7. **Easy Debugging**: Built-in debug helpers and verbose output
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [BATS (Bash Automated Testing System)](https://github.com/bats-core/bats-core)
|
||||
- Standard Unix utilities (find, grep, timeout, etc.)
|
||||
|
||||
Install BATS with your system package manager:
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update && sudo apt install bats
|
||||
|
||||
# Fedora/RHEL
|
||||
sudo dnf install bats
|
||||
|
||||
# macOS
|
||||
brew install bats-core
|
||||
|
||||
# Arch Linux
|
||||
sudo pacman -S bats
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
When adding new test utilities:
|
||||
|
||||
1. Add common functions to `helpers/test_common.sh`
|
||||
2. Add BATS-specific helpers to `bats_libs/acore-support.bash`
|
||||
3. Add custom assertions to `bats_libs/acore-assert.bash`
|
||||
4. Update this README with new functionality
|
||||
Reference in New Issue
Block a user