Hiclaw Test
Testing & Qualityhiclaw-testHiclaw Test is an Agent Skill for testing & quality published in the agentscope-ai/AgentTeams repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Complete HiClaw test cycle including installation, uninstallation, running tests, and exporting debug logs for analysis. Use for (1) verifying HiClaw functionality (2) CI/CD test validation (3) issue diagnosis and debugging (4) pre-merge testing. Trigger words: test HiClaw, run HiClaw tests, hiclaw test, make test, verify HiClaw installation.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/agentscope-ai/AgentTeams/blob/HEAD/tests/skills/hiclaw-test/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/hiclaw-test, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
HiClaw Test Cycle
Complete HiClaw testing workflow including installation verification, functional tests, and issue diagnosis.
Quick Start
# 1. Clone/update code
git clone https://github.com/alibaba/hiclaw.git && cd hiclaw
# 2. Create config file (first time)
cp hiclaw-manager.env.example ~/hiclaw-manager.env
# Edit ~/hiclaw-manager.env and set HICLAW_LLM_API_KEY, etc.
# 3. Run full test
set -a && . ~/hiclaw-manager.env && set +a && make test
Full Test Cycle
Step 1: Prepare Environment
# Clone latest code
git clone https://github.com/alibaba/hiclaw.git
cd hiclaw
# Check if config file exists
ls ~/hiclaw-manager.env
Step 2: Run Full Test
# Load config and run tests (automatically executes install → test → uninstall)
set -a && . ~/hiclaw-manager.env && set +a && make test
Test cases:
- test-01: Manager startup health check
- test-02: Create Worker Alice
- test-03: Assign task to Worker
- test-04: Human intervention with additional instructions
- test-05: Heartbeat query mechanism
- test-06: Multi-Worker collaboration
- test-08~14: GitHub/MCP related tests (requires HICLAW_GITHUB_TOKEN)
Step 3: Individual Install/Uninstall
# Install only
set -a && . ~/hiclaw-manager.env && set +a && HICLAW_YOLO=1 make install
# Uninstall only
make uninstall
# Run tests using existing installation (skip reinstall)
set -a && . ~/hiclaw-manager.env && set +a
./tests/run-all-tests.sh --skip-build --use-existing
Export Debug Logs
When tests fail or hang, use hiclaw-debug.sh to export logs:
# In hiclaw repository directory
./tests/skills/hiclaw-test/scripts/hiclaw-debug.sh all
# Analyze hang issues only
./tests/skills/hiclaw-test/scripts/hiclaw-debug.sh analyze
Manual Log Export
# Manager container logs
docker logs --tail 100 hiclaw-manager 2>&1
# Manager Agent logs
docker exec hiclaw-manager tail -100 /var/log/hiclaw/manager-agent.log
# Manager Agent error logs
docker exec hiclaw-manager tail -50 /var/log/hiclaw/manager-agent-error.log
# Worker container logs
docker ps --filter "name=hiclaw-worker" --format "table {{.Names}}\t{{.Status}}"
docker logs --tail 50 hiclaw-worker-alice 2>&1
# Test output files
ls tests/output/
cat tests/output/metrics-*.json
Common Issue Diagnosis
1. Test Hangs
Use hiclaw-debug.sh to analyze PHASE_DONE messages for mention issues:
# Run in HiClaw repository directory
./tests/skills/hiclaw-test/scripts/hiclaw-debug.sh analyze 1h
# Or use export-debug-log.py directly
python3 scripts/export-debug-log.py --range 1h
hiclaw-debug.sh checks if Worker's PHASE_DONE messages include @manager:
- ✅ Includes
@manager→ Message will be processed by Manager - ⚠️ Missing
@manager→ Message ignored, may cause hang
Common cause: In multi-phase collaboration projects, Worker doesn't @mention Manager after completing a phase
Solution: Fixed in v1.0.8+, Manager adds Multi-Phase Collaboration Protocol to task specs
2. Worker Not Responding
# Check if Worker container is running
docker ps --filter "name=hiclaw-worker"
# Check Worker Agent process
docker exec hiclaw-worker-alice ps aux | grep openclaw
3. LLM Call Failures
# Check error logs
docker exec hiclaw-manager grep -i "error\|fail" /var/log/hiclaw/manager-agent-error.log
4. Test Timeout
Some tests (like test-14-git-collab) take longer, you can increase timeout:
# Run test script directly with custom timeout
timeout 1200 ./tests/run-all-tests.sh --skip-build --use-existing
Test Results Interpretation
Successful Test
========================================
Test Summary
========================================
Total: 12
[32mPassed: 12[0m
[31mFailed: 0[0m
========================================
Skipped Tests
[36m[TEST INFO][0m SKIP: No GitHub token configured
Requires HICLAW_GITHUB_TOKEN environment variable.
Metrics Files
Each test generates metrics-XX-testname.json containing:
- LLM call count
- Token usage
- Execution time
- Cache hit statistics
Cleanup Environment
# Full uninstall
make uninstall
# Delete all Worker containers
docker rm -f $(docker ps -aq --filter "name=hiclaw-worker")
# Delete test code
rm -rf ./hiclaw
References
- tests/README.md - Test framework documentation
- install/README.md - Installation guide
- references/troubleshooting.md - Detailed troubleshooting