librefang-registry/hands/apitester/HAND.toml

id = "apitester"
version = "1.0.0"
name = "API Tester Hand"
description = "Autonomous API testing agent — endpoint discovery, request validation, load testing, and regression detection"

category = "development"
icon = "🔌"

tools = [
  "shell_exec",
  "file_read",
  "file_write",
  "file_list",
  "web_fetch",
  "web_search",
  "memory_store",
  "memory_recall",
  "schedule_create",
  "schedule_list",
  "schedule_delete",
  "knowledge_add_entity",
  "knowledge_add_relation",
  "knowledge_query",
  "event_publish",
]

[routing]
aliases = [
  "api test",
  "endpoint test",
  "load test",
  "regression test",
  "api discovery",
  "test api",
  "api testing",
  "api validation",
  "test endpoint",
]
weak_aliases = [
  "api debug",
  "request validation",
  "swagger",
  "openapi",
  "postman",
  "stress test",
  "http test",
]

# ─── Configurable settings ───────────────────────────────────────────────────

[[settings]]
key = "base_url"
label = "Base URL"
description = "Base URL of the API to test (e.g. https://api.example.com/v1)"
setting_type = "text"
default = ""

[[settings]]
key = "auth_type"
label = "Authentication Type"
description = "How to authenticate API requests"
setting_type = "select"
default = "none"

[[settings.options]]
value = "none"
label = "No Authentication"

[[settings.options]]
value = "bearer"
label = "Bearer Token"

[[settings.options]]
value = "api_key_header"
label = "API Key (Header)"

[[settings.options]]
value = "basic"
label = "Basic Auth"

[[settings]]
key = "auth_token"
label = "Auth Token / API Key"
description = "Bearer token, API key, or base64-encoded credentials depending on auth type"
setting_type = "text"
default = ""

[[settings]]
key = "test_mode"
label = "Test Mode"
description = "What type of API testing to perform"
setting_type = "select"
default = "functional"

[[settings.options]]
value = "functional"
label = "Functional (validate endpoints)"

[[settings.options]]
value = "regression"
label = "Regression (detect changes)"

[[settings.options]]
value = "load"
label = "Load (stress testing)"

[[settings.options]]
value = "security"
label = "Security (vulnerability scan)"

[[settings.options]]
value = "comprehensive"
label = "Comprehensive (all of the above)"

[[settings]]
key = "openapi_spec_url"
label = "OpenAPI Spec URL"
description = "URL to the OpenAPI/Swagger spec (e.g. /openapi.json). Leave empty for auto-discovery."
setting_type = "text"
default = ""

[[settings]]
key = "auto_schedule"
label = "Auto Schedule"
description = "Automatically run tests on a schedule"
setting_type = "toggle"
default = "false"

[[settings]]
key = "test_frequency"
label = "Test Frequency"
description = "How often to run scheduled tests"
setting_type = "select"
default = "daily"

[[settings.options]]
value = "hourly"
label = "Every hour"

[[settings.options]]
value = "daily"
label = "Once per day"

[[settings.options]]
value = "weekly"
label = "Once per week"

[[settings]]
key = "fail_on_error"
label = "Strict Mode"
description = "Treat any non-2xx response as a failure (vs allowing expected error codes)"
setting_type = "toggle"
default = "false"

[[settings]]
key = "approval_mode"
label = "Approval Mode"
description = "Write test plans and destructive requests to a queue file for your review instead of executing directly"
setting_type = "toggle"
default = "true"

# ─── Agent configuration ─────────────────────────────────────────────────────

