haste_testscript_runner/

lib.rs

use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
use haste_fhir_client::{
    FHIRClient,
    http::{
        FHIRHttpExchange, HeaderMap, HeaderName, HeaderValue, HttpResponseMetadata, Method,
        StatusCode, WithRequestHeaders, header,
    },
    request::{
        DeleteRequest, DeleteResponse, FHIRBatchRequest, FHIRConditionalUpdateRequest,
        FHIRCreateRequest, FHIRDeleteInstanceRequest, FHIRDeleteSystemRequest,
        FHIRDeleteTypeRequest, FHIRHistoryInstanceRequest, FHIRHistorySystemRequest,
        FHIRHistoryTypeRequest, FHIRInvokeInstanceRequest, FHIRInvokeSystemRequest,
        FHIRInvokeTypeRequest, FHIRPatchRequest, FHIRReadRequest, FHIRRequest, FHIRResponse,
        FHIRSearchTypeRequest, FHIRTransactionRequest, FHIRUpdateInstanceRequest,
        FHIRVersionReadRequest, HistoryRequest, HistoryResponse, InvocationRequest, InvokeResponse,
        Operation, SearchRequest, SearchResponse, UpdateRequest,
    },
    url::ParsedParameters,
};
use haste_fhir_model::r4::generated::{
    resources::{
        Resource, ResourceType, TestReport, TestReportSetup, TestReportSetupAction,
        TestReportSetupActionAssert, TestReportSetupActionOperation, TestReportTeardown,
        TestReportTeardownAction, TestReportTest, TestReportTestAction, TestScript,
        TestScriptFixture, TestScriptSetup, TestScriptSetupAction, TestScriptSetupActionAssert,
        TestScriptSetupActionOperation, TestScriptTeardown, TestScriptTeardownAction,
        TestScriptTest, TestScriptTestAction, TestScriptVariable,
    },
    terminology::{
        AssertDirectionCodes, AssertOperatorCodes, BoundCode, BundleType, IssueType,
        ReportActionResultCodes, ReportResultCodes, ReportStatusCodes, TestscriptOperationCodes,
    },
    types::{ExtensionValueTypeChoice, FHIRId, FHIRMarkdown, FHIRString, Reference},
};
use haste_fhir_operation_error::OperationOutcomeError;
use haste_pointer::{Key, TypedPointer};
use haste_reflect::MetaValue;
use regex::Regex;
use std::{
    any::Any,
    collections::HashMap,
    sync::{Arc, LazyLock},
    time::Duration,
};
use tokio::sync::Mutex;

use crate::conversion::ConvertedValue;

mod conversion;

#[derive(Debug)]
pub enum TestScriptError {
    ExecutionError(String),
    ValidationError(String),
    FixtureNotFound,
    InvalidFixture,
    OperationError(OperationOutcomeError),
}

#[derive(Debug, Clone)]
enum Response {
    Interaction(Box<FHIRResponse>),
    OperationError(Arc<OperationOutcomeError>),
    /// The response to a request that is not a FHIR interaction (an operation
    /// with a `url` and no `type`): its body, when that is a FHIR resource.
    Http(Option<Box<Resource>>),
}

/// A response as fixtures, variables and assertions see it: the FHIR
/// response, plus the HTTP status and headers it came with (`None` when the
/// request failed before a response arrived).
#[derive(Debug, Clone)]
struct RecordedResponse {
    response: Response,
    http: Option<HttpResponseMetadata>,
}

#[derive(Debug)]
enum Fixtures {
    Resource(Resource),
    Request(FHIRRequest),
    Response(RecordedResponse),
}

// Internal structure to hold current test result and testing fixtures.
struct TestState {
    fp_engine: haste_fhirpath::FPEngine,
    fixtures: HashMap<String, Fixtures>,
    latest_request: Option<FHIRRequest>,
    latest_response: Option<RecordedResponse>,
    result: BoundCode<ReportResultCodes>,
    /// Writes not yet confirmed visible to search, the latest per resource.
    /// All are waited for, since a search (a chained one especially) may
    /// filter on any of them.
    unindexed_writes: Vec<IndexedWrite>,
}

/// A write that searches must see before they run. Search indexing is
/// asynchronous, so a search sent straight after a write can miss it. The
/// worker indexes a tenant's writes in order, so once the latest write is
/// visible every earlier one is too.
#[derive(Debug, Clone)]
struct IndexedWrite {
    resource_type: ResourceType,
    id: String,
    /// The version search should return; `None` for a delete, which search
    /// should no longer return at all.
    version_id: Option<String>,
}

impl TestState {
    fn new() -> Self {
        TestState {
            fp_engine: haste_fhirpath::FPEngine::new(),
            fixtures: HashMap::new(),
            latest_request: None,
            latest_response: None,
            result: ReportResultCodes::pending(),
            unindexed_writes: Vec::new(),
        }
    }
    fn resolve_fixture<'a>(
        &'a self,
        fixture_id: &str,
    ) -> Result<&'a dyn MetaValue, TestScriptError> {
        let fixture = self
            .fixtures
            .get(fixture_id)
            .ok_or(TestScriptError::FixtureNotFound)?;

        match fixture {
            Fixtures::Resource(res) => Ok(res),
            Fixtures::Request(req) => {
                request_to_meta_value(req).ok_or_else(|| TestScriptError::InvalidFixture)
            }
            Fixtures::Response(recorded) => response_to_meta_value(&recorded.response)
                .ok_or_else(|| TestScriptError::InvalidFixture),
        }
    }

    /// The response fixture `fixture_id` names, or the latest response.
    fn resolve_response(
        &self,
        fixture_id: Option<&str>,
    ) -> Result<&RecordedResponse, TestScriptError> {
        match fixture_id {
            Some(fixture_id) => match self.fixtures.get(fixture_id) {
                Some(Fixtures::Response(recorded)) => Ok(recorded),
                Some(_) => Err(TestScriptError::ExecutionError(format!(
                    "Fixture '{fixture_id}' is not a response."
                ))),
                None => Err(TestScriptError::FixtureNotFound),
            },
            None => self.latest_response.as_ref().ok_or_else(|| {
                TestScriptError::ExecutionError("No response to evaluate yet.".to_string())
            }),
        }
    }
}

struct TestResult<T> {
    pub state: Arc<Mutex<TestState>>,
    pub value: T,
}

fn response_to_meta_value(response: &Response) -> Option<&dyn MetaValue> {
    match response {
        Response::Interaction(fhir_response) => match &**fhir_response {
            FHIRResponse::Create(res) => Some(&res.resource),
            FHIRResponse::Read(res) => Some(&res.resource),
            FHIRResponse::VersionRead(res) => Some(&res.resource),
            FHIRResponse::Update(res) => Some(&res.resource),
            FHIRResponse::Patch(res) => Some(&res.resource),
            FHIRResponse::Batch(res) => Some(&res.resource),
            FHIRResponse::Transaction(res) => Some(&res.resource),

            FHIRResponse::Capabilities(res) => Some(&res.capabilities),
            FHIRResponse::Search(res) => match res {
                SearchResponse::Type(res) => Some(&res.bundle),
                SearchResponse::System(res) => Some(&res.bundle),
            },
            FHIRResponse::History(res) => match res {
                HistoryResponse::Instance(res) => Some(&res.bundle),
                HistoryResponse::Type(res) => Some(&res.bundle),
                HistoryResponse::System(res) => Some(&res.bundle),
            },
            FHIRResponse::Invoke(res) => match res {
                InvokeResponse::Instance(res) => Some(&res.resource),
                InvokeResponse::Type(res) => Some(&res.resource),
                InvokeResponse::System(res) => Some(&res.resource),
            },

            FHIRResponse::Delete(_) | FHIRResponse::Accepted(_) => None,
        },
        Response::OperationError(op_error) => {
            let outcome = op_error.outcome();
            Some(outcome)
        }
        Response::Http(resource) => resource
            .as_deref()
            .map(|resource| resource as &dyn MetaValue),
    }
}

fn request_to_meta_value(request: &FHIRRequest) -> Option<&dyn MetaValue> {
    match request {
        FHIRRequest::Create(req) => Some(&req.resource),

        FHIRRequest::Update(update_request) => match update_request {
            UpdateRequest::Conditional(req) => Some(&req.resource),
            UpdateRequest::Instance(req) => Some(&req.resource),
        },

        FHIRRequest::Batch(req) => Some(&req.resource),
        FHIRRequest::Transaction(req) => Some(&req.resource),
        FHIRRequest::Invocation(req) => match req {
            haste_fhir_client::request::InvocationRequest::Instance(req) => Some(&req.parameters),
            haste_fhir_client::request::InvocationRequest::Type(req) => Some(&req.parameters),
            haste_fhir_client::request::InvocationRequest::System(req) => Some(&req.parameters),
        },
        FHIRRequest::Read(_)
        | FHIRRequest::VersionRead(_)
        | FHIRRequest::Compartment(_)
        | FHIRRequest::Patch(_)
        | FHIRRequest::Delete(_)
        | FHIRRequest::Capabilities
        | FHIRRequest::Search(_)
        | FHIRRequest::History(_) => None,
    }
}

