self-healing-dq

A Python + pytest data quality framework where an infrastructure failure gets healed by Claude at test-run time — and a hard-gate data assertion that the engine deliberately refuses to touch.

How it works

A DQ test runs against a data layer. If it fails with an infrastructure error (ModuleNotFoundError, ImportError, FileNotFoundError, etc.), SelfHealingEngine asks Claude (framework/claude_dq_healer.py, raw HTTP to the Anthropic Messages API, no SDK) to suggest a fix — a shell command such as pip install tabulate — up to 3 attempts. Every attempt is logged (framework/healing_log.py) to artifacts/healing/.

• On success: the test passes, and a -HEALED.md artifact tells a human to apply the fix permanently (e.g. add the package to requirements.txt). Claude doesn't modify source files mid-run.
• After 3 failed attempts: writes a -FAILED.md artifact with the full attempt log ("Claude couldn't do it, check manually").

Without ANTHROPIC_API_KEY set, the engine runs in dry-heal mode — classification and reporting still happen, Claude calls are skipped.

The engine never relaxes a data quality assertion. Silver hard gates classified as MUST_FAIL are documented but never repaired.

Three scenarios

1 — Healed (tests/test_healed_scenario.py)

tabulate is intentionally omitted from requirements.txt. Without it, the file fails with ModuleNotFoundError before any test runs. The engine classifies the failure as HEALABLE, asks Claude to suggest pip install tabulate, applies it, re-runs, and writes a -HEALED.md artifact.

2 — No healing needed (tests/test_no_healing_needed.py)

Bronze detection tests that pass on the first run. Known violations (2 null supplier_id, 1 negative unit_price) are within documented tolerance limits. No Claude call is made.

3 — Must fail (tests/test_must_fail_scenario.py)

Silver hard-gate tests applied to the raw layer. The same violations exceed the strict zero-tolerance threshold that gates Gold promotion. The engine classifies these as MUST_FAIL and moves on — no healing is attempted, no artifact is written for a passing outcome.

Run it locally

make install && make heal

To see just the healed scenario:

make heal-healed

To see the must-fail scenario:

make heal-must-fail

To classify without calling Claude:

python3 run_healing.py --dry-run

CI

.github/workflows/self-healing-dq.yml runs the engine on every push/PR to main. With ANTHROPIC_API_KEY set as a repository secret, the healed scenario genuinely exercises the Claude call. Healing artifacts are uploaded regardless of outcome.

Author

Devbrat Verma — Senior SDET, 10+ years in test automation.