API: coverage and test reports 617c2840446c

//! Coverage (oxygenhub#113) and test reports (#114) over the API: what the

//! Coverage and Tests tabs show, for whoever may read the repository.

use super::{caller, not_found, reach, ApiError};

use crate::auth::Access;

use crate::{coverage, junit, Shared};

use axum::extract::{Path, Query, State};

use axum::http::HeaderMap;

use axum::Json;

use hub_api::{CoverageDetail, CoverageFile, CoverageReport, TestCase, TestReport, TestReportDetail};

use serde::Deserialize;

#[derive(Deserialize, Default)]

pub struct ListQuery {

    /// The bookmark (default: the repository's default).

    bookmark: Option<String>,

    /// At most this many, newest first (default 20, at most 200).

    limit: Option<i64>,

}

#[derive(Deserialize, Default)]

pub struct CasesQuery {

    /// `failed` for the failed and errored cases only.

    status: Option<String>,

}

fn coverage_of(app: &Shared, base: &str, r: &coverage::Report) -> CoverageReport {

    CoverageReport {

        id: r.id,

        run: r.run_number,

        job: r.job.clone(),

        bookmark: r.bookmark.clone(),

        state: r.state.clone(),

        format: r.format.clone(),

        lines_found: r.lines_found,

        lines_hit: r.lines_hit,

        percent: r.percent(),

        functions_found: r.functions_found,

        functions_hit: r.functions_hit,

        branches_found: r.branches_found,

        branches_hit: r.branches_hit,

        files: r.files,

        dropped: r.dropped,

        created_ms: r.created_ms,

        url: format!("{}{base}/coverage?report={}", app.config.base_url().trim_end_matches('/'), r.id),

    }

}

fn tests_of(app: &Shared, base: &str, r: &junit::Report) -> TestReport {

    TestReport {

        id: r.id,

        run: r.run_number,

        job: r.job.clone(),

        bookmark: r.bookmark.clone(),

        state: r.state.clone(),

        tests: r.tests,

        passed: r.passed,

        failed: r.failed,

        errors: r.errors,

        skipped: r.skipped,

        time_ms: r.time_ms,

        created_ms: r.created_ms,

        url: format!("{}{base}/tests?report={}", app.config.base_url().trim_end_matches('/'), r.id),

    }

}

/// `GET /repos/{o}/{n}/coverage`.

pub async fn coverage_list(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name)): Path<(String, String)>,

    Query(q): Query<ListQuery>,

) -> Result<Json<Vec<CoverageReport>>, ApiError> {

    let c = caller(&app, &headers).await?;

    let (_, row, _) = reach(&app, &c, &owner, &name, Access::Read).await?;

    let bookmark = q.bookmark.unwrap_or_else(|| row.default_bookmark.clone());

    let list = coverage::on_bookmark(&app.db, row.id, &bookmark, q.limit.unwrap_or(20).clamp(1, 200)).await?;

    let base = format!("/{owner}/{name}");

    Ok(Json(list.iter().map(|r| coverage_of(&app, &base, r)).collect()))

}

/// `GET /repos/{o}/{n}/coverage/{id}`.

pub async fn coverage_one(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name, id)): Path<(String, String, i64)>,

) -> Result<Json<CoverageDetail>, ApiError> {

    let c = caller(&app, &headers).await?;

    let (_, row, _) = reach(&app, &c, &owner, &name, Access::Read).await?;

    let r = coverage::report(&app.db, row.id, id).await?.ok_or_else(|| not_found("no such coverage report"))?;

    let files = coverage::files(&app.db, r.id)

        .await?

        .into_iter()

        .map(|f| CoverageFile {

            percent: f.percent(),

            path: f.path,

            lines_found: f.lines_found,

            lines_hit: f.lines_hit,

            functions_found: f.functions_found,

            functions_hit: f.functions_hit,

            branches_found: f.branches_found,

            branches_hit: f.branches_hit,

        })

        .collect();

    Ok(Json(CoverageDetail { report: coverage_of(&app, &format!("/{owner}/{name}"), &r), files }))

}