fn associate_request_response_variables(
    state: &mut TestState,
    operation: &TestScriptSetupActionOperation,
    request: Option<FHIRRequest>,
    response: RecordedResponse,
) {
    if let Some(request) = request.as_ref()
        && let Some(request_var) = operation
            .requestId
            .as_ref()
            .and_then(|id| id.value.as_ref())
    {
        // Associate request variable in state
        state
            .fixtures
            .insert(request_var.clone(), Fixtures::Request(request.clone()));
    }

    if let Some(response_var) = operation
        .responseId
        .as_ref()
        .and_then(|id| id.value.as_ref())
    {
        // Associate response variable in state
        state
            .fixtures
            .insert(response_var.clone(), Fixtures::Response(response.clone()));
    }

    state.latest_request = request;
    state.latest_response = Some(response);
}

/// Derive the resource type from operation or from the metavalue if not present on operation.
fn derive_resource_type(
    operation: &TestScriptSetupActionOperation,
    target: Option<&dyn MetaValue>,
    path: &str,
) -> Result<ResourceType, TestScriptError> {
    if let Some(operation_resource_type) = operation.resource.as_ref() {
        let string_type = operation_resource_type.as_str();
        ResourceType::try_from(string_type.unwrap_or_default()).map_err(|_| {
            TestScriptError::ExecutionError(format!(
                "Unsupported resource type '{operation_resource_type:?}' for operation at '{path}'."
            ))
        })
    } else if let Some(target) = target {
        ResourceType::try_from(target.fhir_type()).map_err(|_| {
            TestScriptError::ExecutionError(format!(
                "Unsupported resource type '{}' for operation at '{path}'.",
                target.fhir_type()
            ))
        })
    } else {
        Err(TestScriptError::ExecutionError(format!(
            "Failed to derive resource type for operation at '{path}'.",
        )))
    }
}

static EXPRESSION_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\$\{([^}]*)\}").unwrap());

async fn get_variable(
    state: &TestState,
    variables: &[TestScriptVariable],
    variable_id: &str,
) -> Result<ConvertedValue, TestScriptError> {
    let Some(variable) = variables
        .iter()
        .find(|v| v.name.value.as_deref() == Some(variable_id))
    else {
        return Err(TestScriptError::ExecutionError(format!(
            "Variable with id '{variable_id}' not found."
        )));
    };

    if let Some(field) = variable
        .headerField
        .as_ref()
        .and_then(|field| field.value.as_deref())
    {
        let source_id = variable
            .sourceId
            .as_ref()
            .and_then(|id| id.value.as_deref());
        let recorded = state.resolve_response(source_id)?;

        return header_value(recorded, field)
            .map(ConvertedValue::String)
            .ok_or_else(|| {
                TestScriptError::ExecutionError(format!(
                    "Variable '{variable_id}': the response has no '{field}' header."
                ))
            });
    }

    if let Some(expression) = variable
        .expression
        .as_ref()
        .and_then(|exp| exp.value.as_ref())
    {
        let values =
            if let Some(source_id) = variable.sourceId.as_ref().and_then(|id| id.value.as_ref()) {
                let source = state.resolve_fixture(source_id)?;
                vec![source]
            } else {
                vec![]
            };

        let eval_result = state
            .fp_engine
            .evaluate(expression, values)
            .await
            .map_err(|e| {
                TestScriptError::ExecutionError(format!(
                    "Failed to evaluate FHIRPath expression for variable '{variable_id}': {e}"
                ))
            })?;

        let converted_values = eval_result
            .iter()
            .map(conversion::convert_meta_value)
            .collect::<Vec<_>>();

        if converted_values.len() == 1 {
            Ok(converted_values.into_iter().next().unwrap())
        } else {
            Err(TestScriptError::ExecutionError(format!(
                "Variable '{variable_id}' evaluation returned multiple values; only single value supported.",
            )))
        }
    } else {
        Err(TestScriptError::ExecutionError(format!(
            "Only support variable with expression or headerField for variable id '{variable_id}'.",
        )))
    }
}

async fn evaluate_variable(
    state: &TestState,
    pointer: TypedPointer<TestScript, TestScript>,
    value: &str,
) -> Result<String, TestScriptError> {
    let mut result = value.to_string();
    let variable_pointer =
        pointer.descend::<Vec<TestScriptVariable>>(&Key::Field("variable".to_string()));
    let default_variables = vec![];

    let variables = if let Some(pointer) = variable_pointer.as_ref() {
        pointer.value().unwrap_or(&default_variables)
    } else {
        &default_variables
    };

    for reg_match in EXPRESSION_REGEX.captures_iter(value) {
        let full_match = reg_match.get(0).map_or("", |m| m.as_str());
        let Some(variable_id) = reg_match.get(1).map(|m| m.as_str()) else {
            return Err(TestScriptError::ExecutionError(format!(
                "Invalid variable expression in '{value}'."
            )));
        };

        let variable = get_variable(state, variables, variable_id).await?;
        result = result.replace(full_match, variable.to_string().as_str());
    }

    Ok(result)
}

/// What an operation sends: a FHIR interaction, or a plain HTTP request.
enum OperationRequest {
    Interaction(Box<FHIRRequest>),
    Http { method: Method, url: String },
}

async fn testscript_operation_to_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
) -> Result<OperationRequest, TestScriptError> {
    let operation = get_operation(pointer)?;

    // An operation with a `url` and no `type` is a plain HTTP request to that
    // (variable-evaluated) URL by its `method`: how a `TestScript` reaches what
    // is not a FHIR interaction, such as an asynchronous request's status URL.
    if get_operation_type(operation).is_none()
        && let Some(url) = operation.url.as_ref().and_then(|url| url.value.as_deref())
    {
        // The method codes are the HTTP methods in lower case.
        let method = operation
            .method
            .as_ref()
            .and_then(BoundCode::as_str)
            .unwrap_or("get");
        let method = Method::from_bytes(method.to_ascii_uppercase().as_bytes()).map_err(|_| {
            TestScriptError::ExecutionError(format!(
                "Unsupported method '{method}' for operation at '{}'.",
                pointer.path()
            ))
        })?;

        return Ok(OperationRequest::Http {
            method,
            url: evaluate_variable(state, pointer.root(), url).await?,
        });
    }

    testscript_operation_to_fhir_request(state, pointer)
        .await
        .map(|request| OperationRequest::Interaction(Box::new(request)))
}

async fn testscript_operation_to_fhir_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
) -> Result<FHIRRequest, TestScriptError> {
    let operation = get_operation(pointer)?;
    let op = get_operation_type(operation);

    match op {
        Some(op) if Some(op) == TestscriptOperationCodes::read().as_str() => {
            read_request(state, pointer, operation)
        }

        Some(op) if Some(op) == TestscriptOperationCodes::vread().as_str() => {
            version_read_request(state, pointer, operation)
        }

        Some(op) if Some(op) == TestscriptOperationCodes::search().as_str() => {
            search_request(state, pointer, operation).await
        }

        Some(op) if Some(op) == TestscriptOperationCodes::history().as_str() => {
            history_request(state, pointer, operation).await
        }

        Some(op) if Some(op) == TestscriptOperationCodes::transaction().as_str() => {
            transaction_request(state, pointer, operation)
        }

        Some(op) if Some(op) == TestscriptOperationCodes::batch().as_str() => {
            batch_request(state, pointer, operation)
        }

        Some(op) if Some(op) == TestscriptOperationCodes::create().as_str() => {
            create_request(state, pointer, operation)
        }

        Some(op) if Some(op) == TestscriptOperationCodes::update().as_str() => {
            update_request(state, pointer, operation)
        }

        Some(op) if Some(op) == TestscriptOperationCodes::update_create().as_str() => {
            conditional_update_request(state, pointer, operation).await
        }

        Some(op) if Some(op) == TestscriptOperationCodes::patch().as_str() => {
            patch_request(state, pointer, operation)
        }

        Some(op) if Some(op) == TestscriptOperationCodes::delete().as_str() => {
            delete_request(state, pointer, operation)
        }

        Some(op)
            if Some(op) == TestscriptOperationCodes::delete_cond_multiple().as_str()
                || Some(op) == TestscriptOperationCodes::delete_cond_single().as_str() =>
        {
            conditional_delete_request(state, pointer, operation)
        }

        Some(op)
            if Some(op) == TestscriptOperationCodes::capabilities().as_str()
                || Some(op) == TestscriptOperationCodes::conforms().as_str() =>
        {
            Ok(FHIRRequest::Capabilities)
        }

        Some("invoke") => invoke_request(state, pointer, operation),

        _ => Err(TestScriptError::ExecutionError(format!(
            "Unsupported TestScript operation type: {op:?} at '{}'.",
            pointer.path(),
        ))),
    }
}

fn read_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let target_id = require_target_id(operation, pointer.path(), "Read")?;
    let target = state.resolve_fixture(target_id)?;

    Ok(FHIRRequest::Read(FHIRReadRequest {
        resource_type: derive_resource_type(operation, Some(target), pointer.path())?,
        id: fixture_string_field(target, target_id, "id")?,
    }))
}

fn version_read_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let target_id = require_target_id(operation, pointer.path(), "Version Read")?;
    let target = state.resolve_fixture(target_id)?;

    Ok(FHIRRequest::VersionRead(FHIRVersionReadRequest {
        resource_type: derive_resource_type(operation, Some(target), pointer.path())?,
        id: fixture_string_field(target, target_id, "id")?,
        version_id: fixture_version_id(target, target_id)?.into(),
    }))
}

