Payroll Regression Testing: Proving That Nothing Broke

The Cascade Problem

Payroll systems have a property that makes them uniquely vulnerable to regression: calculations depend on each other in deep, non-obvious chains. A social security contribution rate isn’t just one line on a payslip — it feeds into the Vorsorgepauschale (Germany), the primes déductibles (France), or the NI deduction (UK), which in turn affects taxable income, which changes the income tax result, which changes the solidarity surcharge, which changes net pay.

In conventional software, a regression is a bug that reappears after being fixed. In payroll, a regression is worse: it’s a previously correct calculation that becomes incorrect after a change to something else entirely. A developer adds a new bonus wage type. That bonus feeds into a gross income collector. The collector is referenced by the social security base calculation. The higher base pushes an employee above the Beitragsbemessungsgrenze (contribution ceiling). Suddenly the health insurance calculation produces a different result — capped instead of proportional. Three wage types downstream, net pay changes by EUR 47.23. Nobody touched any of those wage types. Nobody intended any of those changes. But the payslip is wrong.

This cascade property means that payroll regression testing cannot be selective. You cannot test “just the changed wage type.” You must test everything downstream of the change — and in payroll, “downstream” often means the entire calculation chain from gross to net. The only safe approach is a comprehensive regression suite that runs all tests on every change.

Each country regulation in PayrollEx ships with hundreds of integration tests. Not unit tests — full payrun executions against a live Payroll Engine backend. When any regulation file changes, the entire suite runs. One failure blocks the change. Zero tolerance, because in payroll, “probably fine” is never acceptable.

What Regression Means in Payroll

A formal definition helps clarify what the test suite is actually protecting against:

This is distinct from an intentional change. When the German government publishes a new Programmablaufplan (PAP) for 2027, every Lohnsteuer test will fail against the 2027 parameters. That’s expected — the expected values are recalculated and the tests updated. The regression suite distinguishes between these two cases by design: tests that fail after a parameter update are recalculated and verified against the new statutory source. Tests that fail after a code or regulation structure change when no parameter changed are genuine regressions.

What makes regression detection actionable — rather than just an alarm — is traceability. Knowing that “WT 5100 Lohnsteuer is wrong” isn’t enough. You need to know where in the cascade the divergence started. Was it the Vorsorgepauschale? The SV-Brutto? The Kirchensteuer base? The Payroll Engine’s Wage Calculation Traceability addresses exactly this — turning a failing assertion into a targeted, auditable diagnosis.

Guard Tests: Proving Rejection Works

Not every payroll regression produces a wrong number. Some regressions are more dangerous: they produce any number at all when the system should have refused to calculate. This is where guard testing enters.

Every country regulation in PayrollEx starts with guard wage types — typically WT 1 through WT 4 — that validate mandatory fields, data consistency, and lookup availability before any calculation begins. If a guard fails, it calls AbortExecution, stopping the entire payrun for that employee. No partial results, no best-effort calculations, no silent zeros.

GUARD-TC tests verify these failure paths. Unlike WT-TC tests (which assert correct calculation results), GUARD-TC tests assert that execution is aborted when inputs are invalid. They provide deliberately incomplete or inconsistent data and verify that the payrun does not produce results.

Why is this a regression concern? Consider this scenario: a developer adds a new optional case field to the German regulation — say, a special tax exemption flag. The guard logic checks for mandatory fields. If the new field is accidentally marked as mandatory in the guard’s validation list, every existing employee without that field will be rejected. The guard fires, execution aborts, no payslip is generated. From the system’s perspective, it correctly enforced a validation rule. From the business perspective, 500 employees didn’t get paid.

The inverse is equally dangerous: a data model change that inadvertently satisfies a guard for employees with invalid data. If a guard checked TaxClass != null and someone refactors the field name without updating the guard, the null check passes vacuously — the field is always null because it’s reading the wrong name. The payrun proceeds with no tax class, and income tax calculates as zero.

In practice, every country regulation maintains GUARD-TC tests alongside its WT-TC calculation tests. The naming convention makes the intent explicit: GUARD-TC1-DE-MissingTaxClass, GUARD-TC2-DE-NoSvLookup, GUARD-TC3-CH-InvalidCanton. Each test documents exactly which validation is being verified and what failure mode it represents.

Mid-Month Value Changes

Some of the subtlest regressions occur in time-segmented calculations. When a case value changes mid-period — a salary increase on the 15th, a tax class change on the 20th, a working hours reduction on the 10th — the engine splits the period into sub-periods and calculates each independently. The payslip shows one aggregated result, but behind it are two or three separate calculation passes.

