Add capability to log CQL evaluation results during Measure integration testing to help debug (#1006)

Add logEvaluationResults() to measure testing framework for CQL debugging

Thread CQL EvaluationResult objects through the Measure and MultiMeasure
test DSLs so they are accessible from SelectedMeasureDef and
SelectedMeasureDefCollection. Add logEvaluationResults() on
SelectedMeasureDef and logAllMeasureEvaluationResults() on
SelectedMeasureDefCollection to pretty-print evaluation results per
subject, with separator lines for readability. This mirrors the existing
logReportJson() pattern on SelectedMeasureReport.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lukedegruchy

.claude/skills/measure-testing-framework.md

@@ -42,8 +42,8 @@ public interface Selector<T, S> { T select(S from); }
 
 ### Return Records (test infrastructure)
 
-- **`MeasureDefAndR4MeasureReport`**: Pairs a single `MeasureDef` with a single `MeasureReport` (used by `Measure`)
-- **`MeasureDefAndR4ParametersWithMeasureReports`**: Pairs `List<MeasureDef>` with `Parameters` containing bundled `MeasureReport`s (used by `MultiMeasure`)
+- **`MeasureDefAndR4MeasureReport`**: Pairs a single `MeasureDef` with a single `MeasureReport` and `Map<String, EvaluationResult>` (used by `Measure`)
+- **`MeasureDefAndR4ParametersWithMeasureReports`**: Pairs `List<MeasureDef>` with `Parameters` containing bundled `MeasureReport`s and `Map<MeasureDef, Map<String, EvaluationResult>>` evaluation results per measure (used by `MultiMeasure`)
 
 ## Given Phase - Test Setup
 
@@ -405,6 +405,9 @@ All classes in `selected/def/` extend `Measure.Selected<T, P>`.
 .group("groupId")                          -> SelectedMeasureDefGroup (by ID)
 .group(0)                                  -> SelectedMeasureDefGroup (by index)
 
+// Logging (debug aid, similar to SelectedMeasureReport.logReportJson())
+.logEvaluationResults()                    // Logs formatted CQL evaluation results (per subject) at INFO level
+
 // Assertions
 .hasNoErrors()
 .hasErrors(2)
@@ -421,6 +424,10 @@ All classes in `selected/def/` extend `Measure.Selected<T, P>`.
 **Parent**: generic `<P>` (used by `MultiMeasure.Then`)
 
 ```java
+// Logging (debug aid)
+.logAllMeasureEvaluationResults()          // Logs formatted CQL evaluation results for ALL measures at once
+
+// Navigation
 .hasCount(3)
 .first()                                   -> SelectedMeasureDef
 .get(0)                                    -> SelectedMeasureDef (by index)

cqf-fhir-cr/src/main/java/org/opencds/cqf/fhir/cr/measure/common/EvaluationResultFormatter.java

@@ -24,6 +24,7 @@ public class EvaluationResultFormatter {
     private static final String DATE_FORMAT = "yyyy-MM-dd";
     private static final String DATE_TIME_FORMAT = "yyyy-MM-dd:HH:mm:ss";
     private static final String INDENT = "  ";
+    private static final String SEPARATOR = "----------------------------------------";
 
     private EvaluationResultFormatter() {
         // Static utility class
@@ -217,6 +218,38 @@ private static String indent(int level) {
         return INDENT.repeat(Math.max(0, level));
     }
 
+    /**
+     * Formats evaluation results for a single measure, with separator lines between subjects.
+     *
+     * @param measureId the measure ID for the header
+     * @param evaluationResults map of subject ID to EvaluationResult
+     * @return formatted string
+     */
+    public static String formatMeasureEvaluationResults(
+            String measureId, Map<String, EvaluationResult> evaluationResults) {
+        StringBuilder sb = new StringBuilder();
+        sb.append(SEPARATOR).append("\n");
+        sb.append("Evaluation Results for Measure: ").append(measureId).append("\n");
+        sb.append(SEPARATOR).append("\n");
+
+        if (evaluationResults.isEmpty()) {
+            sb.append("  (no evaluation results available)\n");
+        } else {
+            boolean first = true;
+            for (Map.Entry<String, EvaluationResult> entry : evaluationResults.entrySet()) {
+                if (!first) {
+                    sb.append("  ").append(SEPARATOR).append("\n");
+                }
+                first = false;
+                sb.append("  Subject: ").append(entry.getKey()).append("\n");
+                sb.append(format(entry.getValue(), 2));
+            }
+        }
+
+        sb.append(SEPARATOR).append("\n");
+        return sb.toString();
+    }
+
     public static Object printSubjectResources(PopulationDef populationDef, String subjectId) {
         if (populationDef == null) {
             return "{empty}";

cqf-fhir-cr/src/main/java/org/opencds/cqf/fhir/cr/measure/r4/MeasureDefAndR4ParametersWithMeasureReports.java

@@ -2,7 +2,9 @@
 
 import com.google.common.annotations.VisibleForTesting;
 import java.util.List;
+import java.util.Map;
 import org.hl7.fhir.r4.model.Parameters;
+import org.opencds.cqf.cql.engine.execution.EvaluationResult;
 import org.opencds.cqf.fhir.cr.measure.common.MeasureDef;
 
 /**
@@ -35,4 +37,15 @@
  * @param parameters Parameters resource containing bundled R4 MeasureReports
  */
 @VisibleForTesting
-public record MeasureDefAndR4ParametersWithMeasureReports(List<MeasureDef> measureDefs, Parameters parameters) {}
+public record MeasureDefAndR4ParametersWithMeasureReports(
+        List<MeasureDef> measureDefs,
+        Parameters parameters,
+        Map<MeasureDef, Map<String, EvaluationResult>> evaluationResultsPerMeasure) {
+
+    /**
+     * Backwards-compatible constructor for callers that do not need evaluation results.
+     */
+    public MeasureDefAndR4ParametersWithMeasureReports(List<MeasureDef> measureDefs, Parameters parameters) {
+        this(measureDefs, parameters, Map.of());
+    }
+}

cqf-fhir-cr/src/main/java/org/opencds/cqf/fhir/cr/measure/r4/R4MultiMeasureService.java

@@ -25,6 +25,7 @@
 import org.hl7.fhir.r4.model.Parameters;
 import org.hl7.fhir.r4.model.Resource;
 import org.opencds.cqf.cql.engine.execution.CqlEngine;
+import org.opencds.cqf.cql.engine.execution.EvaluationResult;
 import org.opencds.cqf.fhir.cql.Engines;
 import org.opencds.cqf.fhir.cr.measure.MeasureEvaluationOptions;
 import org.opencds.cqf.fhir.cr.measure.common.CompositeEvaluationResultsPerMeasure;
@@ -484,6 +485,7 @@ private MeasureDefAndR4ParametersWithMeasureReports toMeasureDefAndParametersRes
             List<List<MeasureDefAndR4MeasureReport>> results) {
 
         final List<MeasureDef> measureDefs = new ArrayList<>();
+        final Map<MeasureDef, Map<String, EvaluationResult>> evaluationResultsPerMeasure = new HashMap<>();
 
         // Create Parameters to hold the bundle(s)
         final Parameters parameters = new Parameters();
@@ -496,6 +498,12 @@ private MeasureDefAndR4ParametersWithMeasureReports toMeasureDefAndParametersRes
             for (MeasureDefAndR4MeasureReport measureDefAndR4MeasureReport : result) {
                 measureDefs.add(measureDefAndR4MeasureReport.measureDef());
 
+                if (!measureDefAndR4MeasureReport.evaluationResults().isEmpty()) {
+                    evaluationResultsPerMeasure.put(
+                            measureDefAndR4MeasureReport.measureDef(),
+                            measureDefAndR4MeasureReport.evaluationResults());
+                }
+
                 // add report to bundle
                 final MeasureReport measureReport = measureDefAndR4MeasureReport.measureReport();
 
@@ -515,7 +523,7 @@ private MeasureDefAndR4ParametersWithMeasureReports toMeasureDefAndParametersRes
             }
         }
 
-        return new MeasureDefAndR4ParametersWithMeasureReports(measureDefs, parameters);
+        return new MeasureDefAndR4ParametersWithMeasureReports(measureDefs, parameters, evaluationResultsPerMeasure);
     }
 
     protected List<String> getSubjects(R4RepositorySubjectProvider subjectProvider, String subjectId) {

cqf-fhir-cr/src/test/java/org/opencds/cqf/fhir/cr/measure/r4/Measure.java

@@ -286,7 +286,7 @@ public MeasureReport measureReport() {
          * @return SelectedMeasureDef for fluent MeasureDef assertions
          */
         public SelectedMeasureDef<Then> def() {
-            return new SelectedMeasureDef<>(evaluation.measureDef(), this);
+            return new SelectedMeasureDef<>(evaluation.measureDef(), this, evaluation.evaluationResults());
         }
 
         // Backward compatibility - delegate to report()

cqf-fhir-cr/src/test/java/org/opencds/cqf/fhir/cr/measure/r4/MultiMeasure.java

@@ -299,7 +299,8 @@ public MultiMeasure.SelectedReport report() {
          * @return SelectedMeasureDefCollection for fluent MeasureDef collection assertions
          */
         public SelectedMeasureDefCollection<Then> defs() {
-            return new SelectedMeasureDefCollection<>(evaluation.measureDefs(), this);
+            return new SelectedMeasureDefCollection<>(
+                    evaluation.measureDefs(), this, evaluation.evaluationResultsPerMeasure());
         }
 
         // Backward compatibility - delegate to report()

cqf-fhir-cr/src/test/java/org/opencds/cqf/fhir/cr/measure/r4/selected/def/SelectedMeasureDef.java

@@ -5,8 +5,13 @@
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import java.util.Map;
+import org.opencds.cqf.cql.engine.execution.EvaluationResult;
+import org.opencds.cqf.fhir.cr.measure.common.EvaluationResultFormatter;
 import org.opencds.cqf.fhir.cr.measure.common.GroupDef;
 import org.opencds.cqf.fhir.cr.measure.common.MeasureDef;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * Fluent assertion API for MeasureDef objects.
@@ -39,8 +44,17 @@
  */
 public class SelectedMeasureDef<P> extends org.opencds.cqf.fhir.cr.measure.r4.Measure.Selected<MeasureDef, P> {
 
+    private static final Logger logger = LoggerFactory.getLogger(SelectedMeasureDef.class);
+
+    private final Map<String, EvaluationResult> evaluationResults;
+
     public SelectedMeasureDef(MeasureDef value, P parent) {
+        this(value, parent, Map.of());
+    }
+
+    public SelectedMeasureDef(MeasureDef value, P parent, Map<String, EvaluationResult> evaluationResults) {
         super(value, parent);
+        this.evaluationResults = evaluationResults;
     }
 
     // ==================== Navigation Methods ====================
@@ -90,6 +104,19 @@ public SelectedMeasureDefGroup<SelectedMeasureDef<P>> group(int index) {
         return new SelectedMeasureDefGroup<>(value().groups().get(index), this);
     }
 
+    // ==================== Logging Methods ====================
+
+    /**
+     * Log the CQL evaluation results for this measure, formatted for readability.
+     * Similar to {@link org.opencds.cqf.fhir.cr.measure.r4.selected.report.SelectedMeasureReport#logReportJson()}.
+     *
+     * @return this SelectedMeasureDef for chaining
+     */
+    public SelectedMeasureDef<P> logEvaluationResults() {
+        logger.info(EvaluationResultFormatter.formatMeasureEvaluationResults(value().id(), evaluationResults));
+        return this;
+    }
+
     // ==================== Assertion Methods ====================
 
     /**

cqf-fhir-cr/src/test/java/org/opencds/cqf/fhir/cr/measure/r4/selected/def/SelectedMeasureDefCollection.java

@@ -3,16 +3,33 @@
 import static org.junit.jupiter.api.Assertions.*;
 
 import java.util.List;
+import java.util.Map;
+import org.opencds.cqf.cql.engine.execution.EvaluationResult;
+import org.opencds.cqf.fhir.cr.measure.common.EvaluationResultFormatter;
 import org.opencds.cqf.fhir.cr.measure.common.MeasureDef;
 import org.opencds.cqf.fhir.cr.measure.r4.Measure;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * Fluent API for asserting on collections of MeasureDefs from multi-measure evaluation.
  */
 public class SelectedMeasureDefCollection<P> extends Measure.Selected<List<MeasureDef>, P> {
 
+    private static final Logger logger = LoggerFactory.getLogger(SelectedMeasureDefCollection.class);
+
+    private final Map<MeasureDef, Map<String, EvaluationResult>> evaluationResultsPerMeasure;
+
     public SelectedMeasureDefCollection(List<MeasureDef> measureDefs, P parent) {
+        this(measureDefs, parent, Map.of());
+    }
+
+    public SelectedMeasureDefCollection(
+            List<MeasureDef> measureDefs,
+            P parent,
+            Map<MeasureDef, Map<String, EvaluationResult>> evaluationResultsPerMeasure) {
         super(measureDefs, parent);
+        this.evaluationResultsPerMeasure = evaluationResultsPerMeasure;
     }
 
     // Assert count
@@ -26,28 +43,46 @@ public SelectedMeasureDef<SelectedMeasureDefCollection<P>> get(int index) {
         assertTrue(
                 index >= 0 && index < value.size(),
                 "Index " + index + " out of bounds for " + value.size() + " MeasureDefs");
-        return new SelectedMeasureDef<>(value.get(index), this);
+        MeasureDef def = value.get(index);
+        return new SelectedMeasureDef<>(def, this, evaluationResultsPerMeasure.getOrDefault(def, Map.of()));
     }
 
     // Access first
     public SelectedMeasureDef<SelectedMeasureDefCollection<P>> first() {
         return get(0);
     }
 
+    /**
+     * Log evaluation results for all measures in this collection at once.
+     * Each measure's results are formatted with separator lines between subjects and between measures.
+     *
+     * @return this SelectedMeasureDefCollection for chaining
+     */
+    public SelectedMeasureDefCollection<P> logAllMeasureEvaluationResults() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("\n");
+        for (MeasureDef def : value) {
+            Map<String, EvaluationResult> results = evaluationResultsPerMeasure.getOrDefault(def, Map.of());
+            sb.append(EvaluationResultFormatter.formatMeasureEvaluationResults(def.id(), results));
+        }
+        logger.info(sb.toString());
+        return this;
+    }
+
     // Access by measure URL - returns collection (can be multiple in subject evaluation)
     public SelectedMeasureDefCollection<SelectedMeasureDefCollection<P>> byMeasureUrl(String measureUrl) {
         List<MeasureDef> found =
                 value.stream().filter(def -> measureUrl.equals(def.url())).toList();
         assertFalse(found.isEmpty(), "No MeasureDefs found for measure URL: " + measureUrl);
-        return new SelectedMeasureDefCollection<>(found, this);
+        return new SelectedMeasureDefCollection<>(found, this, evaluationResultsPerMeasure);
     }
 
     // Access by measure ID - returns collection (can be multiple in subject evaluation)
     public SelectedMeasureDefCollection<SelectedMeasureDefCollection<P>> byMeasureId(String measureId) {
         List<MeasureDef> found =
                 value.stream().filter(def -> measureId.equals(def.id())).toList();
         assertFalse(found.isEmpty(), "No MeasureDefs found for measure ID: " + measureId);
-        return new SelectedMeasureDefCollection<>(found, this);
+        return new SelectedMeasureDefCollection<>(found, this, evaluationResultsPerMeasure);
     }
 
     // TODO: Implement subject-level filtering once subject tracking API is clarified