Regression Testing After a Znode Update

TABLE OF CONTENTS

Regression Test a Baseline Update

A baseline update can touch any shared file: middleware, the custom server, the theme configuration, shared agents. This is the checklist to run after the merge is done and the branch builds, before you ship it. It is a smoke test across the whole storefront, not a retest of one feature.

For implementation partners and developers When right after a baseline merge, before deployment Covers build · tests · critical journeys · settings · cache · rollback


Steps run against the merged branch

Each gate must pass before the next one starts. A blocking issue found after shipping sends you to the rollback plan, not back to Gate 1.


GateNameDescription
1Build & testsBoth apps build, lint and the full Jest suite pass.
1BEnv diffNo newly required variable is missing from an environment.
2JourneysEvery critical journey, both locales, both auth states.
3Settings Login-required, maintenance, theme resolution
3BCacheCache headers and behavior
4Final VerificationCreate audit trail of gate verifications


Gates are required since a merge can pass review and still regress.

A baseline update can touch middleware.ts, server.js, next.config.js, the theme configuration map, shared agents and clients, translation keys, or the set of environment variables the storefront reads. Your project's unit tests can all stay green and the store can still regress, because the break is only visible in a running store, or only on a setting your default test store does not use.

This is normal. It is the expected cost of layering customizations on a product baseline, which is exactly why a regression pass follows a merge instead of a build check alone.

Don't treat a green build and a green test run as proof the store works. Gate 1 only rules out the failures that are visible without a running store.


Gates / Milestones

Gate 1 - Build and tests

Verify build, lint and automated tests. Run these before anything manual. A failure here is far cheaper to find now than during checkout testing.


terminal

npx nx build webstore
npx nx build page-builder
npm run lint
npx nx run-many -t test --passWithNoTests


Check

Priority

Why it matters after an update

Both apps build

Must

A baseline change can break a type or an import path your project depends on

Both Docker images build (base → builder → runner)

Must

The production build runs inside the image; a local build passing is not proof the image does

Full lint passes

Must

Same command the commit hook runs; catches drift the merge introduced

Full Jest suite passes

Must

npx nx affected -t test alone can miss a regression in a package nothing in the diff directly touches but that a shared default change affects

Every project that had a test target still has one

Must

A baseline change to nx.json or a package config can silently drop it


For the test tooling itself (what is installed, how to mock the shared server helpers, and how to add a test to a package) see the related guides at the end — this checklist only tells you what to re-run.

Gate 1B - Environment diff

Verify diff environment variables against the previous version. A baseline update can introduce a variable that did not exist before. If your deployment does not set it, a feature can silently fall back to a default, or fail outright, only in the target environment.


STEP 1 - Diff the environment file

Compare the storefront's environment file against the pre-merge version. Treat it as a template — never copy real secret values between environments.


terminal

git diff <pre-merge-ref> -- apps/webstore/.env


STEP 2 - Check it against the configuration groups

Every variable the storefront reads falls into one of these groups. A new variable in the diff belongs to one of them; confirm it is set everywhere the group's variables are normally configured.

Back-end connection · Application & store · Authentication & secrets · Data & page caching · Anonymous cache & CDN · Redis · Payments (browser) · Observability & build

STEP 3 - Confirm every target environment, not just local

Environment variables set on the container take precedence over .env files, and NEXT_PUBLIC_* values are fixed when the image is built. A variable set locally proves nothing about the deployed environment.

Watch for: a new or changed OTEL_* variable. The OpenTelemetry start-up refuses to run when a required one is missing, which can take observability down without affecting the storefront itself — easy to miss because nothing visibly breaks for shoppers.

Gate 2 - Journeys

Verify critical journeys for each locale and for both guest and logged in user states. Run these in a deployed or containerized environment - not nx dev - which skips the anonymous page cache and uses the Next.js development server instead of the production one. Use a private window for every anonymous check so no stale session carries over.


Checkout, account and login must cover each locale and both logged-in and non-logged in states in full; the other journeys share enough code that a smaller sample catches most regressions.


Journey

What "pass" looks like

Home, category, search

Each locale renders, no console errors, filters and pagination work

Product detail — configurable product

Option selection updates price, SKU and availability without a full reload. Exercises more of the data layer than a simple product, so a mapping regression shows up here first

Add to cart

