Maintainer verification

Use these procedures when changing Atrium itself. Run commands from the Atrium repository root after development setup, except where a temporary directory is explicitly selected. Application developers should use the separate application acceptance checklist.

The 2026-09-18 verification record preserves earlier results and limitations. Rerun relevant checks for the current changes and report what actually passed. No command in this guide publishes a package, creates a release, or deploys remotely.

Quality gates

Run the smallest relevant check while iterating. Run the full repository gate for broad changes:

yarn check

This checks JavaScript, formatting, source headers, prose, EditorConfig, unit coverage, and both production builds. Coverage requires 100% statements, branches, functions, and lines per included file. Reports are written under .reports/coverage/. See coverage details.

For Markdown edits, run yarn lint:prose and Prettier on the affected documentation. Check relative links, heading anchors, source links, and moved-path references. EditorConfig uses tracked paths by default, so pass new document paths explicitly when checking them without staging changes.

Review Git status and generated output after broad checks, and preserve existing user changes and staging.

Run affected browser workflows for markup, styling, routing, lifecycle, or layout changes. Repository-wide source moves require the full production browser suite and the isolated package check below. Documentation restructuring must also preserve package README links and runnable integration examples.

Native development browser checks

With yarn dev running in another terminal, install Chromium once if necessary and run:

yarn playwright install chromium
yarn test:e2e

The default URL is http://127.0.0.1:5173/. Deployment fixtures and production chunk tests are skipped unless their environment variables are supplied. This development run is not a production CSP or deployment check. Stop the server with Ctrl+C when finished. Browser reports go to playwright-report/, with failure artifacts and screenshots in test-results/.

Verify unpublished packages and generated applications

This is a maintainer test of unpublished packages. Normal application onboarding installs released versions from the remote registry. From the repository root:

node src/scripts/ci/helpers/build-package.js
node src/scripts/ci/helpers/build-consumer.js

The first helper packs all four synchronized workspaces and records integrity proofs. The second installs both template packages in separate temporary applications, resolving their core and publisher dependencies to those archives. It executes each installed publication command, installs the merged application dependencies, and builds the generated source. No manual template copying is involved. The showcase also builds at /control-panel/.

The outputs are .build/consumer/starter/, .build/consumer/showcase/, and .build/consumer/showcase-subpath/. Temporary application sources and lockfiles are disposable and removed by the helper. This check needs no Atrium registry token, although it needs access to third-party dependencies or a suitable cache. Package allowlists must include nested template assets and maintained src/atrium/build/ Vite helpers. Generated .build/, dist/, dist-*/, and dependencies do not belong in source archives.

Reproduce production deployment checks

With Chromium available locally, run the workspace and packaged application suites:

yarn playwright install chromium
yarn build
APP_BASE=/control-panel/ yarn workspace @agon/atrium-showcase build --outDir dist-subpath
yarn playwright test --config playwright.ci.config.mjs
ATRIUM_PACKED_CONSUMER=true yarn playwright test --config playwright.ci.config.mjs

Run the package helpers above before the second suite. The CI configuration owns fixture servers and stops them automatically. The ordinary run serves the workspace showcase at port 4175 and its subdirectory build at port 4176. The packaged run serves the generated showcase at those same ports and adds the generated starter at port 4177. Both run the full production showcase workflows. The packaged run additionally verifies starter integration. They test production CSP, history fallback, genuine missing-asset errors, lazy pages, accessibility, native surfaces, and responsive layouts.

If native Chromium cannot start, use local CI, which runs the same configuration inside the pinned Playwright Docker image. yarn ci:local browser builds and tests workspace production fixtures. yarn ci:local smoke includes quality prerequisites, all four archives, generated applications, and their full browser suite. yarn ci:local full also includes dependency-cache warmup and executes shared prerequisites once.

Reports appear under .reports/browser/, playwright-report/, and test-results/ for host checks, or beneath the corresponding local CI job artifact directory. Inspect failures and report exact results, skipped checks, and remaining services. The fixture binds to 0.0.0.0 for container access and is intended only for verification. The managed suites stop their fixture processes when finished.

Clean source verification

To prove ignored files and workspace links are not masking missing source, export the intended staged snapshot into a fresh directory. Stage only reviewed changes when doing this deliberately. Do not change another developer’s staging as part of an unrelated check:

AGON_SOURCE_VERIFY_DIR=$(mktemp -d "${TMPDIR:-/tmp}/agon-atrium-source-check.XXXXXX")
git checkout-index --all --prefix="$AGON_SOURCE_VERIFY_DIR/"
(
  cd "$AGON_SOURCE_VERIFY_DIR"
  git init -b verification
  git add .
  yarn install --immutable
  yarn check
)

The temporary Git index lets EditorConfig inspect exported files. This checks the index, not unstaged edits. The copy starts without dependencies, or builds. No commit, remote, or server is involved. Review and remove that specific temporary copy when finished.

Local CI and preview images

For the complete allowlisted GitLab verification graph in Docker, follow local CI setup. yarn ci:local full runs lint, unit coverage, production browser tests, and independent package consumption. It manages its own fixture servers. Release and publication jobs are separate hosted actions and must never be run locally.

After a passing full run, visually inspect the production screenshots before promoting them to README images. From the repository root:

cp .gitlab-ci-local/artifacts/testOge2eOgbrowser/test-results/dashboard-dark.png docs/images/dashboard-dark.png
cp .gitlab-ci-local/artifacts/testOge2eOgbrowser/test-results/dashboard-light.png docs/images/dashboard-light.png
cp .gitlab-ci-local/artifacts/testOge2eOgbrowser/test-results/catalogue-dark.png docs/images/catalogue-dark.png
cp .gitlab-ci-local/artifacts/testOge2eOgbrowser/test-results/catalogue-light.png docs/images/catalogue-light.png

Keep descriptive alt text and full-size image links. Use the real 1440 × 1000 browser viewport with fullPage: false. Full-document screenshots misrepresent a viewport-height pinned sidebar beside a long page. Refresh maintained previews after material visual changes, not merely because a new test run produced files.

Author

Laurent Declercq l.declercq@agon-innovation.ch

License

Unless otherwise stated all source code is licensed under LGPL 2.1 and has the following copyright:

© 2026, Agon Partners Innovation AG, All rights reserved.

The design material and the “Agon Ātrium” trademark is the property of their authors. Reuse of them without prior consent of their respective authors is strictly prohibited.

Version

Version: 20260921