Regression testing of mid-month changes verifies three properties simultaneously:

1. Sub-period arithmetic: Each split produces the correct prorated result. A salary of 4,000 EUR for 15 days in a 31-day month must produce exactly 4,000 × 15/31 = 1,935.48 EUR — not a rounded approximation.
2. Aggregation correctness: The sum of all sub-period results equals the wage type value on the payslip. No rounding drift accumulates across splits.
3. Custom result storage: When clusterSetWageTypePeriod is active, one custom result per split is stored. An auditor can verify that the Feb 1–14 split used the old salary and the Feb 15–28 split used the new salary.

The regression risk is specific: a new wage type or a refactored custom action that handles two CalendarPeriod fields will silently apply the day-scaling twice. The engine scales every CalendarPeriod field at read time (value × subDays / periodDays). When both operands in a multiplication are CalendarPeriod, the product is scaled squared — and the result is silently too small.

Mid-month regression tests are structured with explicit case value changes within the test period. The exchange JSON contains two case field value entries for the same field — one with start at the period beginning, another with start at the change date. The expected results assert the aggregated value, and when traceability is active, the custom results assert each sub-period independently.

This catches regressions that single-value tests miss entirely. A wage type that works perfectly for a full month — passing all standard WT-TC tests — may fail catastrophically when values change mid-period. Without dedicated mid-month regression tests, these failures only surface in production when an employee happens to have a salary change or working hours adjustment partway through a month.

Retroactive Payrun Results: The Most Complex Regression Scenario

If mid-month splits are subtle, retroactive corrections are an order of magnitude more complex. A retro payrun re-executes a past period with updated data, compares the new results against the originally stored results, and produces delta wage types that flow into the current period. Every step in this chain is a potential regression point.

What Makes Retro Testing Complex

A retro regression test requires at least two payrun job invocations in the test data: the original period run and the correction run. The test must assert results for both — the original run produces the baseline values, and the correction run produces updated values plus the delta (difference) between old and new.

Consider the test structure for a salary correction backdated one month:

payrunJobInvocations:
  [1] January payrun (evaluation: Jan 31)
      → Original results: LSt 301.33, KV-AG 407.50, Net 2,891.17
  [2] February payrun with retro (evaluation: Feb 28)
      → Corrected January: LSt 342.08, KV-AG 447.50, Net 2,810.42
      → Delta into February: LSt +40.75, KV-AG +40.00, Net −80.75
      → February own results + delta = payslip values

The regression suite verifies five properties for every retro scenario:

1. Baseline correctness: The original period result matches the expected values at the time. This confirms the “before” state is accurate.
2. Recalculation correctness: After the data change, re-running the past period with the new data produces the correct new result. The statutory formula with the updated inputs yields the expected output.
3. Delta precision: The difference between old and new results is exact — no rounding drift, no missed wage types, no accumulation errors. If the original LSt was 301.33 and the new LSt is 342.08, the delta must be exactly 40.75.
4. Scope isolation: Periods that were not affected by the change remain untouched. If the salary correction applies only to January, the February base calculation must not retroactively change December or November.
5. ValidFrom boundaries: A 2026 regulation must not retroactively apply to a 2025 period. The retro mechanism respects validFrom dates on data regulations — a correction for December 2025 uses 2025 statutory parameters, not 2026.

Multi-Period Retro Cascades

The complexity escalates when a correction spans multiple periods. A salary change backdated three months means three separate correction passes, each producing its own delta. And the deltas can cascade: if January’s correction changes the year-to-date (YTD) social security base, February’s recalculation sees a different accumulated base, which may push the employee above or below a contribution ceiling in a different month than expected.

Scenario: Salary 3,000 → 3,500 backdated from January, corrected in April

  Jan correction: ΔLSt +40.75, ΔKV-AG +40.00
  Feb correction: ΔLSt +40.75, ΔKV-AG +40.00 (same rate, same delta)
  Mar correction: ΔLSt +40.75, ΔKV-AG +40.00

  April payslip: own calculation + sum of all deltas
  Total retro LSt: +122.25
  Total retro KV-AG: +120.00

In this simple case the deltas are identical per month. But introduce a progressive tax bracket, a contribution ceiling, or a mid-month change within one of the corrected periods, and each month’s delta diverges. The regression test must assert each period’s delta individually — not just the sum.

Testing Retro With Exchange JSON