async fn search_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let query = operation
        .params
        .as_ref()
        .and_then(|p| p.value.as_deref())
        .unwrap_or_default();

    let parameters =
        parsed_parameters(state, pointer.root(), query, pointer.path(), "Search").await?;

    if let Ok(resource_type) = derive_resource_type(operation, None, pointer.path()) {
        Ok(FHIRRequest::Search(
            haste_fhir_client::request::SearchRequest::Type(
                haste_fhir_client::request::FHIRSearchTypeRequest {
                    resource_type,
                    parameters,
                },
            ),
        ))
    } else {
        Ok(FHIRRequest::Search(
            haste_fhir_client::request::SearchRequest::System(
                haste_fhir_client::request::FHIRSearchSystemRequest { parameters },
            ),
        ))
    }
}

async fn history_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let parameters = parsed_parameters(
        state,
        pointer.root(),
        operation
            .params
            .as_ref()
            .and_then(|p| p.value.as_deref())
            .unwrap_or_default(),
        pointer.path(),
        "History",
    )
    .await?;

    if let Some(target_id) = operation
        .targetId
        .as_ref()
        .and_then(|id| id.value.as_deref())
    {
        let target = state.resolve_fixture(target_id)?;

        Ok(FHIRRequest::History(HistoryRequest::Instance(
            FHIRHistoryInstanceRequest {
                resource_type: derive_resource_type(operation, Some(target), pointer.path())?,
                id: fixture_string_field(target, target_id, "id")?,
                parameters,
            },
        )))
    } else if operation.resource.is_some() {
        Ok(FHIRRequest::History(HistoryRequest::Type(
            FHIRHistoryTypeRequest {
                resource_type: derive_resource_type(operation, None, pointer.path())?,
                parameters,
            },
        )))
    } else {
        Ok(FHIRRequest::History(HistoryRequest::System(
            FHIRHistorySystemRequest { parameters },
        )))
    }
}

fn transaction_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let source_id = require_source_id(operation, pointer.path(), "Transaction")?;
    let source = state.resolve_fixture(source_id)?;
    let resource = fixture_resource(source, source_id)?;

    match resource {
        Resource::Bundle(bundle) => {
            if bundle.type_ != BundleType::transaction() {
                return Err(TestScriptError::ExecutionError(format!(
                    "Fixture must be a transaction bundle for transaction operations for sourceId '{source_id}'."
                )));
            }

            Ok(FHIRRequest::Transaction(FHIRTransactionRequest {
                resource: bundle,
            }))
        }
        _ => Err(TestScriptError::ExecutionError(format!(
            "Fixture '{source_id}' is not a transaction Bundle resource."
        ))),
    }
}

fn batch_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let source_id = require_source_id(operation, pointer.path(), "Batch")?;
    let source = state.resolve_fixture(source_id)?;
    let resource = fixture_resource(source, source_id)?;

    match resource {
        Resource::Bundle(bundle) => {
            if bundle.type_ != BundleType::batch() {
                return Err(TestScriptError::ExecutionError(format!(
                    "Fixture must be a batch bundle for batch operations for sourceId '{source_id}'."
                )));
            }

            Ok(FHIRRequest::Batch(FHIRBatchRequest { resource: bundle }))
        }
        _ => Err(TestScriptError::ExecutionError(format!(
            "Fixture '{source_id}' is not a batch Bundle resource."
        ))),
    }
}

fn create_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let source_id = require_source_id(operation, pointer.path(), "Create")?;
    let source = state.resolve_fixture(source_id)?;
    let resource = fixture_resource(source, source_id)?;

    Ok(FHIRRequest::Create(FHIRCreateRequest {
        resource_type: derive_resource_type(operation, Some(source), pointer.path())?,
        resource,
    }))
}

fn update_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let source_id = require_source_id(operation, pointer.path(), "Update")?;
    let source = state.resolve_fixture(source_id)?;
    let mut resource = fixture_resource(source, source_id)?;

    let target_id = require_target_id(operation, pointer.path(), "Update")?;
    let target = state.resolve_fixture(target_id)?;
    let target_resource = fixture_resource(target, target_id)?;
    let id = fixture_string_field(&target_resource, target_id, "id")?;

    // A contained fixture's id is local to the TestScript. The update
    // addresses the target, and the server refuses a body naming another id.
    if let Some(body_id) = resource
        .get_field_mut("id")
        .and_then(|body_id| (body_id as &mut dyn Any).downcast_mut::<Option<String>>())
    {
        *body_id = Some(id.clone());
    }

    Ok(FHIRRequest::Update(UpdateRequest::Instance(
        FHIRUpdateInstanceRequest {
            resource_type: derive_resource_type(operation, Some(target), pointer.path())?,
            id,
            resource,
        },
    )))
}

async fn conditional_update_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let source_id = require_source_id(operation, pointer.path(), "UpdateCreate")?;
    let source = state.resolve_fixture(source_id)?;
    let resource = fixture_resource(source, source_id)?;

    let parameters = parsed_parameters(
        state,
        pointer.root(),
        operation
            .params
            .as_ref()
            .and_then(|p| p.value.as_deref())
            .unwrap_or_default(),
        pointer.path(),
        "UpdateCreate",
    )
    .await?;

    Ok(FHIRRequest::Update(UpdateRequest::Conditional(
        FHIRConditionalUpdateRequest {
            resource_type: derive_resource_type(operation, Some(source), pointer.path())?,
            parameters,
            resource,
        },
    )))
}

fn delete_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let target_id = require_target_id(operation, pointer.path(), "Delete")?;
    let target = state.resolve_fixture(target_id)?;

    Ok(FHIRRequest::Delete(DeleteRequest::Instance(
        FHIRDeleteInstanceRequest {
            resource_type: derive_resource_type(operation, Some(target), pointer.path())?,
            id: fixture_string_field(target, target_id, "id")?,
        },
    )))
}

fn conditional_delete_request(
    _state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let parameters = ParsedParameters::try_from(
        operation
            .params
            .as_ref()
            .and_then(|p| p.value.as_deref())
            .unwrap_or_default(),
    )
    .map_err(|e| {
        TestScriptError::ExecutionError(format!(
            "Failed to parse parameters for conditional delete operation at '{}': {}",
            pointer.path(),
            e
        ))
    })?;

    if operation.resource.is_some() {
        Ok(FHIRRequest::Delete(DeleteRequest::Type(
            FHIRDeleteTypeRequest {
                resource_type: derive_resource_type(operation, None, pointer.path())?,
                parameters,
            },
        )))
    } else {
        Ok(FHIRRequest::Delete(DeleteRequest::System(
            FHIRDeleteSystemRequest { parameters },
        )))
    }
}

/// The patch source fixture must be a `Binary` resource carrying the JSON Patch
/// document, base64-encoded in `data` with `contentType`
/// `application/json-patch+json` — the standard way `TestScript` represents patch
/// bodies, since there's no dedicated FHIR resource type for a JSON Patch document.
fn patch_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let target_id = require_target_id(operation, pointer.path(), "Patch")?;
    let target = state.resolve_fixture(target_id)?;

    let source_id = require_source_id(operation, pointer.path(), "Patch")?;
    let source = state.resolve_fixture(source_id)?;
    let Resource::Binary(binary) = fixture_resource(source, source_id)? else {
        return Err(TestScriptError::ExecutionError(format!(
            "Patch source fixture '{source_id}' must be a Binary resource containing the JSON Patch document."
        )));
    };

    let content_type = binary.contentType.value.as_deref().unwrap_or_default();
    if content_type != "application/json-patch+json" {
        return Err(TestScriptError::ExecutionError(format!(
            "Unsupported patch content type '{content_type}' for fixture '{source_id}'; only 'application/json-patch+json' is supported."
        )));
    }

    let encoded = binary
        .data
        .as_ref()
        .and_then(|d| d.value.as_deref())
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Patch source fixture '{source_id}' Binary resource has no 'data'."
            ))
        })?;

    let decoded = BASE64.decode(encoded).map_err(|e| {
        TestScriptError::ExecutionError(format!(
            "Failed to base64-decode patch content for fixture '{source_id}': {e}"
        ))
    })?;

    let patch: json_patch::Patch = serde_json::from_slice(&decoded).map_err(|e| {
        TestScriptError::ExecutionError(format!(
            "Failed to parse JSON Patch document for fixture '{source_id}': {e}"
        ))
    })?;

    Ok(FHIRRequest::Patch(FHIRPatchRequest {
        resource_type: derive_resource_type(operation, Some(target), pointer.path())?,
        id: fixture_string_field(target, target_id, "id")?,
        patch,
    }))
}

fn invoke_request(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<FHIRRequest, TestScriptError> {
    let op_code = operation
        .url
        .as_ref()
        .and_then(|u| u.value.as_deref())
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Invoke operation requires url at '{}' which is used for the operation code.",
                pointer.path()
            ))
        })?;

    let fhir_operation = Operation::new(op_code);

    let source_id = require_source_id(operation, pointer.path(), "Invoke")?;
    let source = state.resolve_fixture(source_id)?;

    let Resource::Parameters(parameters) = fixture_resource(source, source_id)? else {
        return Err(TestScriptError::ExecutionError(format!(
            "Source fixture '{source_id}' is not a Parameters resource."
        )));
    };

    if let Some(target_id) = operation
        .targetId
        .as_ref()
        .and_then(|id| id.value.as_deref())
    {
        let target = state.resolve_fixture(target_id)?;

        Ok(FHIRRequest::Invocation(InvocationRequest::Instance(
            FHIRInvokeInstanceRequest {
                operation: fhir_operation,
                resource_type: derive_resource_type(operation, Some(target), pointer.path())?,
                id: fixture_string_field(target, target_id, "id")?,
                parameters,
            },
        )))
    } else if let Ok(resource_type) = derive_resource_type(operation, None, pointer.path()) {
        Ok(FHIRRequest::Invocation(InvocationRequest::Type(
            FHIRInvokeTypeRequest {
                operation: fhir_operation,
                resource_type,
                parameters,
            },
        )))
    } else {
        Ok(FHIRRequest::Invocation(InvocationRequest::System(
            FHIRInvokeSystemRequest {
                operation: fhir_operation,
                parameters,
            },
        )))
    }
}

