Regression-testing HL7v2 interfaces in CI: profiles, consistent de-identification, and capture diffs

VariantResearch — Thu, 29 Oct 2026 14:50:24 +0000

Update (Oct 29): launch cohort. I am giving away 10 Solo licenses to interface teams who will run HL7Guard against a real capture and send honest feedback. Email hl7guard-support@variantresearchgroup.com with a line about your setup to claim one. If they are gone, LAUNCH35 takes 35 percent off at checkout through Nov 27 (20 uses). Details in the comments.

Most HL7 interface failures are not single malformed messages. They are silent changes across a whole feed: a vendor upgrade reformats OBX-5, a field that was always populated starts arriving empty, a code list gains a value nobody mapped. A message viewer will not show you that, because message by message everything still parses. You find out when a clinic calls.

Here is the testing pattern I have landed on, and the tool I built to run it.

1. Validate whole captures against a profile

Instead of eyeballing messages, keep a JSON profile per feed: required segments, required fields, allowed values for coded fields. Run every capture through it before and after any change on either side. Exit codes make it a CI gate: 0 clean, 1 findings, 2 the run itself failed. A clean-diff discipline starts with knowing the feed still matches its own contract.

2. De-identify consistently, or do not share captures at all

Real captures are the best test data and the worst thing to email around. One-off anonymization breaks them, though: if the MRN in the ADT does not match the MRN in the result, the flow falls apart and the test proves nothing. The fix is a seeded mapping, one fake identity per real identity across the whole capture, so an admit to discharge to result chain still lines up end to end. Honest limit: this is a de-identification aid, not a HIPAA certification. Free-text fields still need a human review before anything leaves your shop.

3. Diff captures on MSH-10, not on line numbers

Before-and-after captures of the same feed rarely arrive in the same order, so a text diff is noise. Match messages on the message control ID (MSH-10) and diff field by field. What changed, in which segment, for which message: that is the report a vendor call actually needs, and exit code 1 when anything moved makes it a regression test instead of a reading exercise.

4. Feed the receiver bad input on purpose

Generate labelled edge cases from a known-good message: the required segment dropped, the required field emptied, the coded value replaced with one outside the allowed list. Receivers that have never been fed bad input fail in interesting ways, and it is kinder to learn that in testing than in production.

The tool

I built HL7Guard to do these four things from the command line, locally and offline. Single-message validate and anonymize are free, and the free edition includes a desktop GUI and a message viewer/editor. Batch validation, diff, custom profiles, and the edge-case generator are a one-time $79 license; keys are cryptographically signed and the check is offline, not DRM. Code and synthetic samples: https://github.com/VariantResearch/hl7guard and the site is https://hl7guard.variantresearchgroup.com

Disclosure: I built it and I sell the paid tier.