API Health Check (api-health-check)

Summary

Configurable HTTP health check for a single API endpoint.

Classification

• Category: API_HEALTH
• Plugin id: api-health-check
• Version: 1.0.0
• Target types: API
• Weight class: LIGHT
• Risk level: not set on plugin object
• Browser required: No (HTTP / Node / other — see source)
• Tier / group: Tier 4 — API

Schedule

• scheduleHints: { defaultInterval: '0 */1 * * *', priority: 9 }
• Prerequisites: None declared on this plugin.

Configurable inputs

Public keys are derived from inputSchema: z.object({ ... }) (underscore-prefixed keys are runtime-only and omitted here).

Field	Notes
url	Optional override; defaults to target.url.
method	GET, POST, PUT, PATCH, DELETE, or HEAD (default GET).
headers	Extra request headers merged on top of the TesteBot user agent.
body	Request body string; sent only when the method is not GET or HEAD.
auth	Optional inline auth object (bearer, basic, or api-key with token / username / password / headerName).
expectedStatus	HTTP status code that counts as healthy (default 200).
expectedBody	Optional substring that must appear in the response body.
timeout	Per-request timeout in ms (default 10000).

Runtime / injected config

• None documented beyond standard worker context (target, config, logger, reportProgress). Underscore-prefixed keys are internal.

Checks that produce findings

These checks run inside this plugin during a single test run. They are not separate tests in the database — each becomes a Finding linked to the Run for api-health-check.

Check	Typical severity	Why
API request timed out or failed	WARNING	The endpoint did not respond in time or the connection failed — consumers, monitors, and integrations that depend on this API will see the same failure.
Unexpected HTTP status (vs expectedStatus)	WARNING	A non-expected status usually means the service is degraded, misconfigured, or returning errors that upstream callers will hit in production.
Response body missing expected content	WARNING	Status alone can look healthy while the payload is wrong (empty JSON, error HTML, stale deployment); substring checks catch silent logic regressions.

How each check works

1. Resolve config — Uses config.url or falls back to target.url. Builds headers with TesteBot/1.0 user agent plus any config.headers.
2. Auth — If auth is set: bearer → Authorization: Bearer …; basic → Base64 basic auth; api-key → token in headerName (default X-API-Key). Credentials come from test config, not the secrets vault.
3. SSRF guard — assertSafeUrl(url) runs before the request.
4. Single request — One fetch with redirect: 'follow', AbortSignal.timeout(timeout), and optional body. Reads the full response text.
5. Timeout / network failure — Any thrown error becomes a WARNING finding (api:timeout:…) with elapsed ms and error message; run status warning, score 35.
6. Status check — If response.status !== expectedStatus, emits a WARNING finding with the first 500 chars of body in evidence.
7. Body check — When expectedBody is configured, emits WARNING if responseBody.includes(expectedBody) is false (plain substring match, not JSON parsing).
8. Score & status — No findings → passed, score 100. Any finding → warning, score 50. The code checks for CRITICAL findings, but this plugin never emits them.

Caveats and concerns

• Single probe — One request per run; transient blips are not retried (unlike the uptime heartbeat confirmation retries).
• Substring body match — expectedBody uses naive includes(); whitespace, JSON field order, or encoding differences can cause false positives.
• Follows redirects — Status reflects the final URL after redirects, not the first hop.
• Inline auth in config — Tokens and passwords in auth or headers are stored in test configuration; prefer the secrets vault pattern used by browser flow tests for sensitive credentials.
• No response-time finding — Elapsed ms is recorded in metrics only; slow but “200 OK” responses pass unless you add a separate latency test (api-latency-benchmark).
• Uses raw fetch — Not fetchTarget() from shared HTTP utils, though SSRF protection and user agent are still applied manually.

Source

packages/test-plugins/src/plugins/api-health-check.ts