API Contract Tests

// crates/craig-test-lib/src/schema.rs

use anyhow::{Context, Result, bail};
use serde_json::Value;
use std::path::PathBuf;
use std::sync::OnceLock;

/// Validates API response bodies against committed OpenAPI spec files.
pub struct SchemaValidator {
    spec: Value,
    service_name: String,
}

/// Workspace root detection: walks up from CARGO_MANIFEST_DIR to find
/// the directory containing `api-specs/`.
fn workspace_root() -> &'static PathBuf {
    static ROOT: OnceLock<PathBuf> = OnceLock::new();
    ROOT.get_or_init(|| {
        let mut dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
        loop {
            if dir.join("api-specs").is_dir() {
                return dir;
            }
            if !dir.pop() {
                // Fallback: assume cwd
                return PathBuf::from(".");
            }
        }
    })
}

impl SchemaValidator {
    /// Load from committed spec file at `<workspace>/api-specs/<service_name>.json`.
    pub fn load(service_name: &str) -> Result<Self> {
        let path = workspace_root().join(format!("api-specs/{service_name}.json"));
        let content = std::fs::read_to_string(&path)
            .with_context(|| format!("failed to read spec file: {}", path.display()))?;
        let spec: Value = serde_json::from_str(&content)
            .with_context(|| format!("failed to parse spec file: {}", path.display()))?;
        Ok(Self {
            spec,
            service_name: service_name.to_string(),
        })
    }

    /// Validate a response body against the schema declared for the given
    /// operation (method + path template) and HTTP status code.
    ///
    /// `path_template` uses OpenAPI path syntax, e.g., "/v1/cases/cases/{id}".
    /// `method` is lowercase, e.g., "get", "post".
    pub fn validate(
        &self,
        method: &str,
        path_template: &str,
        status: u16,
        body: &Value,
    ) -> Result<()> {
        let schema = self.extract_response_schema(method, path_template, status)?;

        // Resolve $ref pointers to produce a self-contained schema.
        let resolved = self.resolve_refs(&schema)?;

        // Validate using jsonschema crate.
        let validator = jsonschema::validator_for(&resolved)
            .map_err(|e| anyhow::anyhow!("failed to compile schema: {e}"))?;

        let errors: Vec<String> = validator
            .iter_errors(body)
            .map(|e| format!("  - {e} (at {})", e.instance_path))
            .collect();

        if errors.is_empty() {
            Ok(())
        } else {
            bail!(
                "schema validation failed for {} {} {} on {}:\n{}",
                method.to_uppercase(),
                path_template,
                status,
                self.service_name,
                errors.join("\n")
            )
        }
    }

    /// Extract the JSON Schema for a specific response from the OpenAPI spec.
    fn extract_response_schema(
        &self,
        method: &str,
        path_template: &str,
        status: u16,
    ) -> Result<Value> {
        let paths = self.spec.get("paths")
            .context("spec missing 'paths'")?;

        let path_item = paths.get(path_template)
            .with_context(|| format!(
                "path '{}' not found in spec (available: {})",
                path_template,
                paths.as_object().map(|o| o.keys().cloned().collect::<Vec<_>>().join(", "))
                    .unwrap_or_default()
            ))?;

        let operation = path_item.get(&method.to_lowercase())
            .with_context(|| format!(
                "method '{}' not found for path '{}'",
                method, path_template
            ))?;

        let responses = operation.get("responses")
            .context("operation missing 'responses'")?;

        let status_str = status.to_string();
        let response = responses.get(&status_str)
            .with_context(|| format!(
                "status {} not found in responses for {} {}",
                status, method.to_uppercase(), path_template
            ))?;

        // Follow $ref on the response object itself (utoipa sometimes uses
        // response references).
        let response = if let Some(ref_path) = response.get("$ref") {
            self.resolve_ref(ref_path.as_str().context("$ref is not a string")?)?
        } else {
            response.clone()
        };

        let content = response.get("content")
            .with_context(|| format!(
                "response {} has no 'content' (may be empty body like 204)",
                status
            ))?;

        let media_type = content.get("application/json")
            .context("response content missing 'application/json'")?;

        media_type.get("schema")
            .cloned()
            .context("media type missing 'schema'")
    }