fn get_operation(
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
) -> Result<&TestScriptSetupActionOperation, TestScriptError> {
    pointer.value().ok_or_else(|| {
        TestScriptError::ExecutionError(format!(
            "Failed to retrieve TestScript operation at '{}'.",
            pointer.path()
        ))
    })
}

fn get_operation_type(operation: &TestScriptSetupActionOperation) -> Option<&str> {
    operation
        .type_
        .as_ref()
        .and_then(|t| t.code.as_ref())
        .and_then(|c| c.value.as_deref())
}

fn require_target_id<'a>(
    operation: &'a TestScriptSetupActionOperation,
    path: &str,
    operation_name: &str,
) -> Result<&'a str, TestScriptError> {
    operation
        .targetId
        .as_ref()
        .and_then(|id| id.value.as_deref())
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "{operation_name} operation requires targetId at '{path}'."
            ))
        })
}

fn require_source_id<'a>(
    operation: &'a TestScriptSetupActionOperation,
    path: &str,
    operation_name: &str,
) -> Result<&'a str, TestScriptError> {
    operation
        .sourceId
        .as_ref()
        .and_then(|id| id.value.as_deref())
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "{operation_name} operation requires sourceId at '{path}'."
            ))
        })
}

fn fixture_string_field(
    fixture: &dyn MetaValue,
    fixture_name: &str,
    field: &str,
) -> Result<String, TestScriptError> {
    fixture
        .get_field(field)
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Fixture '{fixture_name}' does not have '{field}' field."
            ))
        })?
        .as_any()
        .downcast_ref::<String>()
        .cloned()
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Field '{field}' on fixture '{fixture_name}' is not a String."
            ))
        })
}

fn fixture_version_id(
    fixture: &dyn MetaValue,
    fixture_name: &str,
) -> Result<String, TestScriptError> {
    fixture
        .get_field("meta")
        .and_then(|meta| meta.get_field("versionId"))
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Fixture '{fixture_name}' does not have a 'versionId' field."
            ))
        })?
        .as_any()
        .downcast_ref::<FHIRId>()
        .and_then(|v| v.value.clone())
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Fixture '{fixture_name}' does not have a valid 'versionId' field."
            ))
        })
}

fn fixture_resource(
    fixture: &dyn MetaValue,
    fixture_name: &str,
) -> Result<Resource, TestScriptError> {
    (fixture as &dyn Any)
        .downcast_ref::<Resource>()
        .cloned()
        .ok_or_else(|| {
            TestScriptError::ExecutionError(format!("Fixture '{fixture_name}' is not a Resource."))
        })
}

async fn parsed_parameters(
    state: &TestState,
    root: TypedPointer<TestScript, TestScript>,
    raw: &str,
    path: &str,
    operation: &str,
) -> Result<ParsedParameters, TestScriptError> {
    let evaluated = evaluate_variable(state, root, raw).await?;

    ParsedParameters::try_from(evaluated.as_str()).map_err(|e| {
        TestScriptError::ExecutionError(format!(
            "Failed to parse parameters for {operation} operation at '{path}': {e}"
        ))
    })
}

/// Builds the headers declared by an operation's `requestHeader` entries.
///
/// Values are variable-evaluated first, so a `TestScript` may parameterize a header
/// the same way it parameterizes a URL or a search query.
async fn testscript_request_headers(
    state: &TestState,
    pointer: &TypedPointer<TestScript, TestScriptSetupActionOperation>,
    operation: &TestScriptSetupActionOperation,
) -> Result<Option<HeaderMap>, TestScriptError> {
    let Some(request_headers) = operation.requestHeader.as_ref() else {
        return Ok(None);
    };

    let mut headers = HeaderMap::with_capacity(request_headers.len());

    for request_header in request_headers {
        let field = request_header.field.value.as_deref().ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Missing requestHeader field for operation at '{}'.",
                pointer.path()
            ))
        })?;

        let raw_value = request_header.value.value.as_deref().unwrap_or_default();
        let value = evaluate_variable(state, pointer.root(), raw_value).await?;

        let name = HeaderName::try_from(field).map_err(|e| {
            TestScriptError::ExecutionError(format!(
                "Invalid requestHeader field '{field}' for operation at '{}': {e}",
                pointer.path()
            ))
        })?;

        let value = HeaderValue::from_str(&value).map_err(|e| {
            TestScriptError::ExecutionError(format!(
                "Invalid requestHeader value for '{field}' for operation at '{}': {e}",
                pointer.path()
            ))
        })?;

        headers.insert(name, value);
    }

    Ok((!headers.is_empty()).then_some(headers))
}

/// How often search is polled while waiting for a write to be indexed.
const INDEX_POLL_INTERVAL: Duration = Duration::from_millis(100);

/// The write a response records, for requests that change a resource.
fn indexed_write(response: &FHIRResponse) -> Option<IndexedWrite> {
    let (resource, deleted) = match response {
        FHIRResponse::Create(created) => (&created.resource, false),
        FHIRResponse::Update(updated) => (&updated.resource, false),
        FHIRResponse::Patch(patched) => (&patched.resource, false),
        FHIRResponse::Delete(DeleteResponse::Instance(deleted)) => (&deleted.resource, true),
        _ => return None,
    };
    let json = serde_json::to_value(resource).ok()?;
    Some(IndexedWrite {
        resource_type: ResourceType::try_from(json.get("resourceType")?.as_str()?).ok()?,
        id: json.get("id")?.as_str()?.to_string(),
        version_id: if deleted {
            None
        } else {
            Some(json.pointer("/meta/versionId")?.as_str()?.to_string())
        },
    })
}

/// Whether a request's result depends on the search index. Operations
/// count: `$everything`, `$expand` and `$viewdefinition-run` search for what
/// they return, and for one that does not the wait is one `_id` search per
/// pending write.
fn reads_search_index(request: &FHIRRequest) -> bool {
    matches!(
        request,
        FHIRRequest::Search(_)
            | FHIRRequest::Delete(DeleteRequest::Type(_) | DeleteRequest::System(_))
            | FHIRRequest::Update(UpdateRequest::Conditional(_))
            | FHIRRequest::Invocation(_)
    )
}

/// Polls search until `write` is visible (its version returned, or gone after
/// a delete) or `timeout` runs out. On timeout the caller carries on, and a
/// search that depended on the write fails its assertions as usual.
async fn wait_for_index<CTX: Clone, Client: FHIRClient<CTX, OperationOutcomeError>>(
    client: &Client,
    ctx: &CTX,
    write: &IndexedWrite,
    timeout: Duration,
) {
    let Ok(parameters) = ParsedParameters::try_from(format!("_id={}", write.id).as_str()) else {
        return;
    };
    let request = FHIRRequest::Search(SearchRequest::Type(FHIRSearchTypeRequest {
        resource_type: write.resource_type.clone(),
        parameters,
    }));
    let deadline = tokio::time::Instant::now() + timeout;

    loop {
        let versions: Vec<String> = match client.request(ctx.clone(), request.clone()).await {
            Ok(FHIRResponse::Search(SearchResponse::Type(response))) => response
                .bundle
                .entry
                .unwrap_or_default()
                .into_iter()
                .filter_map(|entry| {
                    let json = serde_json::to_value(entry.resource?).ok()?;
                    Some(json.pointer("/meta/versionId")?.as_str()?.to_string())
                })
                .collect(),
            _ => vec![],
        };
        let visible = match &write.version_id {
            Some(version_id) => versions.contains(version_id),
            None => versions.is_empty(),
        };
        if visible {
            return;
        }
        if tokio::time::Instant::now() >= deadline {
            tracing::warn!(
                resource_type = write.resource_type.as_ref(),
                id = write.id,
                "Timed out waiting for a write to be indexed"
            );
            return;
        }
        tokio::time::sleep(INDEX_POLL_INTERVAL).await;
    }
}

/// The extension that repeats an operation while its response has the status
/// in its `valueString` (such as `"202"`), as a client polls an asynchronous
/// request's status URL. Only the last response is recorded.
const POLL_EXTENSION_URL: &str =
    "https://haste.health/fhir/StructureDefinition/testscript-poll-while-response-code";

/// How long an operation is polled before the last response is taken as it is.
const POLL_TIMEOUT: Duration = Duration::from_secs(60);

/// The shortest wait between polls, and the wait without a `Retry-After`.
const POLL_INTERVAL: Duration = Duration::from_secs(1);

/// The status the operation's poll extension repeats it on, if it has one.
fn poll_while(
    operation: &TestScriptSetupActionOperation,
    path: &str,
) -> Result<Option<StatusCode>, TestScriptError> {
    let Some(extension) = operation
        .extension
        .as_ref()
        .and_then(|extensions| extensions.iter().find(|e| e.url == POLL_EXTENSION_URL))
    else {
        return Ok(None);
    };

    match &extension.value {
        Some(ExtensionValueTypeChoice::String(code)) => code
            .value
            .as_deref()
            .and_then(|code| StatusCode::from_bytes(code.trim().as_bytes()).ok()),
        _ => None,
    }
    .map(Some)
    .ok_or_else(|| {
        TestScriptError::ExecutionError(format!(
            "The poll extension on the operation at '{path}' needs a valueString holding an \
             HTTP status code."
        ))
    })
}

