Record-page card behavior contract
Preserve two Record Health Check Lightning card behaviors that are easy to remove by accident while
changing the recordHealthCheck Lightning Web Component: the card rereads Check Set configuration
before every run, and the card body always renders. Both exist because of failure modes that are invisible when reading the component
in isolation. Each one names the source that implements it, the reason it exists, and the test that
fails when it is removed, so a reviewer or an automated agent can confirm the behavior instead of
trusting this description.
The source files and commands on this page are in the Record Health Check product repository. For the behavior as it appears in Setup and on the record page, see Is refreshing the page the same as selecting Rerun?.
Contract 1: Configuration is reread before every run
Section titled “Contract 1: Configuration is reread before every run”Behavior. Selecting Run or Rerun calls getCheckDefinitions and evaluates against the
response. It does not evaluate against the check list captured when the page loaded.
Reason. A Salesforce console record tab can stay open for days. Definitions captured at page load go stale the moment an administrator activates a Check, deactivates one, or changes a threshold, label, or display setting. Without the reread the card replays whichever configuration happened to be current when the tab was opened, and nothing on screen explains the difference. Rereading costs one Custom Metadata call in front of a run that already makes one Apex call per Check, and the reader has just pressed a button, so the wait is expected.
Where it is implemented.
| Concern | Source |
|---|---|
| Single entry point for every card-initiated run | _ in recordHealthCheck. |
| Run and Rerun | handleAction in recordHealthCheck. |
| Record-save refresh | _ in recordHealthCheck. |
| Server response, deliberately not cacheable | getCheckDefinitions in RecordHealthCheckController. |
Definition response validation and namespace-aware prerequisite resolution live in the pure
healthCheckDefinitions.js helper. _loadDefinitions owns request lifecycle, server-verified
entitlement, state updates, and scheduling. It captures entitlement before validation so malformed
responses retain useful detail for authorized administrators. The extraction preserves validation
order and never reuses definitions from an earlier run.
Supporting behaviors that must survive a refactor.
- The
preserveRowsargument to_loadDefinitionskeeps the previous rows, the Rerun label, and the resolved-definitions flag on screen while the request is in flight. Without it a Rerun empties the card and the button falls back to Run, which reads as lost state. - A failed reread surfaces the component error. It must not fall back to the definitions loaded earlier, because that reports a result against rules the administrator has already changed.
getCheckDefinitionsmust stay withoutcacheable=true. The annotation would reintroduce the same staleness through the Lightning Data Service cache.
Known difference. The record-save refresh rereads configuration but clears the rows and shows the card spinner. Only Run and Rerun hold the previous results. This is a deliberate limit on the change, not an oversight.
Contract 2: The card body always renders
Section titled “Contract 2: The card body always renders”Behavior. From the first frame the reader sees a complete bordered card with meaningful body content. The normal default includes the grey heading strip. A Check Set may deliberately hide that strip through Card Heading Display, but the body never collapses to an empty card and the component never renders bare page space.
Reason. The header and body are separate regions of one card. Three states left the body empty while the header rendered normally, so the card appeared truncated rather than busy.
Where it is implemented.
| Concern | Source |
|---|---|
| The card box always renders; the normal heading follows configuration | recordHealthCheck., both branches of hasComponentError |
| Default title before any response | displayTitle initializer in recordHealthCheck. |
| Loading state covers both Apex calls | _ and _ |
| Last-resort body content | showEmptyBodyNotice in recordHealthCheck. |
| Spinner keeps a real body height | . in recordHealthCheck. |
showEmptyBodyNotice is written as the negation of every other body block rather than as a list of
empty states. When nothing else renders below the header, it renders a short status line. A state
added later cannot reintroduce the header-only card without also being added to that condition.
Maintenance rule. Adding a block to the card body means adding it to the showEmptyBodyNotice
condition. Adding an await to the load path means giving that window a loading state, because the
scheduled-load handle is cleared before the awaited call begins.
TITLE_ONLY suppresses only the subtitle. HIDE removes the complete normal heading, including the
Run/Rerun action, and is valid only with RUN_ON_LOAD; RUN_ON_REQUEST fails as invalid configuration.
No empty heading or action container renders. The body retains top clearance equal to the card radius
so the first status accent remains straight. Error cards retain their setup heading without inheriting
that headerless-card clearance, and App Builder retains the selected Check Set identity. The normal
card article keeps the resolved Card Title as its accessible name.
INVALID_CONFIG is recoverable without a page reload. The error card offers Try Again, which
rereads the full definition after an administrator corrects the Check Set. A directly assigned
Record Health Check Admin or Diagnostics Viewer sees the exact rejected setting under
Administrator detail; other users are shown only the generic setup message. The entitlement is
verified on the server and travels with the structured configuration error, because a rejected
definition cannot return its normal response DTO.
Summary Display also supports HIDE: it suppresses overall and category summaries without changing
Check evaluation or the hidden-results notice. When the list is the final body block, bottom padding
equal to the card radius keeps accents away from the curved edge. Only adjacent Check rows receive
a separator, so a lone Check has no row separator.
What an administrator actually sees for an empty Check Set. Deactivating every Check in a Check
Set was tested in a scratch org. Apex raises NO_ACTIVE_CHECKS before returning definitions, so the
card renders the setup error, not the empty-body line. The heading reads Record Health Check
Needs Setup and the body reads This Record Health Check doesn’t contain any active Checks. The zero-check body line is a defensive
fallback for a response shape the server does not currently produce. Keep it: it costs nothing, and
it is what stops a future response change from reintroducing a header-only card.
Verified states
Section titled “Verified states”Each row was observed by rendering the component and inspecting the card body, not by reading the source. The Before column describes the component prior to these changes.
| State | Before | Now |
|---|---|---|
| First frame after connect | Full card with spinner | Unchanged |
getCheckSetShellConfig in flight | Header only | Full card with spinner |
getCheckDefinitions in flight | Full card with spinner | Unchanged |
| Loaded, before the first manual run | Pre-run hint | Unchanged |
| Run in flight, either reveal mode | Check rows | Unchanged |
| Run complete | Rows and summary | Unchanged |
| Every row hidden by display settings | Hidden-results notice | Unchanged |
| Check Set with no active checks | Header only | Explanatory body line |
| Shell reports zero active checks | Header only | Explanatory body line |
| Component has no record | Header only | Explanatory body line |
| No Check Set selected | Header only | Explanatory body line |
| Definition load failed | Error row | Unchanged |
How to verify these claims
Section titled “How to verify these claims”Run the component test suite:
npm run test:unitThe two describe blocks below own these contracts. Their names are the search keys.
| Contract | Describe block |
|---|---|
| Configuration is reread before every run | Rerun re-reads Check Set configuration |
| The card body always renders | the card body never collapses to a header |
Those tests run against jsdom, where no stylesheet is applied and no Apex is called. They prove the rendered structure and the request sequence, not the painted card. The release gate covers that:
npm run test:browser:salesforce -- --target-org <alias> --security-mode LWStests/browser/card-contract.spec.mjs runs in that gate for both browsers and both security modes.
It measures the painted card body against the header, and it counts getCheckDefinitions requests
across a Run and a Rerun. scripts/release/run_salesforce_browser_gate.mjs invokes it alongside the
existing release-matrix spec, so every release exercises both contracts on a real record page.
A passing suite is not proof on its own, because a test can pass against a component that no longer implements the behavior. Confirm that the tests still fail when the behavior is removed:
- In
recordHealthCheck.html, changeif:true={showEmptyBodyNotice}to a name that does not exist, and delete thethis.isLoading = true;line before the shell request in_resolveConfiguredLifecycle. - Run
npm run test:unit. The body contract tests fail withHeader-only card in scenario, naming each uncovered state. - Restore both files, then in
handleActionreplace the_loadDefinitionscall withthis._runner.run(false, "USER_INITIATED")and run the suite again. - Restore the component before continuing. Take the restored copy from source control rather than
from memory, and confirm
npm run test:unitreports every test passing again.
Both mutations were measured when these tests were written:
| Removed behavior | Failing tests | Reported detail |
|---|---|---|
| Body notice and shell loading state | 9 of 305 | 16 states named as Header-only card in scenario |
| Reread on Run and Rerun | 9 of 305 | 5 in the configuration block, 4 in existing load tests |
If either mutation stops failing, the tests have stopped protecting the behavior. Repair them rather than deleting them, and treat the passing suite as unproven until they fail again.
Scratch-org evidence
Section titled “Scratch-org evidence”Recorded on 2026-09-05 in the namespaced Lightning Web Security scratch org rhc-2063-ns-lws,
against the release-matrix record page.
| What was exercised | Result |
|---|---|
Package RunLocalTests | 1281 tests, 100% pass, run 707Ru000029OYsJ |
| Card at load, during a run, and after completion | Box, header, and painted body throughout |
| Deactivating one Check in Setup, then Rerun with the tab left open | Completed Checks moved from 25 / 25 to 24 / 24 with no page reload |
| Deactivating every Check in a Check Set | Setup error card, per the note above |
card-contract. against the current component | Passed |
card-contract. against the component before this change | Failed: Rerun did not request Check Set definitions again |
Limit of the browser evidence. The pre-change run failed only on the configuration assertion. Its painted-body assertion still passed, because the release-matrix page has no empty Check Set and the shell-request window is too short to sample reliably. The browser spec is therefore a regression guard for a persistent header-only card. The transient loading gap is proven only by the Jest suite, which holds the request open deliberately.
Card-only result transport
Section titled “Card-only result transport”The card calls RecordHealthCheckController.evaluateCheckJson, which delegates to the existing
typed evaluateCheck method and serializes its display plus the five card evaluation fields
(recordId, checkQualifiedApiName, status, severity, and reasonCode). Raw machine operands
and structured evidence are excluded from the card-specific response. Null object properties are
omitted. healthCheckModel.normalizeResult decodes the JSON before validating the result. The
card keeps the verdict, message, Found/Expected comparison, remediation, and authorized diagnostics;
it never renders evidence summaries, tables, Show details/Show all, or downloads. Evidence remains
available to authorized callers through the typed evaluation APIs and is tested there independently.
Comparison headings are fixed as Found and Expected for every Check type, including
Formula condition fallbacks and Apex plugin display content. Server-provided expectedValueLabel
cannot rename the card heading or accessible row label. ComparisonDisplayMode__c controls eligible
sides, and the Check Set’s comparison placement controls inline/expanded visibility. Typed APIs
retain their existing optional label field. The Jest block fixed comparison labels respect Custom Metadata visibility guards PASS and FAIL across all placement and visibility combinations.
The Preview controller already returns JSON text. Public Apex, REST and native action contracts retain their existing typed or JSON responses; the new adapter changes only the card transport. The adapter preserves authorization, Check membership, source validation and per-Check execution.
The LWC regressions verify that PASS and FAIL retain the comparison while no structured evidence
controls or summary appear, even if an older server includes evidence in the display payload.
RHCControllerEvidenceTransportTest verifies PASS and FAIL through the saved typed-null fixture,
confirms the adapter omits evidence, and rejects an unauthorized caller. It also guards omitted raw
operands and text nodes without null link properties. RHCEvidenceFixtureTest continues to verify
typed null cells and evidence validity through the public evaluation API.