The exchange JSON for a retro regression test contains multiple payrunJobInvocations with ascending evaluation dates. The first invocation establishes the baseline. Subsequent invocations trigger retro correction for prior periods. The payrollResults section asserts expected values for each invocation — both the current period’s own results and the retro delta values.

The README for a retro test must document the full chain: original calculation, data change, recalculation per corrected period, delta derivation, and final payslip composition. This is typically the longest README in a test suite — because the arithmetic spans multiple periods with multiple wage types each. But without it, the test is unauditable. An assertion of “retro delta WT 5100 = 40.75” is meaningless without showing the original 301.33, the recalculated 342.08, and the subtraction that produces 40.75.

The CI Safety Net

All of the above — cascade protection, guard verification, mid-month split validation, retro delta checking — converges in a single operational mechanism: the CI regression gate.

Every pull request against a country regulation triggers the full test suite. Not a subset. Not “tests related to the changed file.” The complete Test.All.pecmd — hundreds of integration tests per country — runs in a clean environment. Preview payrun jobs execute each test against a freshly imported regulation stack. One failure blocks the merge.

The choice to run all tests on every change is deliberate and non-negotiable. Payroll’s cascade property means that no static analysis can predict which tests a change might affect. A lookup table modification affects every wage type that references that lookup — directly or transitively through collectors, wage type references, or custom actions. Only executing the full suite provides certainty.

The CI environment starts clean for every run. This is critical because local development databases retain state from previous test runs. A regulation that was imported last week still resolves lookups locally — but in CI, only what Setup.Test.pecmd explicitly imports exists. The regression gate catches not only calculation regressions but also import regressions: a file that was removed from the setup pipeline, a data satellite that lost its layer entry, a script that was renamed without updating its reference.

Preview jobs are the correct execution mode for CI: synchronous (the pipeline waits for completion), non-persistent (no database state between runs), and retro-free (no historical periods to trigger correction logic). The test verifies the calculation, asserts the result, and discards everything. The next test starts with the same clean state.

Provider Overlay Regression

The regression risk multiplies when providers add their own regulation layers. A provider overlay sits above the country regulation in the layer stack. It can add wage types, override rates, extend cases, and modify collectors. Each of these operations is a potential regression vector for the underlying country regulation.

The most common provider-induced regression is accidental shadowing. The Payroll Engine resolves objects by name across layers — higher layers override lower layers. If a provider defines a wage type with the same name as a country wage type (intentionally, to override behavior), only the provider’s version executes. But if the override is incomplete — it handles the common case but misses an edge case that the country regulation handled — the test for that edge case fails.

Less obvious: a provider adds a new collector group membership to a wage type. The country regulation has a collector that accumulates all members of that group. The provider’s wage type is now contributing to a collector it wasn’t designed to feed. The social security base includes an amount it shouldn’t. The contribution calculation is wrong. The regression test for social security catches it — because the expected value for a standard employee suddenly includes the provider’s extra amount.

This dual-layer testing is what makes PayrollEx’s composable model safe for production. You can build on top of a country regulation with confidence — not because overrides are impossible, but because the existing test suite will immediately surface any unintended side effect.

Traceability as Regression Evidence

Finding a regression is step one. Proving that it was correctly identified, isolated, and fixed is step two — and for regulated payroll operations, step two is what auditors care about.

The Payroll Engine’s Wage Calculation Traceability feature provides the evidence trail. When clusterSetWageTypePeriod is active, every wage type in the cluster set produces per-sub-period custom results. These results document not just what the engine calculated, but how it arrived at each value.

In a regression scenario, this means:

1. Detection: The regression test fails — WT 5100 expected 301.33, got 342.08.
2. Isolation: The custom results show that sub-period Feb 1–14 produced the expected value, but sub-period Feb 15–28 diverged. The divergence started at the Vorsorgepauschale (WT 5050), which used a contribution rate from a newly modified lookup.
3. Root cause: The lookup modification was intended for a different wage type but affected the Vorsorgepauschale because both reference the same lookup key.
4. Correction: The lookup is split into two entries with distinct keys. The regression test passes. The custom results confirm both sub-periods now produce the expected values.
5. Evidence: The test history (before/after), the custom results (per-split derivation), and the commit diff (what changed) constitute complete audit evidence that the regression was managed correctly.

This isn’t just good engineering practice. In jurisdictions with payroll certification requirements — Germany’s ITSG certification, Switzerland’s Swissdec, the UK’s HMRC recognition — the ability to demonstrate systematic regression management is part of the compliance story. The system doesn’t just produce correct results; it can prove that correctness is continuously verified and that any deviation is caught, explained, and resolved.