/// A response header's value, with repeats joined as HTTP allows (`, `).
fn header_value(recorded: &RecordedResponse, field: &str) -> Option<String> {
    let headers = &recorded.http.as_ref()?.headers;
    let values: Vec<&str> = headers
        .get_all(field)
        .iter()
        .filter_map(|value| value.to_str().ok())
        .collect();

    (!values.is_empty()).then(|| values.join(", "))
}

/// `Retry-After` in its delay-seconds form.
fn retry_after(recorded: &RecordedResponse) -> Option<Duration> {
    header_value(recorded, header::RETRY_AFTER.as_str())?
        .trim()
        .parse::<u64>()
        .ok()
        .map(Duration::from_secs)
}

async fn send_operation<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    request: &OperationRequest,
) -> RecordedResponse {
    match request {
        OperationRequest::Interaction(request) => {
            let (http, result) = client
                .request_with_metadata(ctx, request.as_ref().clone())
                .await;
            let response = match result {
                Ok(response) => Response::Interaction(Box::new(response)),
                Err(error) => Response::OperationError(Arc::new(error)),
            };

            RecordedResponse { response, http }
        }
        OperationRequest::Http { method, url } => match client.send(ctx, method.clone(), url).await
        {
            Ok((metadata, body)) => RecordedResponse {
                // A body that is not a FHIR resource (a Bulk Data manifest,
                // say) is left to the HTTP-level assertions.
                response: Response::Http(
                    serde_json::from_slice::<Resource>(&body).ok().map(Box::new),
                ),
                http: Some(metadata),
            },
            Err(error) => RecordedResponse {
                response: Response::OperationError(Arc::new(error)),
                http: None,
            },
        },
    }
}

/// Sends the operation, and while its response has the `poll_while` status
/// sends it again, waiting as long as `Retry-After` says, up to
/// [`POLL_TIMEOUT`]. Returns the last response.
async fn send_polling<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    request: &OperationRequest,
    poll_while: Option<StatusCode>,
) -> RecordedResponse {
    let Some(poll_while) = poll_while else {
        return send_operation(client, ctx, request).await;
    };
    let deadline = tokio::time::Instant::now() + POLL_TIMEOUT;

    loop {
        let recorded = send_operation(client, ctx.clone(), request).await;
        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
        if recorded.http.as_ref().map(|http| http.status) != Some(poll_while) || remaining.is_zero()
        {
            return recorded;
        }

        let wait = retry_after(&recorded)
            .unwrap_or_default()
            .max(POLL_INTERVAL)
            .min(remaining);
        tokio::time::sleep(wait).await;
    }
}

async fn run_operation<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScriptSetupActionOperation>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestResult<TestReportSetupActionOperation>, TestScriptError> {
    let operation = pointer.value().ok_or_else(|| {
        TestScriptError::ExecutionError(format!(
            "Failed to retrieve TestScript operation at '{}'.",
            pointer.path()
        ))
    })?;

    let mut state_guard = state.lock().await;
    let request = testscript_operation_to_request(&state_guard, &pointer).await?;

    if let Some(timeout) = options.index_wait_timeout
        && let OperationRequest::Interaction(fhir_request) = &request
        && reads_search_index(fhir_request)
        && !state_guard.unindexed_writes.is_empty()
    {
        // One deadline for the whole set: the worker indexes them together.
        let deadline = tokio::time::Instant::now() + timeout;
        for write in std::mem::take(&mut state_guard.unindexed_writes) {
            let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
            if remaining.is_zero() {
                break;
            }
            wait_for_index(client, &ctx, &write, remaining).await;
        }
    }

    let ctx = match testscript_request_headers(&state_guard, &pointer, operation).await? {
        Some(headers) => ctx.with_request_headers(headers),
        None => ctx,
    };

    let poll_while = poll_while(operation, pointer.path())?;
    let recorded = send_polling(client, ctx, &request, poll_while).await;

    if let Some(wait_duration) = options.wait_between_operations {
        tokio::time::sleep(wait_duration).await;
    }

    let failure = match &recorded.response {
        Response::Interaction(response) => {
            if let Some(write) = indexed_write(response) {
                // Search returns only a resource's current version, so an
                // earlier write of the same resource could never be seen.
                state_guard.unindexed_writes.retain(|earlier| {
                    (&earlier.resource_type, &earlier.id) != (&write.resource_type, &write.id)
                });
                state_guard.unindexed_writes.push(write);
            }
            None
        }
        Response::OperationError(error) => Some(error.to_string()),
        Response::Http(_) => recorded
            .http
            .as_ref()
            .filter(|http| !http.status.is_success())
            .map(|http| format!("HTTP {}", http.status)),
    };

    let fhir_request = match request {
        OperationRequest::Interaction(request) => Some(*request),
        OperationRequest::Http { .. } => None,
    };
    associate_request_response_variables(&mut state_guard, operation, fhir_request, recorded);
    drop(state_guard);

    let value = match failure {
        None => TestReportSetupActionOperation {
            result: ReportActionResultCodes::pass(),
            ..Default::default()
        },
        Some(failure) => {
            tracing::warn!(
                path = pointer.path(),
                operation.label = operation
                    .label
                    .as_ref()
                    .and_then(|l| l.value.as_deref())
                    .unwrap_or("<no-label>"),
                operation.operation_type = get_operation_type(operation).unwrap_or("<unknown>"),
                error = %failure,
                "TestScript operation failed"
            );

            TestReportSetupActionOperation {
                result: ReportActionResultCodes::warning(),
                message: Some(Box::new(FHIRMarkdown {
                    value: Some(format!("Operation failed: {failure}")),
                    ..Default::default()
                })),
                ..Default::default()
            }
        }
    };

    Ok(TestResult {
        state: state.clone(),
        value,
    })
}

fn get_source<'a>(
    state: &'a TestState,
    assertion: &TestScriptSetupActionAssert,
) -> Result<Option<&'a dyn MetaValue>, TestScriptError> {
    if let Some(source_id) = assertion.sourceId.as_ref().and_then(|id| id.value.as_ref()) {
        let source = state.resolve_fixture(source_id)?;
        Ok(Some(source))
    } else {
        match assertion
            .direction
            .as_ref()
            .unwrap_or(&AssertDirectionCodes::response())
        {
            assertion if assertion == &AssertDirectionCodes::request() => {
                if let Some(request) = state.latest_request.as_ref() {
                    request_to_meta_value(request)
                        .ok_or_else(|| TestScriptError::InvalidFixture)
                        .map(Some)
                } else {
                    Ok(None)
                }
            }
            assertion if assertion == &AssertDirectionCodes::response() => {
                if let Some(recorded) = state.latest_response.as_ref() {
                    response_to_meta_value(&recorded.response)
                        .ok_or_else(|| TestScriptError::InvalidFixture)
                        .map(Some)
                } else {
                    Ok(None)
                }
            }
            _ => Err(TestScriptError::ExecutionError(
                "Assert direction cannot be 'null' when sourceId is not provided.".to_string(),
            )),
        }
    }
}

fn evaluate_operator(
    operator: &BoundCode<AssertOperatorCodes>,
    a: &Vec<conversion::ConvertedValue>,
    b: &Vec<conversion::ConvertedValue>,
) -> bool {
    match operator {
        operator
            if operator == &AssertOperatorCodes::equals()
                || operator == &AssertOperatorCodes::null() =>
        {
            a == b
        }
        operator if operator == &AssertOperatorCodes::not_equals() => !(a == b),

        operator if operator == &AssertOperatorCodes::contains() => {
            if a.len() != 1 || b.len() != 1 {
                return false;
            }

            match (&a[0], &b[0]) {
                (ConvertedValue::String(a_str), ConvertedValue::String(b_str)) => {
                    a_str.contains(b_str)
                }
                _ => false,
            }
        }
        operator if operator == &AssertOperatorCodes::empty() => {
            todo!("Empty operator not implemented")
        }
        operator if operator == &AssertOperatorCodes::eval() => {
            todo!("Eval operator not implemented")
        }
        operator if operator == &AssertOperatorCodes::greater_than() => {
            todo!("GreaterThan operator not implemented")
        }
        operator if operator == &AssertOperatorCodes::in_() => todo!("In operator not implemented"),
        operator if operator == &AssertOperatorCodes::less_than() => {
            todo!("LessThan operator not implemented")
        }
        operator if operator == &AssertOperatorCodes::not_contains() => {
            todo!("NotContains operator not implemented")
        }
        operator if operator == &AssertOperatorCodes::not_empty() => {
            todo!("NotEmpty operator not implemented")
        }
        operator if operator == &AssertOperatorCodes::not_in() => {
            todo!("NotIn operator not implemented")
        }
        _ => {
            todo!("Operator '{:?}' not implemented", operator)
        }
    }
    // a == b
}