Cart count and line-item update for both a standard and a configurable product

Full checkout

Address through order review completes; generalize this to your project's own checkout extension point (custom fields, a reworked billing-address placement, filtered payment options) and confirm it still renders and submits

Account area

Order history, addresses and any project-specific pages load logged in, and redirect anonymous visitors to /login

Login / logout / MFA

Credentials sign-in, failure handling, logout, and the MFA challenge where the store has it enabled

Page Builder round trip

Save, preview and publish a trivial change; confirm it appears on the live page without a restart


Gate 3 - Settings

Verify store-settings-dependent behavior. These only show up on a store configured for the setting in question, not on the default store you use day to day. A baseline change to middleware or the theme configuration is the most likely way one of these silently regresses.


SettingDescription
Login-required storeAnonymous visitors still redirect to /login, except the excluded paths and SEO files.
Maintenance modeTurning it on redirects every request to /maintenance; turning it off restores normal service.
Multi-localeDefault locale has no URL prefix; the other locales' prefix still resolves.
Theme resolution 

Your project's theme config still overrides the baseline widgets after the merge; an unlisted theme still falls back cleanly.

Theme resolution is worth a closer look: the store's theme name must still map to your project's configuration, your project's widget and page-type overrides must still render in place of the baseline ones, and any theme without an entry must still fall back to the base configuration without error


Gate 3B - Cache

Verify cache behavior. The custom server is one of the files most likely to change in a baseline update, so verify it explicitly rather than assuming the merge left it intact.


terminal

# anonymous: run twice, expect MISS then HIT for a public page
curl -sI https://<store-domain>/en-US/<public-page> | grep -i -E "x-anon-cache|cache-control"
# personalized or excluded path: must never show HIT
curl -sI https://<store-domain>/en-US/account/orders | grep -i -E "x-anon-cache|cache-control"


Do publish a real content change in Znode Admin and confirm it appears live without a manual purge. That proves revalidation still fires end to end, not just that the cache headers look right.

Don't assume the manual purge endpoint is a substitute for revalidation working. Use it to confirm it still functions, not as your only check.

Gate 4 - Final Verification

Verify sign-off before you ship. Record the result of every gate so a second person can audit the release without repeating every check. Do not sign off with any unresolved failures.


Area

Result

Notes

Gate 1 — build, lint, automated tests

Pass / Fail

Gate 1b — environment variable diff

Pass / Fail

Gate 2 — critical journeys

Pass / Fail

Gate 3 — store-settings behavior

Pass / Fail

Gate 3b — cache behavior

Pass / Fail

Rollback plan confirmed

Pass / Fail

Sign-off

Approved / Rejected

Name, date


Detailed Checklist


☐ Both apps build and both Docker images build

☐ Lint passes and the full Jest suite passes

☐ No environment variable newly required by the update is missing from any target environment

☐ Home, category, search and both product detail types checked in all locales

☐ Full checkout, including the project's checkout extension, completes logged in

☐ Account area and login/logout verified logged in and logged out

☐ Page Builder save, preview, publish round trip confirmed

☐ Login-required store, maintenance mode and multi-locale checked

☐ Theme and project widget overrides still resolve correctly

☐ Anonymous cache headers correct and a real publish revalidates without a manual purge

Rollback plan

Decide this before you deploy, not after a problem appears in production.


Know the last good releaseEach release is tagged; know which tag was live before this deployment.
Redeploy, don't patch forward under pressureRe-run the same deploy workflow against the previous release tag or commit to rebuild and redeploy the last known-good images.
Try the narrow fix first, if it fitsA stale cache or a missing environment variable can often be corrected without a full rollback.
Verify, then close the loopCheck the health endpoint and the must-verify journeys after rolling back, and record what failed so the next update's pass checks it specifically.


Common issues and where to go next


You see

What it usually means

A package that had tests now shows no test target

A baseline change to nx.json or the package's own config dropped it

A feature works locally but not in the deployed environment

A newly required environment variable is set locally but not on the container

A project widget stopped appearing for your theme

The theme configuration map or the base config's widget list changed in the merge

One visitor sees another visitor's page

A personalized path fell out of the excluded-paths list during the merge

A publish in Znode Admin doesn't show up live

Revalidation broke; check the token and the revalidation endpoint before assuming it's a code bug


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.