[agent]
name = "apitester-hand"
description = "AI API tester — discovers endpoints, validates responses, runs load tests, detects regressions, and generates comprehensive test reports"
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 16384
temperature = 0.4
max_iterations = 60
system_prompt = """You are API Tester Hand — an autonomous API testing agent that discovers endpoints, validates responses, runs load tests, detects regressions, and produces detailed test reports.

## Phase 0 — Environment Setup (ALWAYS DO THIS FIRST)

Detect the operating system:
```
python -c "import platform; print(platform.system())"
```

Verify connectivity to the target API:
```
curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/health"
```
If the base URL is not reachable, alert the user.

Load context:
1. memory_recall `apitester_hand_state` — load previous test results and baselines
2. Read **User Configuration** for base_url, auth_type, auth_token, test_mode, etc.
3. file_read `api_test_baseline.json` if it exists — previous test baselines
4. knowledge_query for previously discovered endpoints and schemas

Set up authentication headers based on `auth_type`:
- none: no auth header
- bearer: `-H "Authorization: Bearer $AUTH_TOKEN"`
- api_key_header: `-H "X-API-Key: $AUTH_TOKEN"`
- basic: `-H "Authorization: Basic $AUTH_TOKEN"`

---

## Phase 1 — API Discovery

Discover available endpoints:

If `openapi_spec_url` is provided:
```
curl -s -H "$AUTH_HEADER" "$BASE_URL$OPENAPI_SPEC_URL" -o openapi_spec.json
```
Parse the OpenAPI/Swagger spec to extract all endpoints, methods, parameters, and schemas.

If no spec is available, try common locations:
```
curl -s "$BASE_URL/openapi.json" -o openapi_spec.json
curl -s "$BASE_URL/swagger.json" -o swagger_spec.json
curl -s "$BASE_URL/api-docs" -o api_docs.json
```

If no spec found, probe common endpoints:
- /health, /api/health
- /api/v1, /api/v2
- /status, /version
- /docs, /redoc

Store discovered endpoints in the knowledge graph.

---

## Phase 2 — Functional Testing

**Check `approval_mode` setting before executing any tests.**

If `approval_mode` is ENABLED:
1. Build the full test plan (all endpoints, methods, payloads) and write it to `apitester_queue.json`:
   ```json
   [{"id": "t_001", "endpoint": "/api/users", "method": "POST", "payload": {...}, "type": "functional", "status": "pending"}]
   ```
2. Write a human-readable `apitester_queue_preview.md` for easy review
3. Only execute **safe read-only requests** (GET, HEAD, OPTIONS) directly
4. Do NOT execute any write requests (POST, PUT, PATCH, DELETE) — queue them for approval

If `approval_mode` is DISABLED:
Execute all tests directly.

For each discovered endpoint:

1. **Method validation**: Send requests with correct and incorrect HTTP methods
2. **Parameter testing**: Test required params, optional params, missing params, invalid types
3. **Response validation**:
   - Status code matches expected (200, 201, 204, etc.)
   - Response body matches schema (if OpenAPI spec available)
   - Required fields present
   - Data types correct
   - Pagination works correctly
4. **Error handling**: Test error responses (400, 401, 403, 404, 422, 500)
5. **Edge cases**: Empty payloads, oversized payloads, special characters, null values

For each test:
```
curl -s -w "\\n%{http_code} %{time_total}" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -X METHOD "$BASE_URL/endpoint" \
  -d '{"field": "value"}' \
  -o response.json
```

Record: endpoint, method, status_code, response_time, pass/fail, details.

Rate each test result confidence:
- **Definitive**: Clear pass (2xx with valid schema) or clear fail (5xx, schema mismatch) — report as-is
- **Ambiguous**: 4xx that might be expected (403 on admin endpoint) or slow response that might be transient — re-run once before reporting
- **Flaky**: Different results on consecutive runs — mark as "FLAKY" in report, do not count as pass or fail

---

## Phase 3 — Regression Testing

Compare current results against stored baselines:

1. Load baseline from `api_test_baseline.json`
2. For each endpoint, compare:
   - Response schema changes (new fields, removed fields, type changes)
   - Status code changes
   - Response time degradation (>20% slower = warning, >50% = failure)
   - New error codes
3. Flag any regressions with severity level

If no baseline exists, current results become the new baseline.

---

## Phase 4 — Load Testing

If `test_mode` includes load testing:

If `approval_mode` is ENABLED:
- Write the load test plan to `apitester_queue.json` (target URL, concurrency levels, expected duration)
- Do NOT execute load tests — queue them for user approval
- Alert the user that load tests can impact production systems

If `approval_mode` is DISABLED:
Execute load tests directly.

Use curl in a loop or shell-based load generator:
```
for i in $(seq 1 100); do
  curl -s -o /dev/null -w "%{http_code} %{time_total}\\n" \
    -H "$AUTH_HEADER" \
    "$BASE_URL/endpoint" &
done
wait
```

Measure:
- Average response time
- P95 and P99 response times
- Error rate under load
- Throughput (requests per second)
- Degradation curve (response time vs concurrency)

Start with 10 concurrent, then 50, then 100 requests.

**Backoff strategy:**
- Check `Retry-After` and `X-RateLimit-Remaining` response headers after each batch
- If the API returns HTTP 429 (Too Many Requests), stop load testing immediately and wait for the Retry-After period
- If error rate exceeds 20% at any concurrency level, pause for 30 seconds before continuing
- If error rate exceeds 50%, terminate the load test and report current results
- Never exceed the API's documented rate limits during load testing

---

## Phase 5 — Security Testing

If `test_mode` includes security:

If `approval_mode` is ENABLED:
- Write the security test plan to `apitester_queue.json` (injection payloads, auth bypass attempts, etc.)
- Do NOT execute security tests — queue them for user approval
- Security tests can trigger alerts and block accounts — always require review

If `approval_mode` is DISABLED:
Execute security tests directly.

1. **Authentication tests**: Missing auth, invalid auth, expired tokens
2. **Authorization tests**: Access resources of other users, escalate privileges
3. **Input injection**: SQL injection, XSS, command injection in parameters
4. **Headers**: Missing security headers (CORS, HSTS, X-Frame-Options)
5. **Rate limiting**: Verify rate limits are enforced
6. **Data exposure**: Check for sensitive data in responses (passwords, tokens, PII)

IMPORTANT: Only test APIs you have permission to test. Never perform destructive tests without explicit confirmation.

### Test Session Exit Criteria
Stop testing when ANY of these conditions is met:
1. **Target down**: Base URL returns 5xx on 3+ consecutive health checks — skip remaining tests, generate partial report
2. **Auth expired**: API returns 401 on previously-working endpoints — alert user about token/key refresh
3. **Rate limited**: Target returns 429 — stop all tests, wait for Retry-After, then resume or report
4. **Critical failure**: A destructive endpoint (DELETE/DROP) returned 2xx unexpectedly — STOP IMMEDIATELY and alert user
5. **Iteration cap**: 200+ individual test requests in a single session — generate report with current results

---

## Phase 6 — Report Generation

Generate a comprehensive test report:

```markdown
# API Test Report
**Target**: $BASE_URL
**Date**: YYYY-MM-DD HH:MM
**Mode**: $TEST_MODE
**Total Endpoints**: N
**Tests Run**: N
**Passed**: N | **Failed**: N | **Warnings**: N

## Summary
[Overall health assessment]

## Endpoint Results
| Endpoint | Method | Status | Response Time | Result |
|----------|--------|--------|---------------|--------|

## Failures (if any)
[Detailed failure descriptions]

## Regressions (if any)
[Changes from baseline]

## Performance
[Response time distribution]

## Recommendations
[Actionable improvements]
```

Save report to: `api_test_report_YYYY-MM-DD.md`
Save baseline to: `api_test_baseline.json`

---

## Phase 7 — State Persistence

1. memory_store `apitester_hand_state`: tests_run, endpoints_discovered, last_test_date
2. Update dashboard stats:
   - memory_store `apitester_hand_tests_run` — total tests executed
   - memory_store `apitester_hand_endpoints_tested` — unique endpoints tested
   - memory_store `apitester_hand_failures_found` — total failures detected
   - memory_store `apitester_hand_avg_response_time` — average response time across all endpoints

If `auto_schedule` is enabled, create scheduled runs via schedule_create.

---

## Guidelines

- NEVER test APIs without the user's permission or authorization
- NEVER perform destructive operations (DELETE, data modification) without explicit confirmation
- NEVER send real user data or credentials in test payloads
- NEVER exceed rate limits intentionally (respect the API's constraints)
- Log all test results for auditability
- Treat any sensitive data in responses as a security finding
- If an endpoint returns 5xx repeatedly, back off and report the issue
- Use realistic but fake test data (e.g. "test@example.com", not real emails)
- Always include request/response details in failure reports
- In approval_mode (default), ALWAYS write to queue — NEVER execute write requests, load tests, or security tests without user review
"""

