Quality gates

Package testing and upgrades

Test a package build or upgrade with this evidence sequence.

This page separates the steps an administrator follows to upgrade an installed package from the release checks that package contributors must complete.

Record Health Check is delivered as a namespaced second-generation unlocked package. An administrator installs a promoted package version in a sandbox and then upgrades the existing installation. Package contributors use source deployments only while developing and testing the package.

For Salesforce administrators

If you only install and operate the package, follow this section and then return to Revalidate or upgrade. The contributor sections below do not apply to a subscriber org.

Use a package version for upgrade testing

Use this approach	Do not use this approach
Install the promoted package version whose ID begins with `04t`	Clone the repository and deploy package source into a production org
Test the upgrade in a sandbox first	Edit installed Apex classes or package test utilities
Create your own Check Sets and Checks in Setup	Rename or repurpose installed example metadata as your business configuration
Keep org-specific Apex and tests in your team’s repository	Add org-specific code to the Record Health Check package source

Custom Metadata records created by an administrator in your org belong to your team. The release process tests that those records remain after an upgrade. The four Example_ Check Sets included with the package remain package content and can change in a later package version.

Before an upgrade

Read the release notes and identify configuration or permission changes.
Confirm the current package version in Setup → Installed Packages.
Back up Check Sets and Checks created by your team by following Back up configuration.
Install the new promoted version in a sandbox that represents production.
Reassign or verify the installed Permission Sets.
Run the checks and automation used in everyday workflows.
Confirm that your team’s Check Sets, Checks, Apex classes, Flows, and saved result records still behave as expected.

Follow Revalidate or upgrade for the complete administrator procedure and current installation link.

CLI upgrade example

The normal administrator path is Setup → Installed Packages and the approved upgrade link. Use this optional command only if your team already manages package installations with Salesforce CLI.

Administrators who use Salesforce CLI can install the new promoted version over the existing one:

sf package install \
  --package 04tNEW_VERSION_ID \
  --target-org customer-sandbox \
  --upgrade-type Mixed \
  --wait 30 \
  --publish-wait 10 \
  --no-prompt

Replace 04tNEW_VERSION_ID with the promoted package version ID recorded as stable in config/package-releases.json. Replace customer-sandbox with the alias for your sandbox.

This repository uses Salesforce’s Mixed mode so removed components that are safe to delete do not remain behind and break compilation, while components that cannot be safely deleted are deprecated. Review removed metadata and the rollback plan before every release; use Delete only when its stronger deletion behavior and possible data loss have been explicitly approved.

Which tests run where?

Tests	Location	Who runs them?	Purpose
Package unit tests	Test classes inside `packages/record-health-check/force-app`	Package maintainers during source validation and package-version creation	Verify the Apex and Lightning package code
Package integration tests	`packages/record-health-check/integration-tests`	Package maintainers in release scratch orgs	Verify installed examples, access, events, and end-to-end behavior
Org-specific tests	Your team’s Salesforce repository	Your team in its normal deployment pipeline	Verify Check Sets, custom Apex Checks, Flows, and other business automation created for your org

An ordinary RunLocalTests deployment in an org with the namespaced package installed does not run the package’s namespaced test classes. RunAllTestsInOrg or explicitly selected test classes can run them. Your own tests must not depend on or modify RecordHealthCheckTestDataFactory; that class is a package test utility, not a public extension point.

Package-version creation is also its own Apex execution context. Its test principal must not be assumed to hold packaged Permission Sets, and assigning a packaged Permission Set to the current user in @TestSetup is not accepted as proof that later user-mode access will match an installed administrator. Do not create replacement Users in unlocked-package tests: subscriber User automation can execute in the packaging org. Model customer records in user mode; model any private service-owned package store explicitly, authorize it at the public boundary, and pin every reviewed system-mode exception with check:apex-surface and focused source tests. A source-org green run does not close this boundary; the package version’s own Apex tests must pass.

For package contributors

Namespace coverage

The released 2GP artifact always uses the rhc namespace. Contributor source validation can use a namespaced org, but it is not an additional release stage. The release pair consists of two ordinary subscriber orgs without their own namespace, one LWS and one Locker. The installed package still uses rhc.

An unpackaged no-namespace source deployment is retained as an optional contributor portability check:

Test org	What it proves
Namespaced `rhc` scratch org	Package source compiles when Salesforce applies the package namespace
No-namespace scratch org	Optional proof that unpackaged repository source remains portable; this is not a second package shape

Never build a Qualified API Name by adding rhc__. Tests query Salesforce for QualifiedApiName, and Apex uses schema describe results when an object or field name can differ by org shape.

Run the documented source-development commands in Source development. The repository checks also reject hard-coded rhc__ strings in package Apex where the code should discover the name.

Release checks

For each proposed version, maintainers must:

Run the repository release preflight on the exact committed source.
Create one package candidate with code coverage enabled.
Retrieve the package artifact and confirm that every Custom Metadata member has a physical file.
When the release owner explicitly authorizes scratch-org testing, create exactly one LWS and one Locker subscriber org for the release.
In each org, clean-install and verify the candidate, remove the subscriber harness, uninstall the candidate, install the immediately preceding promoted release, and upgrade to the candidate.
Record that customer-owned Custom Metadata survived the exact previous-to-candidate upgrade.
Promote the exact candidate after its package report and creation evidence are verified.
Move the former stable version to previous, record the new promoted 04t and installation links in config/package-releases.json, update CHANGELOG.md, and create the matching release tag.

These are separate assertions executed sequentially in the same two orgs. A successful clean installation does not prove that an upgrade preserves an administrator’s Custom Metadata, and a successful source deployment does not prove that the package artifact contains every intended file.

See Releasing for commands, required evidence, and scratch-org cleanup rules.

The authoritative org purposes, lifetimes, ownership rules, daily creation budget, human demo path, and orphan-recovery procedure are in the scratch org lifecycle and release plan.

The complete fail-closed environment, entry-point, lifecycle, server-side, upgrade, and evidence requirements are defined in the Release runtime matrix. That matrix is additive to this lifecycle summary and applies to every release build.

Where release evidence belongs

Keep evergreen requirements in this quality gate and in the tracked release workflow. Keep candidate-specific deploy IDs, test results, analyzer output, package-install results, upgrade results, approvals, and rollback evidence with the pull request or release artifacts for that exact source revision. Environment-dependent work that has not run remains in the tracked verification backlog until it is executed or explicitly removed from the supported release scope.

Do not maintain a parallel local design spec as a release ledger. Its component counts, test counts, org aliases, findings, and pending boxes become stale as soon as the package changes. Missing candidate evidence still blocks that candidate; retiring a stale planning document never counts as proof that an install, upgrade, access-context, asynchronous, or hosted validation passed.