/// `GET /repos/{o}/{n}/tests`.

pub async fn tests_list(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name)): Path<(String, String)>,

    Query(q): Query<ListQuery>,

) -> Result<Json<Vec<TestReport>>, ApiError> {

    let c = caller(&app, &headers).await?;

    let (_, row, _) = reach(&app, &c, &owner, &name, Access::Read).await?;

    let bookmark = q.bookmark.unwrap_or_else(|| row.default_bookmark.clone());

    let list = junit::on_bookmark(&app.db, row.id, &bookmark, q.limit.unwrap_or(20).clamp(1, 200)).await?;

    let base = format!("/{owner}/{name}");

    Ok(Json(list.iter().map(|r| tests_of(&app, &base, r)).collect()))

}

/// `GET /repos/{o}/{n}/tests/{id}`.

pub async fn tests_one(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name, id)): Path<(String, String, i64)>,

    Query(q): Query<CasesQuery>,

) -> Result<Json<TestReportDetail>, ApiError> {

    let c = caller(&app, &headers).await?;

    let (_, row, _) = reach(&app, &c, &owner, &name, Access::Read).await?;

    let r = junit::report(&app.db, row.id, id).await?.ok_or_else(|| not_found("no such test report"))?;

    let statuses: &[&str] = match q.status.as_deref() {

        Some("failed") => &["failed", "error"],

        _ => &[],

    };

    let cases = junit::cases(&app.db, r.id, statuses, junit::MAX_CASES as i64)

        .await?

        .into_iter()

        .map(|c| TestCase {

            suite: c.suite,

            classname: c.classname,

            name: c.name,

            status: c.status,

            time_ms: c.time_ms,

            message: c.message,

            output: c.output,

        })

        .collect();

    Ok(Json(TestReportDetail { report: tests_of(&app, &format!("/{owner}/{name}"), &r), cases }))

}

/// `GET /repos/{o}/{n}/coverage`: a coverage report from a Flow job

/// (oxygenhub#113); `percent` values are of lines, functions and branches,

/// absent when nothing was counted.

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]

pub struct CoverageReport {

    pub id: i64,

    pub run: i64,

    pub job: String,

    pub bookmark: String,

    /// The run's state, by hash.

    pub state: String,

    /// `lcov` or `cobertura`.

    pub format: String,

    pub lines_found: i64,

    pub lines_hit: i64,

    pub percent: Option<f64>,

    pub functions_found: i64,

    pub functions_hit: i64,

    pub branches_found: i64,

    pub branches_hit: i64,

    pub files: i64,

    /// Files the report named that are not in the run's state.

    pub dropped: i64,

    pub created_ms: i64,

    /// The report on the hub's Coverage tab, absolute.

    pub url: String,

}

/// One file of a coverage report.

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]

pub struct CoverageFile {

    pub path: String,

    pub lines_found: i64,

    pub lines_hit: i64,

    pub percent: Option<f64>,

    pub functions_found: i64,

    pub functions_hit: i64,

    pub branches_found: i64,

    pub branches_hit: i64,

}

/// `GET /repos/{o}/{n}/coverage/{id}`: a report with its files.

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]

pub struct CoverageDetail {

    pub report: CoverageReport,

    pub files: Vec<CoverageFile>,

}

/// `GET /repos/{o}/{n}/tests`: a JUnit test report from a Flow job

/// (oxygenhub#114).

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct TestReport {

    pub id: i64,

    pub run: i64,

    pub job: String,

    pub bookmark: String,

    pub state: String,

    pub tests: i64,

    pub passed: i64,

    pub failed: i64,

    pub errors: i64,

    pub skipped: i64,

    /// The cases' times added up.

    pub time_ms: i64,

    pub created_ms: i64,

    pub url: String,

}