[dashboard]
[[dashboard.metrics]]
label = "Tests Run"
memory_key = "apitester_hand_tests_run"
format = "number"

[[dashboard.metrics]]
label = "Endpoints Tested"
memory_key = "apitester_hand_endpoints_tested"
format = "number"

[[dashboard.metrics]]
label = "Failures Found"
memory_key = "apitester_hand_failures_found"
format = "number"

[[dashboard.metrics]]
label = "Avg Response Time"
memory_key = "apitester_hand_avg_response_time"
format = "duration"

[[dashboard.metrics]]
label = "Pass Rate"
memory_key = "apitester_hand_pass_rate"
format = "percentage"

# ─── Token & Performance Metadata ─────────────────────────────────────────────

[metadata]
frequency = "continuous"
token_consumption = "medium"
default_active = false
activation_warning = "API Tester hand runs continuously, consuming tokens. Use on-demand for specific tests."

# ─── Internationalization (optional) ─────────────────────────────────────────
# All i18n sections are optional. Without them, the English values above are used.
# To localize, add [i18n.LANG] sections (e.g. zh, ja, ko, es, fr, de).
# Settings translations are also optional — omit to keep English labels.

# ─── Chinese (简体中文) ────────────────────────────────────────────────────

[i18n.zh]
name = "API 测试 Hand"
description = "自主 API 测试智能体——端点发现、请求验证、负载测试和回归检测"
category = "开发"

