# API Frontend Coverage Methodology

Apifrontend tracks code coverage across three test tiers following the same defense-in-depth testing pyramid as kubernaut. Coverage is reported automatically on every pull request via CI.

---

## Test Tiers

### Unit-Testable

Pure business logic that can be tested in isolation with no external dependencies (no K8s API, no containers, no network I/O).

**Includes**: config, validate, audit, metrics, security, httputil, requestid, logging, prometheus, tools (business logic), agent (prompt, RBAC config), session (state machine), severity (triage pipeline), ratelimit, resilience (circuit breaker config), streaming (SSE framing), auth (RBAC helpers).

**Excludes**: handler (MCP bridge/HTTP server), ka (KA REST client), ds (DS OgenClient), launcher (server bootstrap), controller (envtest reconcilers), tlswiring (real TLS cert loading), auth middleware (TokenReview/SAR).

### Integration-Testable

Code that requires real or simulated external dependencies (envtest K8s API, Podman containers for DS/KA, TCP proxy for resilience).

**Includes**: handler (MCP bridge dispatch), ka (REST client), ds (OgenClient), launcher, controller, tlswiring, auth (dynamic impersonation, TokenReview middleware).

### E2E

Full end-to-end user journeys running against a Kind cluster with AF deployed as a pod, plus Dex for OIDC.

### All Tiers (Merged)

Line-by-line deduplication across all three tiers. A statement covered by **any** tier counts once. This is the most accurate measure of overall test coverage.

---

## Quality Targets

| Tier | Target |
|------|--------|
| Unit-Testable | >= 80% |
| Integration-Testable | >= 80% |
| All Tiers (Merged) | >= 80% |

---

## How Coverage Is Reported

### On Every Pull Request

The CI pipeline runs `make coverage-report-markdown` and posts a coverage table as a PR comment. This is the **source of truth** for current coverage numbers.

### Locally

```bash
# Run unit tests (generates coverage_unit_apifrontend.out)
make test-unit

# Run IT tests (generates coverage_integration_apifrontend.out)
make test-integration-containers

# Generate coverage report (terminal table with per-package breakdown)
make coverage-report

# Generate coverage report (markdown table for PR comments)
make coverage-report-markdown

# Generate coverage report (JSON for CI tooling)
make coverage-report-json

# Generate HTML coverage report
make coverage-html

# Per-function coverage detail
make coverage-func
```

---

## How Merging Works

Coverage profiles from each tier use the same `--coverpkg` scope (all `internal/` packages). The reporting script (`scripts/coverage/coverage_report.py`) applies **post-processing filters** to classify each statement:

1. **Unit-Testable scope**: Statements from packages classified as unit-testable (pure logic, no I/O).
2. **Integration-Testable scope**: Statements from packages classified as integration-only (requires envtest, containers, or network).
3. **All Code**: All statements from `internal/` (minus generated code).

For **All Tiers** merged coverage, the script takes the maximum execution count per line across all tier profiles (logical OR: if any tier covered a line, it counts).

---

## Package Classification

| Package | Tier | Rationale |
|---------|------|-----------|
| config | UT | Pure config parsing |
| validate | UT | Input validation logic |
| audit | UT | Event construction |
| metrics | UT | Counter/histogram wiring |
| security | UT | Header sanitization |
| httputil | UT | HTTP helpers |
| requestid | UT | Middleware logic |
| logging | UT | Log setup |
| prometheus | UT | Registry wiring |
| tools | UT | CRD/KA/DS tool business logic |
| agent | UT | Prompt, RBAC config |
| session | UT | State machine |
| severity | UT (mixed) | Triage pipeline (excludes LLM client) |
| ratelimit | UT | Token bucket logic |
| resilience | UT | Circuit breaker config |
| streaming | UT | SSE framing |
| auth | UT+IT | RBAC helpers (UT), TokenReview/SAR middleware (IT) |
| handler | IT | MCP bridge, HTTP server dispatch |
| ka | IT | KA REST/MCP client |
| ds | IT | DS OgenClient |
| launcher | IT | Server bootstrap |
| controller | IT | Reconciler loops |
| tlswiring | IT | TLS cert loading/rotation |

---

## Tooling

The coverage report is generated by `scripts/coverage/coverage_report.py`, adapted from kubernaut's `scripts/coverage/coverage_report.py`. It supports three output formats:

- `table` (default): Terminal-friendly with per-package breakdown
- `markdown`: GitHub PR comment format (matches kubernaut's CI reporting)
- `json`: Machine-readable for CI/CD integration
