Test And Script Guide

This is the guideline document that decides what lives in scripts/tests/ and how scripts/ is used. It does not define Product behaviour; it covers only placement, execution and growth prevention rules. The New-System check selection, environment and execution commands are owned by the test guide.

2026-09-20 relocation: tests/ moved to scripts/tests/, and new-system/tests/ to new-system/scripts/tests/. The structure standard (SYSTEM_STRUCTURE_STANDARD.md §2, §3, §5, §7, §11) was amended the same way. The old paths in historical evidence documents (docs/reference/, docs/performance/evidence/, docs/reconstruction/ and so on) are not rewritten in bulk.

1. Roles At A Glance

scripts/tests/            Legacy proofs (contracts, regressions). No root package.json; see the table below for the runners
new-system/scripts/tests/ New-System proofs across the board (contract/integration/e2e/parity/profile/architecture/quality/runtime/performance)
                          plus the node-test discovery and runners (run-node-tests.mjs, run-field-process.mjs)
scripts/ (everything else) Supporting scripts (gates, smoke, UAT, migrations, one-offs). Not Product runtime
new-system/scripts/ (else) Per-area local tooling. Not Product runtime
scripts/_archive/         Retired Legacy one-off records (not a current execution target)

Keeping the scripts/tests/ execution scripts separate from the scripts/ run scripts is the principle. Checks internal to one owner stay next to the code; suites that verify several owners and the existing suite runners stay at their current place under scripts/tests/.

2. What Actually Runs When Asked To "Run The Tests"

2.1 Legacy (scripts/tests/, 371 in total)

Request	Execution command	Selection scope	Notes
Light gate	scripts/check-fast	3 mjs files only	3 files via node --test + node --check + git diff --check
Full (default)	scripts/check-full	check-fast + 291 scripts/tests/unit/*_test.php	Goes through scripts/run-php-tests.sh --suite=unit
PHP only	scripts/run-php-tests.sh --suite=unit\|integration\|integration-db\|all	scripts/tests/unit, scripts/tests/integration, scripts/tests/integration-db	integration-db is SKIPped without --allow-db-write
69 root contracts	run node --test scripts/tests/<file>.test.mjs directly	Not registered in a runner	No canonical command — the file has to be named in the request. 24 p5_* files make up half of them
E2E	individual runs	scripts/tests/e2e/*	Not part of the default gate

To triage a Legacy screen incident first, run node scripts/browser/gates/gate-legacy-visible-menu-health-no-write.js against the local Legacy runtime. It logs in and sweeps every administrator-visible menu with GET only, and inspects HTTP 500s, browser errors, login redirects and fatal error text. It runs no logout and no write action.

Browser verification before a Legacy deployment prioritises business-button verification over a screen sweep. After confirming the local DB and the no-external-provider boundary, verify create, edit, state change, cancel/delete, DB readback and fixture cleanup with node scripts/smoke/field_process_ui_smoke.js --base-url=<Legacy URL>, and then run the read-only full-menu gate above.

In other words, the 69 root *.test.mjs files and scripts/tests/e2e do not run from the single phrase "run the tests". Name the file in the request when they are needed.

2.2 New-System

Check the verification layers, execution commands and the real discovery scope in the New-System test guide. The command source is package.json; the browser environment is the browser guide and the config/fixture of the suite in question.

3. Where A Test Goes

1. Module-local tests belong next to their owner. Only cross-owner proofs go in scripts/tests/. (apps/web/tests, packages/*/src/**/*.test.ts are not relocation targets.)
2. Legacy contracts and regressions → scripts/tests/*.test.mjs (naming: <target>_<topic>_contract.test.mjs).
3. Legacy PHP unit tests → scripts/tests/unit/*_test.php (run-php-tests.sh collects only this pattern).
4. New-System → new-system/scripts/tests/<contract|integration|e2e|parity|profile|architecture|quality|runtime|performance>/.
5. Runners, discovery and checkers are not tests → directly under new-system/scripts/tests/ (for example run-node-tests.mjs) or in the per-area scripts/<area>/. See §1.
6. The test_* files in scripts/probes/ are legacy probes; new ones are forbidden (the TEST_INDEX rule still applies). Put new verification in the locations in 2–4.

4. Rules Against Unchecked Growth

1. The location of a new test follows §3 and the existing structure standard. Adding to the list in this guide is not a structural change approval.
2. File names follow the naming rules in scripts/TEST_INDEX.md (existing names are frozen).
3. Do not create a test that no runner picks up. Confirm it is caught by the run-php-tests.sh pattern (*_test.php) or by a package.json selector.
4. One-off work follows the existing creation and retention criteria in §5.2.
5. Adding scripts/tests/parity or scripts/tests/e2e only when a Task names it. It is not part of the foundation gate, so leaving it undocumented rots.

5. Using The Scripts

5.1 Categories

Location	Nature	Treatment
scripts/check-fast, check-full, run-php-tests.sh, run_full_runtime_test.js, ctc-task*, lib/	Reusable gates, runners, CLIs, shared lib	KEEP. Run the §2 regression when changing
scripts/browser/{verify,gates,uat,probes,popup}/, scripts/smoke/, scripts/probes/	Purpose-specific browser, smoke and probe work (restructured 2026-09-20, owned by scripts/TEST_INDEX.md)	KEEP. Confirm the target environment and whether it writes before running
scripts/migrations/*.sql	Migration ledger	Do not touch. With no applied ledger it is impossible to tell what has been applied, and a rollback path is needed
scripts/_archive/ (75 files)	Retired one-offs (mk-excel-import, repairs, rebuilds, migrate-mk, slices-r6/r7, stale tests)	Never run. Revival is git mv + path fix + TEST_INDEX registration
scripts/tailwind-runtime/, terminal-autofill/, kj-table-bundle/, kj-ui-standard/, data-import/**/vendor/	Vendor and build output	Not part of test/script cleanup. Managed separately
New-System local tooling	the script guide	The real owner and execution path are confirmed in that area

5.2 One-Off Rules

File creation, retention and retirement follow the existing file creation criteria. There is no separate 7-day retention rule, no automatic archive move, and no per-script log or report copy. Raw results needed for reproduction, audit or recovery are preserved in the owning Task and the existing evidence locations. DB writes are dry-run by default as before, and are not performed without an approved target and an explicit execution confirmation.

---

Source: docs/TEST_AND_SCRIPTS_GUIDE.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.