async fn derive_comparison_to(
    state: &TestState,
    assertion: &TestScriptSetupActionAssert,
) -> Result<Vec<ConvertedValue>, TestScriptError> {
    if let Some(comparision_fixture_id) = assertion
        .compareToSourceId
        .as_ref()
        .and_then(|c| c.value.as_ref())
    {
        let comparison_fixture = state.resolve_fixture(comparision_fixture_id)?;

        let Some(comparison_expression) = assertion
            .compareToSourceExpression
            .as_ref()
            .and_then(|exp| exp.value.as_ref())
        else {
            return Err(TestScriptError::ExecutionError(
                "compareToSourceExpression is required when compareToSourceId is provided."
                    .to_string(),
            ));
        };

        let result = state
            .fp_engine
            .evaluate(comparison_expression, vec![comparison_fixture])
            .await
            .map_err(|e| {
                TestScriptError::ExecutionError(format!(
                    "FHIRPath evaluation error for comparison fixture '{comparision_fixture_id}': {e}"
                ))
            })?;

        Ok(result
            .iter()
            .map(conversion::convert_meta_value)
            .collect::<Vec<_>>())
    } else if let Some(value) = assertion.value.as_ref().and_then(|v| v.value.as_ref())
        && let Some(converted_value) = conversion::convert_string_value(value.as_ref())
    {
        Ok(vec![converted_value])
    } else {
        Err(TestScriptError::ExecutionError(
            "Failed to derive comparison value for assertion.".to_string(),
        ))
    }
}

/// Assertions carry a `label`/`description` intended by the FHIR spec for
/// exactly this purpose: identifying an assertion in test engine output.
fn assert_label(assertion: &TestScriptSetupActionAssert) -> &str {
    assertion
        .label
        .as_ref()
        .and_then(|l| l.value.as_deref())
        .or_else(|| {
            assertion
                .description
                .as_ref()
                .and_then(|d| d.value.as_deref())
        })
        .unwrap_or("<no-label>")
}

/// Assertions are what determine the testreports ultimate pass/fail status.
/// So set that within state here depending on assertion success/failure.
async fn run_assertion(
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScriptSetupActionAssert>,
) -> Result<TestResult<TestReportSetupActionAssert>, TestScriptError> {
    let assertion = pointer.value().ok_or_else(|| {
        TestScriptError::ExecutionError(format!(
            "Failed to retrieve TestScript assertion at '{}'.",
            pointer.path()
        ))
    })?;

    let mut state_guard = state.lock().await;

    let default = AssertOperatorCodes::equals();
    let operator = assertion.operator.as_ref().unwrap_or(&default);

    // Keep all uses of `source` inside this scope so the immutable borrow
    // of `state_guard` ends before we mutate `state_guard`.
    let failure_message = if let Some(message) =
        evaluate_http_assertion(&state_guard, assertion, pointer.path(), operator)?
    {
        Some(message)
    } else if assertion.resource.is_some() || assertion.expression.is_some() {
        let Some(source) = get_source(&state_guard, assertion)? else {
            return Err(TestScriptError::ExecutionError(format!(
                "Failed to resolve source for assertion at '{}'.",
                pointer.path()
            )));
        };

        if let Some(message) =
            evaluate_resource_assertion(assertion, pointer.path(), source, operator)
        {
            Some(message)
        } else if let Some(expression) =
            assertion.expression.as_ref().and_then(|e| e.value.as_ref())
        {
            evaluate_expression_assertion(
                &state_guard,
                assertion,
                pointer.path(),
                source,
                operator,
                expression,
            )
            .await?
        } else {
            None
        }
    } else {
        None
    };

    let (result, message) = match failure_message {
        Some(message) => {
            tracing::error!(
                assert.label = assert_label(assertion),
                path = pointer.path(),
                "{message}"
            );

            state_guard.result = ReportResultCodes::fail();

            (
                ReportActionResultCodes::fail(),
                Some(Box::new(FHIRMarkdown {
                    value: Some(message),
                    ..Default::default()
                })),
            )
        }
        None => (ReportActionResultCodes::pass(), None),
    };

    Ok(TestResult {
        state: state.clone(),
        value: TestReportSetupActionAssert {
            result,
            message,
            ..Default::default()
        },
    })
}

/// The status code an assertion's `response` code stands for.
fn response_code_status(code: &str) -> Option<u16> {
    Some(match code {
        "okay" => 200,
        "created" => 201,
        "noContent" => 204,
        "notModified" => 304,
        "bad" => 400,
        "forbidden" => 403,
        "notFound" => 404,
        "methodNotAllowed" => 405,
        "conflict" => 409,
        "gone" => 410,
        "preconditionFailed" => 412,
        "unprocessable" => 422,
        _ => return None,
    })
}

/// Compares an HTTP value (a status code or a header, `None` when absent)
/// with an assertion's expected value under its operator, or `None` for an
/// operator that does not apply. `in` and `notIn` take a comma-separated list.
fn compare_http_value(operator: &str, actual: Option<&str>, expected: &str) -> Option<bool> {
    let listed = || {
        expected
            .split(',')
            .map(str::trim)
            .any(|item| Some(item) == actual)
    };
    let contains = actual.is_some_and(|actual| actual.contains(expected));

    Some(match operator {
        "equals" => actual == Some(expected),
        "notEquals" => actual != Some(expected),
        "in" => listed(),
        "notIn" => !listed(),
        "contains" => contains,
        "notContains" => !contains,
        "empty" => actual.is_none_or(str::is_empty),
        "notEmpty" => actual.is_some_and(|actual| !actual.is_empty()),
        _ => return None,
    })
}

/// An assertion's HTTP-level check, if it has one: `responseCode`,
/// `response`, `headerField` (against `value`) or `contentType`, made on the
/// response `sourceId` names or the latest one. An assertion holds at most one
/// check (invariants tst-5 and tst-6). Returns the failure.
fn evaluate_http_assertion(
    state: &TestState,
    assertion: &TestScriptSetupActionAssert,
    path: &str,
    operator: &BoundCode<AssertOperatorCodes>,
) -> Result<Option<String>, TestScriptError> {
    let response_code = assertion
        .responseCode
        .as_ref()
        .and_then(|code| code.value.as_deref());
    let response = assertion.response.as_ref().and_then(BoundCode::as_str);
    let header_field = assertion
        .headerField
        .as_ref()
        .and_then(|field| field.value.as_deref());
    let content_type = assertion
        .contentType
        .as_ref()
        .and_then(|content_type| content_type.value.as_deref());

    if response_code.is_none()
        && response.is_none()
        && header_field.is_none()
        && content_type.is_none()
    {
        return Ok(None);
    }

    let label = assert_label(assertion);
    let error = |message: String| {
        TestScriptError::ExecutionError(format!("Assertion '{label}' at '{path}': {message}"))
    };
    if assertion.direction.as_ref() == Some(&AssertDirectionCodes::request()) {
        return Err(error(
            "responseCode, response, headerField and contentType are checked against \
             responses only."
                .to_string(),
        ));
    }

    let source_id = assertion
        .sourceId
        .as_ref()
        .and_then(|id| id.value.as_deref());
    let recorded = state.resolve_response(source_id)?;
    let Some(http) = recorded.http.as_ref() else {
        return Ok(Some(format!(
            "Assertion '{label}' at '{path}' failed: no HTTP response arrived."
        )));
    };
    let status = http.status.as_u16().to_string();

    // What is checked, its actual value, and the expected one.
    let (what, actual, expected) = if let Some(code) = response_code {
        ("response code".to_string(), Some(status), code.to_string())
    } else if let Some(code) = response {
        let expected = response_code_status(code)
            .ok_or_else(|| error(format!("unknown response code '{code}'.")))?;
        (
            format!("response code (for '{code}')"),
            Some(status),
            expected.to_string(),
        )
    } else if let Some(field) = header_field {
        let expected = assertion
            .value
            .as_ref()
            .and_then(|value| value.value.as_deref())
            .unwrap_or_default();
        (
            format!("header '{field}'"),
            header_value(recorded, field),
            expected.to_string(),
        )
    } else {
        // The media type alone, without parameters such as `charset`.
        let actual = header_value(recorded, header::CONTENT_TYPE.as_str()).map(|value| {
            value
                .split(';')
                .next()
                .unwrap_or_default()
                .trim()
                .to_ascii_lowercase()
        });
        (
            "content type".to_string(),
            actual,
            content_type.unwrap_or_default().to_ascii_lowercase(),
        )
    };

    let operator = operator.as_str().unwrap_or("equals");
    let passed = compare_http_value(operator, actual.as_deref(), &expected).ok_or_else(|| {
        error(format!(
            "operator '{operator}' is not supported for responseCode, response, headerField \
             or contentType."
        ))
    })?;
    if passed {
        return Ok(None);
    }

    let actual = actual.map_or_else(|| "absent".to_string(), |actual| format!("'{actual}'"));
    let expected = match operator {
        "empty" | "notEmpty" => String::new(),
        _ => format!(" '{expected}'"),
    };
    Ok(Some(format!(
        "Assertion '{label}' at '{path}' failed: {what} was {actual}, expected {operator}{expected}."
    )))
}

fn evaluate_resource_assertion(
    assertion: &TestScriptSetupActionAssert,
    path: &str,
    source: &dyn MetaValue,
    operator: &BoundCode<AssertOperatorCodes>,
) -> Option<String> {
    let resource_string = assertion.resource.as_ref()?.as_str()?;

    let operation_evaluation_result = evaluate_operator(
        operator,
        &vec![conversion::ConvertedValue::String(
            resource_string.to_string(),
        )],
        &vec![conversion::ConvertedValue::String(
            source.fhir_type().to_string(),
        )],
    );

    if operation_evaluation_result {
        return None;
    }

    Some(format!(
        "Assertion '{}' at '{}' failed: resource type '{resource_string}' does not match '{}'.",
        assert_label(assertion),
        path,
        source.fhir_type()
    ))
}