    /// Recursively resolve all `$ref` pointers in a schema against
    /// the spec's `components/schemas` section.
    fn resolve_refs(&self, schema: &Value) -> Result<Value> {
        match schema {
            Value::Object(map) => {
                // If this object is a $ref, resolve it and then resolve its contents.
                if let Some(ref_val) = map.get("$ref") {
                    let ref_str = ref_val.as_str().context("$ref is not a string")?;
                    let resolved = self.resolve_ref(ref_str)?;
                    return self.resolve_refs(&resolved);
                }

                // Otherwise, recursively resolve all values.
                let mut new_map = serde_json::Map::new();
                for (key, value) in map {
                    new_map.insert(key.clone(), self.resolve_refs(value)?);
                }
                Ok(Value::Object(new_map))
            }
            Value::Array(arr) => {
                let new_arr: Result<Vec<Value>> =
                    arr.iter().map(|v| self.resolve_refs(v)).collect();
                Ok(Value::Array(new_arr?))
            }
            other => Ok(other.clone()),
        }
    }

    /// Resolve a single `$ref` string like `#/components/schemas/RuleSet`
    /// against the spec.
    fn resolve_ref(&self, ref_path: &str) -> Result<Value> {
        let pointer = ref_path
            .strip_prefix('#')
            .with_context(|| format!("only local $ref supported, got: {ref_path}"))?;

        // Convert OpenAPI JSON Reference to JSON Pointer (/ separated).
        // The ref_path is already in the right format after stripping #.
        self.spec.pointer(pointer)
            .cloned()
            .with_context(|| format!("$ref '{}' not found in spec", ref_path))
    }
}

# In crates/craig-test-lib/Cargo.toml, add to [dependencies]:
jsonschema = "0.33"

// In services/craig-cases/tests/api/cases.rs

use craig_test_lib::schema::SchemaValidator;

#[tokio::test]
async fn create_case() {
    if !devstack_available().await {
        return;
    }
    let harness = TestHarness::new().await.unwrap();
    let client = harness.caseworker_cases_client().await.unwrap();
    let validator = SchemaValidator::load("craig-cases").unwrap();

    let body = json!({
        "admin_unit": "Fulton",
        "assigned_worker": "bob.smith",
        "icwa_flag": false
    });
    let resp = client.create_case(&body).await.unwrap();
    assert_eq!(resp.status, StatusCode::OK);

    // Schema validation — parse raw response and validate against OpenAPI spec
    let raw_json: serde_json::Value = serde_json::from_str(&resp.raw).unwrap();
    validator.validate("post", "/v1/cases/cases", 200, &raw_json).unwrap();

    let data = resp.body.unwrap();
    assert!(data["id"].is_string());
    assert_eq!(data["status"], "open");
}

#[tokio::test]
async fn get_case() {
    if !devstack_available().await {
        return;
    }
    let harness = TestHarness::new().await.unwrap();
    let case_id = create_case_id(&harness).await;
    let client = harness.caseworker_cases_client().await.unwrap();
    let validator = SchemaValidator::load("craig-cases").unwrap();

    let resp = client.get_case(&case_id).await.unwrap();
    assert_eq!(resp.status, StatusCode::OK);

    // Schema validation
    let raw_json: serde_json::Value = serde_json::from_str(&resp.raw).unwrap();
    validator.validate("get", "/v1/cases/cases/{id}", 200, &raw_json).unwrap();
}

#[tokio::test]
async fn list_cases() {
    if !devstack_available().await {
        return;
    }
    let harness = TestHarness::new().await.unwrap();
    let client = harness.caseworker_cases_client().await.unwrap();
    let validator = SchemaValidator::load("craig-cases").unwrap();

    let resp = client
        .list_cases(&[("page", "1"), ("per_page", "10")])
        .await
        .unwrap();
    assert_eq!(resp.status, StatusCode::OK);

    // Schema validation — list endpoints return PageResponse<T>
    let raw_json: serde_json::Value = serde_json::from_str(&resp.raw).unwrap();
    validator.validate("get", "/v1/cases/cases", 200, &raw_json).unwrap();
}

/// Validate an ApiResponse against the OpenAPI schema.
/// Usage: assert_schema!(validator, "post", "/v1/cases/cases", 200, resp);
macro_rules! assert_schema {
    ($validator:expr, $method:expr, $path:expr, $status:expr, $resp:expr) => {
        let __raw: serde_json::Value = serde_json::from_str(&$resp.raw)
            .expect("response body is not valid JSON");
        $validator
            .validate($method, $path, $status, &__raw)
            .expect("schema validation failed");
    };
}