[i18n.zh.settings.base_url]
label = "基础 URL"
description = "待测试 API 的基础 URL（例如 https://api.example.com/v1）"

[i18n.zh.settings.auth_type]
label = "认证方式"
description = "API 请求的认证方式"

[i18n.zh.settings.auth_token]
label = "认证令牌 / API 密钥"
description = "Bearer 令牌、API 密钥或 Base64 编码的凭据，取决于认证方式"

[i18n.zh.settings.test_mode]
label = "测试模式"
description = "执行的 API 测试类型"

[i18n.zh.settings.openapi_spec_url]
label = "OpenAPI 规范 URL"
description = "OpenAPI/Swagger 规范的 URL（例如 /openapi.json）。留空则自动发现。"

[i18n.zh.settings.auto_schedule]
label = "自动定时"
description = "按计划自动运行测试"

[i18n.zh.settings.test_frequency]
label = "测试频率"
description = "定时测试的执行频率"

[i18n.zh.settings.fail_on_error]
label = "严格模式"
description = "将任何非 2xx 响应视为失败（而非允许预期的错误码）"

[i18n.zh.settings.approval_mode]
label = "审批模式"
description = "将测试计划和破坏性请求写入队列文件供审核，而非直接执行"

# ─── Japanese (日本語) ────────────────────────────────────────────────────

[i18n.ja]
name = "APIテスト Hand"
description = "自律型APIテストエージェント——エンドポイント検出、リクエスト検証、負荷テスト、リグレッション検出"
category = "開発"

[i18n.ja.settings.base_url]
label = "ベースURL"
description = "テスト対象APIのベースURL（例: https://api.example.com/v1）"

[i18n.ja.settings.auth_type]
label = "認証方式"
description = "APIリクエストの認証方法"

[i18n.ja.settings.auth_token]
label = "認証トークン / APIキー"
description = "認証方式に応じたBearerトークン、APIキー、またはBase64エンコードされた資格情報"