async fn evaluate_expression_assertion(
    state_guard: &TestState,
    assertion: &TestScriptSetupActionAssert,
    path: &str,
    source: &dyn MetaValue,
    operator: &BoundCode<AssertOperatorCodes>,
    expression: &str,
) -> Result<Option<String>, TestScriptError> {
    let comparison_to = derive_comparison_to(state_guard, assertion).await?;

    let Ok(result) = state_guard
        .fp_engine
        .evaluate(expression, vec![source])
        .await
    else {
        tracing::error!(
            assert.label = assert_label(assertion),
            path = path,
            expression = expression,
            "Assertion '{}' at '{}' failed: FHIRPath expression '{expression}' failed to evaluate.",
            assert_label(assertion),
            path,
        );

        return Err(TestScriptError::ExecutionError(format!(
            "Assertion '{}' at '{}': FHIRPath expression '{expression}' failed to evaluate.",
            assert_label(assertion),
            path,
        )));
    };

    let converted_values = result
        .iter()
        .map(conversion::convert_meta_value)
        .collect::<Vec<_>>();

    let operation_evaluation_result =
        evaluate_operator(operator, &converted_values, &comparison_to);

    if operation_evaluation_result {
        return Ok(None);
    }

    Ok(Some(format!(
        "Assertion '{}' at '{}' failed: '{converted_values:?}' {operator:?} '{comparison_to:?}'.",
        assert_label(assertion),
        path,
    )))
}

async fn run_action<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScriptTestAction>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestResult<TestReportSetupAction>, TestScriptError> {
    tracing::info!("Running TestScript action at path: {}", pointer.path());
    let action = pointer.value().ok_or_else(|| {
        TestScriptError::ExecutionError(format!(
            "Failed to retrieve TestScript action at '{}'.",
            pointer.path()
        ))
    })?;

    // Should be either an operation or an assert.
    // Both should not exist at the same time.
    if action.operation.is_some() {
        let Some(operation_pointer) =
            pointer.descend::<TestScriptSetupActionOperation>(&Key::Field("operation".to_string()))
        else {
            return Err(TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript operation at '{}'.",
                pointer.path()
            )));
        };

        let result = run_operation(client, ctx, state, operation_pointer, options).await?;

        Ok(TestResult {
            state: result.state,
            value: TestReportSetupAction {
                operation: Some(result.value),
                ..Default::default()
            },
        })
    } else if action.assert.is_some() {
        let Some(assertion_pointer) =
            pointer.descend::<TestScriptSetupActionAssert>(&Key::Field("assert".to_string()))
        else {
            return Err(TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript assertion at '{}'.",
                pointer.path()
            )));
        };

        let assertion = run_assertion(state, assertion_pointer).await?;

        Ok(TestResult {
            state: assertion.state,
            value: TestReportSetupAction {
                assert: Some(assertion.value),
                ..Default::default()
            },
        })
    } else {
        Err(TestScriptError::ExecutionError(format!(
            "TestScript action must have either an operation or an assert at '{}'.",
            pointer.path()
        )))
    }
}

async fn run_setup_action<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScriptSetupAction>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestResult<TestReportSetupAction>, TestScriptError> {
    let action = pointer.value().ok_or_else(|| {
        TestScriptError::ExecutionError(format!(
            "Failed to retrieve TestScript action at '{}'.",
            pointer.path()
        ))
    })?;

    tracing::info!("Running TestScript action at path: {}", pointer.path());

    // Should be either an operation or an assert.
    // Both should not exist at the same time.
    if action.operation.is_some() {
        let Some(operation_pointer) =
            pointer.descend::<TestScriptSetupActionOperation>(&Key::Field("operation".to_string()))
        else {
            return Err(TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript operation at '{}'.",
                pointer.path()
            )));
        };

        let result = run_operation(client, ctx, state, operation_pointer, options).await?;

        Ok(TestResult {
            state: result.state,
            value: TestReportSetupAction {
                operation: Some(result.value),
                ..Default::default()
            },
        })
    } else if action.assert.is_some() {
        let Some(assertion_pointer) =
            pointer.descend::<TestScriptSetupActionAssert>(&Key::Field("assert".to_string()))
        else {
            return Err(TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript assertion at '{}'.",
                pointer.path()
            )));
        };

        let assertion = run_assertion(state, assertion_pointer).await?;

        Ok(TestResult {
            state: assertion.state,
            value: TestReportSetupAction {
                assert: Some(assertion.value),
                ..Default::default()
            },
        })
    } else {
        Err(TestScriptError::ExecutionError(format!(
            "TestScript action must have either an operation or an assert at '{}'.",
            pointer.path()
        )))
    }
}

async fn setup_fixtures<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScript>,
    _options: Arc<TestRunnerOptions>,
) -> Result<Arc<Mutex<TestState>>, OperationOutcomeError> {
    let mut state_lock = state.lock().await;

    let Some(fixtures_pointer) =
        pointer.descend::<Vec<TestScriptFixture>>(&Key::Field("fixture".to_string()))
    else {
        return Ok(state.clone());
    };

    let Some(fixtures) = fixtures_pointer.value() else {
        return Ok(state.clone());
    };

    for fixture in fixtures {
        if let Some(reference_string) = fixture
            .resource
            .as_ref()
            .and_then(|r| r.reference.as_ref())
            .and_then(|refe| refe.value.as_ref())
        {
            let resolved_resource = if reference_string.starts_with('#')
                && let Some(contained) =
                    pointer.descend::<Vec<Resource>>(&Key::Field("contained".to_string()))
                && let Some(contained) = contained.value()
            {
                let local_id = &reference_string[1..];
                let Some(resource) = contained.iter().find(|res| {
                    if let Some(id) = res.get_field("id")
                        && let Some(id) = id.as_any().downcast_ref::<String>()
                    {
                        id.as_str() == local_id
                    } else {
                        false
                    }
                }) else {
                    return Err(OperationOutcomeError::error(
                        IssueType::not_found(),
                        format!("Contained resource with id '{local_id}' not found."),
                    ));
                };

                resource.clone()
            } else {
                let parts = reference_string.split('/').collect::<Vec<&str>>();
                if parts.len() != 2 {
                    return Err(OperationOutcomeError::error(
                        IssueType::invalid(),
                        format!("Invalid fixture reference: {reference_string}"),
                    ));
                }

                let resource_type = parts[0];
                let id = parts[1];

                let Some(remote_resource) = client
                    .read(
                        ctx.clone(),
                        ResourceType::try_from(resource_type).map_err(|_| {
                            OperationOutcomeError::error(
                                IssueType::invalid(),
                                format!(
                                    "Invalid resource type in fixture reference: '{resource_type}'"
                                ),
                            )
                        })?,
                        id.to_string(),
                    )
                    .await?
                else {
                    return Err(OperationOutcomeError::error(
                        IssueType::not_found(),
                        format!("Resource '{resource_type}' with id '{id}' not found."),
                    ));
                };

                remote_resource
            };

            state_lock.fixtures.insert(
                fixture.id.clone().unwrap_or_default(),
                Fixtures::Resource(resolved_resource),
            );
        }
    }

    drop(state_lock);

    Ok(state)
}

async fn run_setup<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScriptSetup>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestResult<TestReportSetup>, TestScriptError> {
    let mut cur_state = state;

    let mut setup_results = TestReportSetup {
        action: vec![],
        ..Default::default()
    };

    let Some(setup) = pointer.value() else {
        return Ok(TestResult {
            state: cur_state,
            value: setup_results,
        });
    };

    for action in setup.action.iter().enumerate() {
        let action_pointer = pointer
            .descend::<Vec<TestScriptSetupAction>>(&Key::Field("action".to_string()))
            .and_then(|p| p.descend::<TestScriptSetupAction>(&Key::Index(action.0)));

        let action_pointer = action_pointer.ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript action at index {}.",
                action.0
            ))
        })?;

        let result = run_setup_action(
            client,
            ctx.clone(),
            cur_state,
            action_pointer,
            options.clone(),
        )
        .await?;
        cur_state = result.state;

        setup_results.action.push(result.value);
    }

    Ok(TestResult {
        state: cur_state,
        value: setup_results,
    })
}

async fn run_teardown<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScriptTeardown>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestResult<TestReportTeardown>, TestScriptError> {
    let mut cur_state = state;

    let mut teardown_results = TestReportTeardown {
        action: vec![],
        ..Default::default()
    };

    let Some(actions) = pointer.value() else {
        return Ok(TestResult {
            state: cur_state,
            value: teardown_results,
        });
    };

    for action in actions.action.iter().enumerate() {
        let action_pointer = pointer
            .descend::<Vec<TestScriptTeardownAction>>(&Key::Field("action".to_string()))
            .and_then(|p| p.descend::<TestScriptTeardownAction>(&Key::Index(action.0)));

        let action_pointer = action_pointer.ok_or_else(|| {
            TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript teardown action at index {}.",
                action.0
            ))
        })?;

        let operation_pointer = action_pointer
            .descend::<TestScriptSetupActionOperation>(&Key::Field("operation".to_string()))
            .ok_or_else(|| {
                TestScriptError::ExecutionError(format!(
                    "Failed to retrieve TestScript teardown operation at index {}.",
                    action.0
                ))
            })?;

        let result = run_operation(
            client,
            ctx.clone(),
            cur_state,
            operation_pointer,
            options.clone(),
        )
        .await?;
        cur_state = result.state;

        teardown_results.action.push(TestReportTeardownAction {
            operation: result.value,
            ..Default::default()
        });
    }

    Ok(TestResult {
        state: cur_state,
        value: teardown_results,
    })
}