/// One test case of a report.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct TestCase {

    pub suite: String,

    pub classname: String,

    pub name: String,

    /// `passed`, `failed`, `error` or `skipped`.

    pub status: String,

    pub time_ms: i64,

    pub message: String,

    /// A failure's text and output, cut to 16 KiB; empty for a pass.

    pub output: String,

}

/// `GET /repos/{o}/{n}/tests/{id}`: a report with its cases

/// (`?status=failed` for the failed and errored ones).

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct TestReportDetail {

    pub report: TestReport,

    pub cases: Vec<TestCase>,

}

mod reports;

        .route("/repos/{owner}/{name}/coverage", get(reports::coverage_list))

        .route("/repos/{owner}/{name}/coverage/{id}", get(reports::coverage_one))

        .route("/repos/{owner}/{name}/tests", get(reports::tests_list))

        .route("/repos/{owner}/{name}/tests/{id}", get(reports::tests_one))

pub(super) async fn reach(

/// A report's cases in report order, all or only those with a status

/// among `statuses`.

pub async fn cases(pool: &Pool, report_id: i64, statuses: &[&str], limit: i64) -> sqlx::Result<Vec<Case>> {

    let filter = if statuses.is_empty() {

        String::new()

    } else {

        format!(" AND status IN ({})", statuses.iter().map(|_| "?").collect::<Vec<_>>().join(", "))

    };

    let sql = format!(

        "SELECT suite, classname, name, status, time_ms, message, output FROM test_cases WHERE report_id = ?{filter} ORDER BY idx LIMIT ?"

    );

    let mut q = sqlx::query_as(&sql).bind(report_id);

    for s in statuses {

        q = q.bind(*s);

    }

    q.bind(limit).fetch_all(pool).await

}

    // The API (#113).

    let (_, list) = call(&h.app, "GET", "/api/v1/repos/andy/cov/coverage", None, None).await;

    let list: serde_json::Value = serde_json::from_str(&list).unwrap();

    assert_eq!((list[0]["percent"].as_f64(), list[0]["format"].as_str()), (Some(50.0), Some("lcov")), "{list}");

    let (_, one) = call(&h.app, "GET", &format!("/api/v1/repos/andy/cov/coverage/{report}"), None, None).await;

    let one: serde_json::Value = serde_json::from_str(&one).unwrap();

    assert_eq!((one["files"][0]["path"].as_str(), one["files"][0]["lines_hit"].as_i64()), (Some("src/lib.rs"), Some(2)), "{one}");

    // The API (#114): the bookmark's reports newest first, and one with

    // its failed cases.

    let (st, list) = call(&h.app, "GET", "/api/v1/repos/andy/t/tests", None, None).await;

    assert_eq!(st, StatusCode::OK, "{list}");

    let list: serde_json::Value = serde_json::from_str(&list).unwrap();

    assert_eq!(list.as_array().unwrap().len(), 3);

    assert_eq!((list[0]["tests"].as_i64(), list[1]["failed"].as_i64()), (Some(4), Some(1)));

    let (_, one) = call(&h.app, "GET", &format!("/api/v1/repos/andy/t/tests/{second}?status=failed"), None, None).await;

    let one: serde_json::Value = serde_json::from_str(&one).unwrap();

    assert_eq!(one["cases"].as_array().unwrap().len(), 1);

    assert_eq!((one["cases"][0]["name"].as_str(), one["cases"][0]["message"].as_str()), (Some("b"), Some("b broke")));

    let (_, all) = call(&h.app, "GET", &format!("/api/v1/repos/andy/t/tests/{second}"), None, None).await;

    assert_eq!(serde_json::from_str::<serde_json::Value>(&all).unwrap()["cases"].as_array().unwrap().len(), 4);

    assert_eq!(call(&h.app, "GET", "/api/v1/repos/andy/t/tests/99999", None, None).await.0, StatusCode::NOT_FOUND);

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route, or a known one with the wrong method, too), cursor pagination (`?after=`), ETags on cacheable resources, and rate limits per token. Resources mirror the pages: `/repos/{owner}/{name}`, `/bookmarks`, `/changes/{hash}`, `/tree/{ref}/{path}`, `/file/{ref}/{path}`, `/blame`, `/history/{ref}` (`?path=`, `?offset=&limit=`, or `?r=REVSET` for the changes a revset selects, evaluated under a two-second budget and answering 400 when it does not parse or goes past it; Oxygen's docs/revset_query_language.md), `/compare`, `/conflicts`, `/proposals` (`?state=open|draft|landed|closed|all`, open ones and drafts by default; a source bookmark may hold `/`, and `owner/name:bookmark` naming the repository itself is its own bookmark), `/proposals/{n}/comments|reviews|checks|files`, `PATCH /proposals/{n}` (the title and description, for its author or a maintainer, and `labels`, the whole set by name, for triage; what is not given stays), `POST /proposals/{n}/land` (repo:write: what the Land button does, `409` with the blockers when it cannot; a landed proposal keeps the changes it landed and reports `landed` with who, how (`web`, or `api (token NAME)`) and when, which its event, the audit log and the push record also say, adding when nobody approved), `/proposals/{n}/content/{base|head}/{path}` (a changed file's bytes in the target's state or the projected state, for editor diff views), `/issues` (creating an issue can set its labels, assignees and milestone; `PATCH /issues/{n}` edits the title and body for the author or triage, and replaces labels, assignees or the milestone for triage, recording each on the timeline; unknown names are refused before anything changes), `/labels` (`POST` creates or changes one, `DELETE /labels/{name}` removes it; triage), `/milestones` (`POST` creates one or changes the description and due date of the one with that title, `PATCH /milestones/{title}` changes title, description, due date or state; triage), `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags`, `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/notifications` (the caller's inbox and unread count; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/orgs/{name}`, `/checks/{state}` (the checks on a state, named by its hash, by its heads joined with `+`, by the one head of a single-head state, or by a bookmark), `/checks/required` (`GET`, and `PUT` of the whole list by a repository admin: the checks a proposal needs, passed, to land), `/projects/{owner}` (list, create) and `/projects/{owner}/{n}` (the board as the caller may see it, `PATCH` for title, description, privacy and closing, `/cards` to list them by column or add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one; `repo:write` and the page's rights to change), `/coverage` and `/tests` (a bookmark's coverage and JUnit test reports from Flow jobs, newest first, `?bookmark=&limit=`), `/coverage/{id}` (a report with its files) and `/tests/{id}` (a report with its cases, `?status=failed` for the failed and errored ones), `/flow/runs` (`GET`: runs newest first, `?before=N&limit=`; `POST {"bookmark"}` or `{"change"}`, repo:write: run a bookmark's current state, the default bookmark when none is named, or one change's state), `/flow/runs/{n}` (a run with its jobs), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/flow/runs/{n}/cancel` (repo:write: a run still going ends as `cancelled`, its running jobs stopped when their runner next reports; `409` when it had already ended; a push to a bookmark cancels the push runs of it still going), `/search`. A change's author carries the account its key is linked to, or `null` and a `note` saying the key is not linked and where its owner links it; `via` names the delegate (an agent) that signed for the author when one did, with the delegation's scope and expiry and whether it has since been revoked, and the pages show the same as an `agent` badge, a `via` row under the author on the change page, and a count under the author in Contributors (the change page shows a "key not linked" tag, with a link to Settings → Keys for signed-in viewers). Shapes reuse `oxy --json` shapes wherever one exists (change, status, blame, diff) so tools written against the CLI work against the hub. `crates/hub-api` holds the types with `serde` derives and is what the runner and the VS Code extension will link.

### 13.6 Coverage reports (oxygenhub#113, done 2026-10-06)

- **API:** `GET /repos/{o}/{n}/coverage` and `/coverage/{id}` (§12.1).

- **API:** `GET /repos/{o}/{n}/tests` and `/tests/{id}` (§12.1).