[i18n.ja.settings.test_mode]
label = "テストモード"
description = "実行するAPIテストの種類"

[i18n.ja.settings.openapi_spec_url]
label = "OpenAPI仕様URL"
description = "OpenAPI/Swagger仕様のURL（例: /openapi.json）。空欄にすると自動検出します。"

[i18n.ja.settings.auto_schedule]
label = "自動スケジュール"
description = "スケジュールに基づいてテストを自動実行する"

[i18n.ja.settings.test_frequency]
label = "テスト頻度"
description = "定期テストの実行頻度"

[i18n.ja.settings.fail_on_error]
label = "厳格モード"
description = "2xx以外のレスポンスをすべて失敗として扱う（期待されるエラーコードを許容しない）"

[i18n.ja.settings.approval_mode]
label = "承認モード"
description = "テスト計画や破壊的リクエストを直接実行せず、レビュー用のキューファイルに書き出す"

# ─── Spanish (Español) ────────────────────────────────────────────────────

[i18n.es]
name = "Hand de Pruebas API"
description = "Agente autónomo de pruebas de API — descubrimiento de endpoints, validación de peticiones, pruebas de carga y detección de regresiones"
category = "Desarrollo"

[i18n.es.settings.base_url]
label = "URL base"
description = "URL base de la API a probar (ej. https://api.example.com/v1)"

[i18n.es.settings.auth_type]
label = "Tipo de autenticación"
description = "Cómo autenticar las peticiones a la API"

[i18n.es.settings.auth_token]
label = "Token de autenticación / Clave API"
description = "Token Bearer, clave API o credenciales codificadas en Base64 según el tipo de autenticación"

[i18n.es.settings.test_mode]
label = "Modo de prueba"
description = "Qué tipo de pruebas de API realizar"

[i18n.es.settings.openapi_spec_url]
label = "URL de especificación OpenAPI"
description = "URL de la especificación OpenAPI/Swagger (ej. /openapi.json). Dejar vacío para descubrimiento automático."

[i18n.es.settings.auto_schedule]
label = "Programación automática"
description = "Ejecutar pruebas automáticamente según un calendario"

[i18n.es.settings.test_frequency]
label = "Frecuencia de pruebas"
description = "Con qué frecuencia ejecutar las pruebas programadas"

[i18n.es.settings.fail_on_error]
label = "Modo estricto"
description = "Tratar cualquier respuesta no 2xx como un fallo (en lugar de permitir códigos de error esperados)"

[i18n.es.settings.approval_mode]
label = "Modo de aprobación"
description = "Escribir planes de prueba y peticiones destructivas en un archivo de cola para revisión en lugar de ejecutarlos directamente"

# ─── French (Français) ────────────────────────────────────────────────────

[i18n.fr]
name = "Hand de Test API"
description = "Agent autonome de test d'API — découverte de points de terminaison, validation de requêtes, tests de charge et détection de régression"
category = "Développement"

[i18n.fr.settings.base_url]
label = "URL de base"
description = "URL de base de l'API à tester (ex. https://api.example.com/v1)"

[i18n.fr.settings.auth_type]
label = "Type d'authentification"
description = "Méthode d'authentification des requêtes API"

[i18n.fr.settings.auth_token]
label = "Jeton d'authentification / Clé API"
description = "Jeton Bearer, clé API ou identifiants encodés en Base64 selon le type d'authentification"

[i18n.fr.settings.test_mode]
label = "Mode de test"
description = "Type de tests API à exécuter"

[i18n.fr.settings.openapi_spec_url]
label = "URL de spécification OpenAPI"
description = "URL de la spécification OpenAPI/Swagger (ex. /openapi.json). Laisser vide pour la découverte automatique."

[i18n.fr.settings.auto_schedule]
label = "Planification automatique"
description = "Exécuter automatiquement les tests selon un calendrier"

[i18n.fr.settings.test_frequency]
label = "Fréquence des tests"
description = "Fréquence d'exécution des tests planifiés"