async fn run_test<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, TestScriptTest>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestResult<TestReportTest>, TestScriptError> {
    let mut cur_state = state;
    let mut test_report_test = TestReportTest {
        action: vec![],
        ..Default::default()
    };

    let test = pointer.value().ok_or_else(|| {
        TestScriptError::ExecutionError(format!(
            "Failed to retrieve TestScript test at '{}'.",
            pointer.path()
        ))
    })?;

    for action in test.action.iter().enumerate() {
        let Some(action_pointer) = pointer
            .descend::<Vec<TestScriptTestAction>>(&Key::Field("action".to_string()))
            .and_then(|p| p.descend(&Key::Index(action.0)))
        else {
            return Err(TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript test action at index {}.",
                action.0
            )));
        };
        let state = cur_state.clone();
        let result = run_action(
            client,
            ctx.clone(),
            cur_state,
            action_pointer.clone(),
            options.clone(),
        )
        .await;
        let result = match result {
            Ok(result) => result,
            // An action that cannot run (a read of a fixture the failed create
            // before it never produced, say) fails its test instead of ending
            // the run with no report: the error becomes the action's result
            // and the test's remaining actions are skipped.
            Err(TestScriptError::ExecutionError(message)) => {
                tracing::error!(
                    path = action_pointer.path(),
                    "TestScript action could not run: {message}"
                );
                state.lock().await.result = ReportResultCodes::fail();
                test_report_test.action.push(TestReportTestAction {
                    operation: Some(TestReportSetupActionOperation {
                        result: ReportActionResultCodes::error(),
                        message: Some(Box::new(FHIRMarkdown {
                            value: Some(message),
                            ..Default::default()
                        })),
                        ..Default::default()
                    }),
                    ..Default::default()
                });
                return Ok(TestResult {
                    state,
                    value: test_report_test,
                });
            }
            Err(e) => return Err(e),
        };
        cur_state = result.state;
        test_report_test.action.push(TestReportTestAction {
            operation: result.value.operation,
            assert: result.value.assert,
            ..Default::default()
        });
    }

    Ok(TestResult {
        state: cur_state,
        value: test_report_test,
    })
}

async fn run_tests<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    state: Arc<Mutex<TestState>>,
    pointer: TypedPointer<TestScript, Vec<TestScriptTest>>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestResult<Vec<TestReportTest>>, TestScriptError> {
    let mut test_results = vec![];
    let mut cur_state = state;

    let Some(tests) = pointer.value() else {
        return Ok(TestResult {
            state: cur_state,
            value: test_results,
        });
    };

    for test in tests.iter().enumerate() {
        let Some(test_pointer) = pointer.descend(&Key::Index(test.0)) else {
            return Err(TestScriptError::ExecutionError(format!(
                "Failed to retrieve TestScript test at index {}.",
                test.0
            )));
        };
        let test_result = run_test(
            client,
            ctx.clone(),
            cur_state,
            test_pointer,
            options.clone(),
        )
        .await?;
        cur_state = test_result.state;
        test_results.push(test_result.value);
    }

    Ok(TestResult {
        state: cur_state,
        value: test_results,
    })
}

pub struct TestRunnerOptions {
    pub wait_between_operations: Option<Duration>,
    /// Before a request that reads the search index (a search, an operation,
    /// a conditional delete or a conditional update), wait up to this long
    /// for the latest writes to be indexed. Waits only as long as indexing
    /// takes, where `wait_between_operations` waits a fixed time after every
    /// operation.
    pub index_wait_timeout: Option<Duration>,
}

/// Runs a FHIR `TestScript` using the provided client and execution context.
///
/// This executes the `TestScript` lifecycle:
/// - fixture setup
/// - setup actions
/// - test actions
/// - teardown actions
///
/// # Errors
///
/// Returns [`TestScriptError`] if:
/// - fixture setup fails
/// - setup actions fail
/// - test execution fails
/// - teardown execution fails
/// - an operation performed by the FHIR client fails
#[tracing::instrument(
    name = "testscript_run",
    skip_all,
    fields(
        testscript.id = test_script.id.as_deref().unwrap_or("<no-id>"),
        testscript.name = test_script.name.value.as_deref().unwrap_or("<unnamed>"),
        testscript.url = test_script.url.value.as_deref().unwrap_or("<no-url>"),
    )
)]
pub async fn run<CTX: Clone + WithRequestHeaders, Client: FHIRHttpExchange<CTX>>(
    client: &Client,
    ctx: CTX,
    test_script: Arc<TestScript>,
    options: Arc<TestRunnerOptions>,
) -> Result<TestReport, TestScriptError> {
    tracing::info!("Starting TestScript run");

    let mut test_report = TestReport {
        status: ReportStatusCodes::completed(),
        testScript: Box::new(Reference {
            reference: Some(Box::new(FHIRString {
                value: Some(format!(
                    "Testscript/{}",
                    test_script.id.clone().unwrap_or_default()
                )),
                ..Default::default()
            })),
            ..Default::default()
        }),
        ..Default::default()
    };

    let mut state = Arc::new(Mutex::new(TestState::new()));
    let pointer = TypedPointer::<TestScript, TestScript>::new(test_script);

    state = setup_fixtures(client, ctx.clone(), state, pointer.clone(), options.clone())
        .await
        .map_err(TestScriptError::OperationError)?;

    let mut running_state = Ok(());

    // Run setup actions
    if let Some(setup_pointer) =
        pointer.descend::<TestScriptSetup>(&Key::Field("setup".to_string()))
    {
        tracing::info!("Running TestScript setup...");
        let setup_result = run_setup(
            client,
            ctx.clone(),
            state.clone(),
            setup_pointer,
            options.clone(),
        )
        .await;
        match setup_result {
            Ok(res) => {
                state = res.state;
                test_report.setup = Some(res.value);
            }
            Err(e) => {
                tracing::error!(phase = "setup", error = ?e, "TestScript run failed during setup");
                running_state = Err(e);
            }
        }
    }

    // Run Test actions
    if running_state.is_ok()
        && let Some(test_pointer) =
            pointer.descend::<Vec<TestScriptTest>>(&Key::Field("test".to_string()))
    {
        tracing::info!("Running TestScript tests...");
        let test_result = run_tests(
            client,
            ctx.clone(),
            state.clone(),
            test_pointer,
            options.clone(),
        )
        .await;

        match test_result {
            Ok(res) => {
                state = res.state;
                test_report.test = Some(res.value);
            }

            Err(e) => {
                tracing::error!(phase = "test", error = ?e, "TestScript run failed during test execution");
                running_state = Err(e);
            }
        }
    }

    if let Some(teardown_pointer) =
        pointer.descend::<TestScriptTeardown>(&Key::Field("teardown".to_string()))
    {
        tracing::info!("Running TestScript teardown...");

        let result = run_teardown(
            client,
            ctx.clone(),
            state.clone(),
            teardown_pointer,
            options.clone(),
        )
        .await?;

        // state = result.state;
        test_report.teardown = Some(result.value);
    }

    running_state?;

    let state_guard = state.lock().await;
    // Only set result to fail so if still pending can assume pass.
    // Flip to fail in assertion tests if any fail.
    match &state_guard.result {
        state if state == &ReportResultCodes::pending() => {
            test_report.result = ReportResultCodes::pass();
        }
        status => test_report.result = status.clone(),
    }

    if test_report.result == ReportResultCodes::fail() {
        tracing::error!(result = ?test_report.result, "TestScript run finished with failures");
    } else {
        tracing::info!(result = ?test_report.result, "TestScript run finished");
    }

    Ok(test_report)
}

#[cfg(test)]
mod tests {
    use super::*;
    use haste_fhir_client::request::{FHIRCreateResponse, FHIRDeleteInstanceResponse};

    fn patient(id: &str, version_id: &str) -> Resource {
        serde_json::from_value(serde_json::json!({
            "resourceType": "Patient",
            "id": id,
            "meta": { "versionId": version_id }
        }))
        .expect("valid Patient")
    }

    #[test]
    fn writes_record_the_version_search_must_return() {
        let created = FHIRResponse::Create(FHIRCreateResponse {
            resource: patient("p1", "v1"),
        });
        let write = indexed_write(&created).expect("a create is a write");
        assert_eq!(write.resource_type, ResourceType::Patient);
        assert_eq!(write.id, "p1");
        assert_eq!(write.version_id.as_deref(), Some("v1"));

        // A delete must be gone from search, whatever version it was.
        let deleted = FHIRResponse::Delete(DeleteResponse::Instance(Box::new(
            FHIRDeleteInstanceResponse {
                resource: patient("p1", "v2"),
            },
        )));
        assert_eq!(
            indexed_write(&deleted)
                .expect("a delete is a write")
                .version_id,
            None
        );
    }

    #[test]
    fn only_index_backed_requests_wait() {
        let search = FHIRRequest::Search(SearchRequest::Type(FHIRSearchTypeRequest {
            resource_type: ResourceType::Patient,
            parameters: ParsedParameters::try_from("_tag=x").unwrap(),
        }));
        assert!(reads_search_index(&search));

        let read = FHIRRequest::Read(FHIRReadRequest {
            resource_type: ResourceType::Patient,
            id: "p1".to_string(),
        });
        assert!(!reads_search_index(&read), "a read goes to the repository");
    }
}