Docs/Developer Guide/Build, Test & Verify

Build, Test & Verify

Basis: README.md §3, CONTRIBUTING.md, web/package.json, web-admin/package.json, core/Dockerfile, Makefile, .github/workflows/*.yml. Commands quoted from those files.
Principle: Be exact about verification state: compiled ≠ tested ≠ deployed-to-staging ≠ deployed-to-prod. "Merged" is not "deployed".

1. Backend (`core/`)

cd core && mvn clean verify          # full build + tests (README)
mvn -pl <module> test                # one module

Use mvn clean, not a bare mvn test, after any Flyway rename: stale compiled migrations under target/classes shadow the real ones (README §3).
JDK: 21 is the compile target; maintainers build with JDK 24 (CONTRIBUTING.md). Run one Maven build at a time — parallel builds in one checkout fight over target/.
-am builds dependencies, never dependents. For a signature change in a shared module, verify with the command the image build actually runs (core/Dockerfile runs mvn -q -B -pl ${MODULE} -am -Dmaven.test.skip=true package):
```
cd core && mvn -o -pl app -am -Dmaven.test.skip=true package
```

Command	Answers
`mvn -pl app -am -Dmaven.test.skip=true package` (full reactor)	Does every dependent still compile against my changed signature?
`mvn -pl <mymodule> test`	Is my own change correct?
One full reactor build from a clean tree before shipping	Does what I am about to deploy build without uncommitted local work?

2. Frontends (`web/`, `web-admin/`)

Script	web	web-admin
`npm run dev`	`next dev -p 3000` (`predev` vendors WebLLM/Kokoro/Babel)	`next dev -p 3001`
`npm run build`	`next build` (`prebuild` runs i18n route namespaces + vendor scripts)	`next build`
`npm run lint`	`eslint .`	`eslint .`
`npm run typecheck`	`tsc --noEmit`	`tsc --noEmit`
`npm test`	`vitest run` (also `test:watch`)	`vitest run` (also `test:watch`)
e2e	`e2e`, `e2e:ui`, `e2e:report`, `e2e:showcase` (Playwright)	—

tsc is not a sufficient gate

While tsconfig is mid-strictness-ratchet (strict: false), next build is stricter than npx tsc --noEmit and has failed on code that passed tsc. Run npm run build, or accept that the image build is your first real compile.

3. Python services and other packages

sidecar — services/sidecar/requirements-dev.txt says to run the suite from services/sidecar/ with pytest tests/.
code-intel, app-builder, voice-agent, rl-trainer and tool-sandbox (all under services/) — each has its own tests; see their READMEs for the test entry point.
Public-surface E2E (tests/e2e/, own package) — npm test (Playwright); it targets a real deployed domain, never localhost; base URL via E2E_BASE_URL (tests/e2e/README.md).
Load tests (tests/load/) — k6 harness; read its README before running anything.

4. The merge gate (static gates)

Fast, no toolchain. Run before pushing; make gates runs all of them (CONTRIBUTING.md):

make gates          # everything below
bash scripts/ci/flyway-lint.sh
bash scripts/ci/entity-name-lint.sh
bash scripts/ci/skip-expiry.sh
sh   scripts/ci/check-file-size.sh
bash scripts/ci/secret-scan.sh

Details of each gate live in CONTRIBUTING.md and on Quality Gates & CI Checks. The .githooks/pre-push hook runs the same scripts (see Git & Contribution Workflow).

5. Verification before a production core image

Rule: no production core deploy without a boot check. Build the reactor jar (mvn -pl app -am -Dmaven.test.skip=true package), boot it against a throwaway container of the release postgres image (deploy/postgres: pgvector + AGE), and confirm all migrations apply, Hibernate validate passes and Started CoreApplication appears. Rationale: duplicate-bean and constructor-injection failures have compiled and passed tests but crash-looped core at startup.

Build images from a clean checkout, never a working tree with local edits: stray .env*.local files override build args (make images builds the Full-tier images from source). See the Deployment Guide.

6. CI

Eight workflows live in .github/workflows/: ci.yml, static-gates.yml (called from ci.yml), codeql.yml, scorecard.yml, release.yml, e2e.yml, labeler.yml and stale.yml. Pull requests run CI (summary check CI OK, which includes the static gates) and CodeQL; the local equivalents are:

make test      # core, web, web-admin, python
make lint      # eslint + tsc, ruff, shellcheck
make gates     # static gates + secret scan
make compose-validate
make helm-lint

See CI/CD Pipelines for triggers and jobs. Install the pre-push hook with make hooks.

Evidence & references

README.md §3 Testing; CONTRIBUTING.md "Checks".
web/package.json, web-admin/package.json, tests/e2e/package.json, tests/e2e/README.md, services/sidecar/requirements-dev.txt.
core/Dockerfile line with -Dmaven.test.skip=true package.
Makefile; .github/workflows/ci.yml, static-gates.yml (job lists); .githooks/pre-push.