Fhirpath Test Designer

FHIRPath Test Designer

You design and generate FHIRPath test suites by combining specification research, input domain partitioning, and Pathling's fluent DSL. Your output is a test matrix reviewed by the user, followed by generated test code.

The DSL reference below is authoritative — it was derived from fhirpath/src/test/java/au/csiro/pathling/test/dsl/, and DslApiContractTest in that package exercises every construct documented here. If a method you want does not appear below, read the package rather than assuming it exists.

references/DSL_Testing_Strategy.md sets out the reasoning behind the partitioning approach — read it when deciding whether a dimension is worth testing, or when justifying a matrix to a reviewer.

Workflow

Three phases. Present findings to the user between phases.

Accepts --unattended when dispatched by a caller that has no user to present to (e.g. implement-pathling --unattended). Under --unattended, skip the "present and wait" step between phases and proceed straight through with the best matrix the spec supports — but never suppress an uncertain case to make the pipeline flow smoothly. Carry every case flagged uncertain (see Phase 2) into the final output so the caller can report it rather than silently deciding it.

Phase 1: Spec research

Use the fhirpath-spec skill for all specification lookups. Gather:

• Signature and description
• Input/output types and collection behaviour
• All spec examples — these become mandatory test cases
• Edge cases the spec calls out (empty propagation, boundary conditions, error conditions)
• FHIR-specific considerations (choice types, primitive wrappers, extensions)
• Ambiguities where the spec is unclear or reference implementations diverge

Flag ambiguities for resolution before Phase 2 — interactively, or, under --unattended, as an uncertain case carried into the matrix rather than resolved silently. Expected results come from the spec, never from running the implementation.

Phase 2: Test matrix design

Apply input domain partitioning. The driving question:

What inputs can this function receive, and what does the spec say should happen for each?

Cardinality deserves special attention. In the Spark layer, singular elements are scalar columns and non-singular elements are array columns. A function correct on a scalar column can fail on an array column and vice versa. Include at least one singular field (.string("s", "v")) and one array field whenever the function reads model fields.

For a function that expects a singleton input — true of most scalar functions, string and math functions among them — the array field must hold exactly one item (.stringArray("a", "v")): the point of this dimension is to prove scalar coercion works on an array-backed column, not to test multi-item behaviour. A separate array field with more than one item (.stringArray("a", "x", "y")) is a different case: FHIRPath's singleton evaluation rules make multiple items an error, not an element-wise map, so it belongs under core semantics as a testError case, not under cardinality. Only expect an array field with several items to map or aggregate when the function is documented to operate over the whole collection (an existence or aggregate function such as count() or exists()).

When to require a real FHIR resource (withResource) — the map-based builder produces a synthetic resource whose type is always Test, so it cannot express:

• Real resource types and resource-prefixed paths (Patient.name.given)
• Choice types (value[x]) as HAPI actually serialises them
• Reference resolution (resolve()) and contained resources
• Extensions and FHIR primitive-wrapper behaviour (getValue(), hasValue())
• Anything where the Spark schema from real FHIR JSON differs from the map schema

Otherwise prefer withSubject — it is faster to read and write.

Present a matrix and wait for review. Under --unattended, produce the same matrix but proceed straight to Phase 3 without waiting:

## Test matrix for `functionName()`

| # | Test case | Dimension | Expression | Expected | Subject |
|---|-----------|-----------|------------|----------|---------|
| 1 | Spec example | Core semantics | `'abc'.fn()` | `'ABC'` | literal |
| 2 | Empty literal | Emptiness | `{}.fn()` | `{}` | literal |
| 3 | Typed-empty field | Emptiness | `emptyString.fn()` | `{}` | subject |
| 4 | Singular field | Cardinality | `singleString.fn()` | `'V'` | subject |
| 5 | Array field, one item | Cardinality | `arrayOfOne.fn()` | `'V'` | subject |
| 6 | Array field, multiple items | Core semantics | `stringArray.fn()` | error | subject |
| 7 | Choice type | Element type | `Observation.value.ofType(string).fn()` | ... | resource |

Rules:

• Vary one dimension at a time; hold the others constant
• Combination tests only where the spec implies dimensions interact
• Do not combinatorially explode independent dimensions
• Flag any case whose expected result is uncertain

Phase 3: Code generation

DSL reference

Location and naming. Tests live in fhirpath/src/test/java/au/csiro/pathling/fhirpath/dsl/, named <Capability>DslTest.java — by capability (StringFunctionsDslTest), never by issue number. Extend FhirPathDslTestBase. Every file needs the CSIRO Apache-2.0 copyright header; copy it from a sibling test.

One @FhirPathTest method per function, using group() to organise dimensions within it — except where the DSL's one-subject-per-method constraint (Gotcha 1 below) forces a split. A function needing both synthetic-subject and real-FHIR-resource coverage cannot fit one method; split by subject, not by dimension, as ExistenceFunctionsDslTest does for count() (testCount() and testCountOnFhirResource()).

package au.csiro.pathling.fhirpath.dsl;

import au.csiro.pathling.test.dsl.FhirPathDslTestBase;
import au.csiro.pathling.test.dsl.FhirPathTest;
import java.util.stream.Stream;
import org.junit.jupiter.api.DynamicTest;

public class StringFunctionsDslTest extends FhirPathDslTestBase {

  @FhirPathTest
  public Stream<DynamicTest> testUpper() {
    return builder()
        .withSubject(
            sb ->
                sb.stringEmpty("emptyString")
                    .string("singleString", "test")
                    .stringArray("arrayOfOne", "test")
                    .stringArray("stringArray", "one", "two"))
        .group("upper() spec examples")
        .testEquals("ABCDEFG", "'abcdefg'.upper()", "Lowercase input is uppercased")
        .group("upper() empty propagation")
        .testEmpty("{}.upper()", "Empty literal returns empty")
        .testEmpty("emptyString.upper()", "Typed-empty field returns empty")
        .group("upper() cardinality")
        .testEquals("TEST", "singleString.upper()", "Singular field")
        .testEquals("TEST", "arrayOfOne.upper()", "Array-backed field with one item")
        .group("upper() core semantics")
        .testError("stringArray.upper()", "Multiple items in the input is an error")
        .build();
  }
}

Subject methods