[i18n.fr.settings.fail_on_error]
label = "Mode strict"
description = "Traiter toute réponse non 2xx comme un échec (au lieu d'autoriser les codes d'erreur attendus)"

[i18n.fr.settings.approval_mode]
label = "Mode d'approbation"
description = "Écrire les plans de test et requêtes destructives dans un fichier d'attente pour révision au lieu de les exécuter directement"

# ─── German (Deutsch) ────────────────────────────────────────────────────

[i18n.de]
name = "API-Test-Hand"
description = "Autonomer API-Test-Agent — Endpunkt-Erkennung, Anfrage-Validierung, Lasttests und Regressionserkennung"
category = "Entwicklung"

[i18n.de.settings.base_url]
label = "Basis-URL"
description = "Basis-URL der zu testenden API (z.B. https://api.example.com/v1)"

[i18n.de.settings.auth_type]
label = "Authentifizierungstyp"
description = "Authentifizierungsmethode für API-Anfragen"

[i18n.de.settings.auth_token]
label = "Authentifizierungstoken / API-Schlüssel"
description = "Bearer-Token, API-Schlüssel oder Base64-kodierte Anmeldedaten je nach Authentifizierungstyp"

[i18n.de.settings.test_mode]
label = "Testmodus"
description = "Art der durchzuführenden API-Tests"

[i18n.de.settings.openapi_spec_url]
label = "OpenAPI-Spezifikations-URL"
description = "URL der OpenAPI/Swagger-Spezifikation (z.B. /openapi.json). Leer lassen für automatische Erkennung."

[i18n.de.settings.auto_schedule]
label = "Automatische Planung"
description = "Tests automatisch nach Zeitplan ausführen"

[i18n.de.settings.test_frequency]
label = "Testhäufigkeit"
description = "Ausführungshäufigkeit der geplanten Tests"

[i18n.de.settings.fail_on_error]
label = "Strikter Modus"
description = "Jede Nicht-2xx-Antwort als Fehler behandeln (anstatt erwartete Fehlercodes zuzulassen)"

[i18n.de.settings.approval_mode]
label = "Genehmigungsmodus"
description = "Testpläne und destruktive Anfragen in eine Warteschlange zur Überprüfung schreiben, anstatt sie direkt auszuführen"

# ─── Korean (한국어) ────────────────────────────────────────────────────

[i18n.ko]
name = "API 테스트 Hand"
description = "자율 API 테스트 에이전트 — 엔드포인트 탐색, 요청 검증, 부하 테스트 및 회귀 감지"
category = "개발"

[i18n.ko.settings.base_url]
label = "기본 URL"
description = "테스트할 API의 기본 URL (예: https://api.example.com/v1)"

[i18n.ko.settings.auth_type]
label = "인증 방식"
description = "API 요청의 인증 방식"

[i18n.ko.settings.auth_token]
label = "인증 토큰 / API 키"
description = "인증 방식에 따른 Bearer 토큰, API 키 또는 Base64 인코딩 자격 증명"

[i18n.ko.settings.test_mode]
label = "테스트 모드"
description = "수행할 API 테스트 유형"

[i18n.ko.settings.openapi_spec_url]
label = "OpenAPI 스펙 URL"
description = "OpenAPI/Swagger 스펙의 URL (예: /openapi.json). 비워두면 자동 탐색합니다."

[i18n.ko.settings.auto_schedule]
label = "자동 일정"
description = "일정에 따라 자동으로 테스트 실행"

[i18n.ko.settings.test_frequency]
label = "테스트 빈도"
description = "정기 테스트 실행 주기"

[i18n.ko.settings.fail_on_error]
label = "엄격 모드"
description = "모든 비-2xx 응답을 실패로 처리 (예상된 오류 코드 허용 안 함)"

[i18n.ko.settings.approval_mode]
label = "승인 모드"
description = "테스트 계획 및 파괴적 요청을 직접 실행하지 않고 큐 파일에 기록하여 검토"