Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(gates): --suites related runs of an owed suite only the tests that reach what changed - where its runner can follow imports from every changed file, and the whole suite where it cannot; the run names each suite it ran in part

yhh7152728f5956
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 6ac731fe8..9d072ac29 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -34,6 +34,8 @@ export const SCOPES = ['local', 'ci'];
* that run a suite — orthogonal to `where`, which says a gate CANNOT run here.
* `owns` is the other half: the SOURCE a suite answers for, and `--suites owed`
* runs the ones a change touched, so it meets its unit-test owner before the remote.
+ * `related` is how a suite runs IN PART: `root`, the package its runner takes paths from, and `run`, the command the changed files are
+ * handed to, which runs the tests that reach them (`--suites related`, see relatedRun). A suite without one is run whole.
*/
export const GATES = [
// `exclusive: true` is a build or a writer of what a later gate reads: a `--jobs` run cuts the list there and runs it alone.
@@ -113,11 +115,13 @@ export const GATES = [
// The engine's own TS suites (pipeline + tooling). They lived in desktop/tests
// until the editor split, where a checkout without the editor ran none of them.
{ id: 'engine-tests', run: 'pnpm run test', covers: ['pipeline/tests', 'tools/tests'],
- owns: ['pipeline', 'tools'] },
+ owns: ['pipeline', 'tools'],
+ related: { root: '.', run: 'pnpm exec vitest related --run --config vitest.engine.config.ts' } },
// The SDK's own suites. They were run by NOTHING until 2026-08-30: the gate
// list said 76/76 while four of them did not compile against the source they
// test, and only a hand-run vitest found it.
- { id: 'sdk-tests', run: 'pnpm --filter ./sdk test', covers: ['sdk/tests'], owns: ['sdk'] },
+ { id: 'sdk-tests', run: 'pnpm --filter ./sdk test', covers: ['sdk/tests'], owns: ['sdk'],
+ related: { root: 'sdk', run: 'pnpm --filter ./sdk exec vitest related --run' } },
// The AOT compiler carries its own oracle: a real example system lowered to
// EIR must move a world exactly the way node moves it.
// It also compiles the emitted C and requires the same bytes back: natively
@@ -425,6 +429,31 @@ export function owedSuites(changed) {
return owed;
}
+/** The most changed files a suite is run in part for: past it the whole suite is the cheaper answer and the surer one. */
+export const RELATED_MOST = 80;
+
+/**
+ * How `gate` runs in part for `changed`: the command that runs only the tests that reach what changed under it, and how many files
+ * that is. Null where the whole suite is owed instead, which is every case this cannot answer for: a suite with no `related`, a change
+ * that is not TypeScript source its runner can follow (a config, a fixture, a generated binary: anything may read those), a file that
+ * is gone (what imported it is not named by its path any more), or more files than RELATED_MOST.
+ *
+ * @details A runner follows imports, so a test that reads a changed file some other way (a path it builds, a file it opens) is missed.
+ * That is why this is a mode a caller asks for by name and the run says so, and why CI runs every suite whole.
+ */
+export function relatedRun(gate, changed, exists = () => true) {
+ if (!gate.related || !gate.owns) return null;
+ const mine = changed.filter((p) => under(p, gate.owns));
+ if (mine.length === 0 || mine.length > RELATED_MOST) return null;
+ const root = gate.related.root === '.' ? '' : `${gate.related.root}/`;
+ const files = [];
+ for (const p of mine) {
+ if (!/\.(ts|tsx|mts)$/.test(p) || /(^|\/)[^/]*\.config\.[a-z]+$/.test(p) || !p.startsWith(root) || !exists(p)) return null;
+ files.push(p.slice(root.length));
+ }
+ return { run: `${gate.related.run} ${files.map((f) => `"${f}"`).join(' ')}`, files: files.length };
+}
+
/**
* The gates a scope runs, in declaration order. `hasEditor` gates the editor
* ones; `suites` is 'all', 'none', or the set of suite ids a diff owes.
diff --git a/tools/run-gates.mjs b/tools/run-gates.mjs
index f895bec56..efe07256a 100644
--- a/tools/run-gates.mjs
+++ b/tools/run-gates.mjs
@@ -17,6 +17,7 @@
* node tools/run-gates.mjs --scope local
* node tools/run-gates.mjs --scope ci
* node tools/run-gates.mjs --scope local --suites owed
+ * node tools/run-gates.mjs --scope local --suites related
* node tools/run-gates.mjs --scope local --where local
* node tools/run-gates.mjs --scope local --keep-going --matrix out.json
*/
@@ -24,7 +25,7 @@ import { execFileSync, spawn, spawnSync } from 'node:child_process';
import { existsSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
-import { SCOPES, GATES, gatesFor, owedSuites } from './gates.mjs';
+import { SCOPES, GATES, gatesFor, owedSuites, relatedRun } from './gates.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const argv = process.argv.slice(2);
@@ -45,12 +46,13 @@ if (!SCOPES.includes(SCOPE)) {
const HAS_EDITOR = existsSync(path.join(ROOT, 'desktop', 'package.json'));
/**
* Which suite gates this caller pays for: `all` (default, and CI), `owed` (those
- * whose `owns` this change touched), or `none`.
+ * whose `owns` this change touched), `related` (those, and of each only the tests
+ * that reach what changed, where its runner can say which), or `none`.
*
* @details A machine that cannot run an owed suite is not silently excused: it
* says what it needs and the run stops, per check-suite-preconditions.
*/
-const SUITE_MODES = ['all', 'owed', 'none'];
+const SUITE_MODES = ['all', 'owed', 'related', 'none'];
if (argv.includes('--no-suites')) {
console.error('run-gates: --no-suites is now --suites none (or --suites owed).');
process.exit(2);
@@ -79,8 +81,9 @@ function changedPaths() {
return [...new Set(out.split('\n').map((l) => l.trim()).filter(Boolean))];
}
-const changed = SUITE_MODE === 'owed' ? changedPaths() : [];
-const SUITES = SUITE_MODE === 'owed' ? owedSuites(changed) : SUITE_MODE;
+const BY_CHANGE = SUITE_MODE === 'owed' || SUITE_MODE === 'related';
+const changed = BY_CHANGE ? changedPaths() : [];
+const SUITES = BY_CHANGE ? owedSuites(changed) : SUITE_MODE;
/**
* Whether every DECLARED gate has to have run, not just every gate that could.
*
@@ -96,6 +99,10 @@ const COMPLETE = argv.includes('--complete');
* second question cannot be answered one re-run at a time.
*/
const SCAN = argv.includes('--keep-going');
+if (COMPLETE && SUITE_MODE === 'related') {
+ console.error('run-gates: --suites related cannot be --complete — a suite run in part answers for the tests it ran.');
+ process.exit(2);
+}
/** Where to write the matrix, for a reader that is not a terminal. */
const MATRIX = (() => {
const i = argv.indexOf('--matrix');
@@ -155,8 +162,16 @@ if (WHERE && !SCOPES.includes(WHERE)) {
console.error(`run-gates: unknown --where "${WHERE}" (have: ${SCOPES.join(', ')})`);
process.exit(2);
}
+/** The suites run in part, and for how many changed files each: a green from one of them is about those tests only. */
+const inPart = new Map();
const gates = gatesFor(SCOPE, HAS_EDITOR, { suites: SUITES })
- .filter((g) => (!ONLY || ONLY.includes(g.id)) && (!WHERE || g.where === WHERE));
+ .filter((g) => (!ONLY || ONLY.includes(g.id)) && (!WHERE || g.where === WHERE))
+ .map((g) => {
+ const part = SUITE_MODE === 'related' ? relatedRun(g, changed, (p) => existsSync(path.join(ROOT, p))) : null;
+ if (!part) return g;
+ inPart.set(g.id, part.files);
+ return { ...g, run: part.run };
+ });
/** Either form answers for the gates it selected and for nothing else. */
const NARROWED = Boolean(ONLY || WHERE);
if (NARROWED) {
@@ -182,10 +197,10 @@ if (NARROWED) {
const skipped = GATES.filter((g) => g.where && g.where !== SCOPE);
/** Suites this run is not paying for — named, never silently absent. */
const unpaid = gatesFor(SCOPE, HAS_EDITOR)
- .filter((g) => g.covers?.length && !gates.includes(g));
+ .filter((g) => g.covers?.length && !gates.some((ran) => ran.id === g.id));
/** Everything a narrowing left out, suites included: such a run answers for the
* gates it selected and nothing else, and must not read as a list that went green. */
-const narrowed = NARROWED ? gatesFor(SCOPE, HAS_EDITOR).filter((g) => !gates.includes(g)) : [];
+const narrowed = NARROWED ? gatesFor(SCOPE, HAS_EDITOR).filter((g) => !gates.some((ran) => ran.id === g.id)) : [];
const noEditor = HAS_EDITOR ? [] : GATES.filter((g) => g.needs === 'editor' && (!g.where || g.where === SCOPE));
console.log(`gates ${SCOPE}: ${gates.length} of ${GATES.length}`);
if (noEditor.length) {
@@ -208,7 +223,11 @@ if (argv.includes('--plan')) {
*/
function reportSuites() {
const suites = gates.filter((g) => g.covers?.length);
- if (suites.length) console.log(` test suites run: ${suites.map((g) => g.id).join(', ')}`);
+ const whole = suites.filter((g) => !inPart.has(g.id));
+ if (whole.length) console.log(` test suites run: ${whole.map((g) => g.id).join(', ')}`);
+ for (const [id, files] of inPart) {
+ console.log(` test suite run IN PART: ${id} — only the tests that reach the ${files} changed file(s) under it; CI runs it whole`);
+ }
// A declared profile narrows what a suite covered, and the summary is where
// that has to be said — otherwise "green" quietly means "green minus 300".
for (const g of declared) console.log(` ${g.env}=${g.value} — ${g.says}`);
@@ -219,12 +238,12 @@ function reportSuites() {
// The whole point of not paying for a suite is that it is CHEAP, not that it
// is quiet. Under `owed` the count of paths is part of the claim: "no suite was
// owed" means nothing unless it is attached to a diff that was actually read.
- if (SUITE_MODE === 'owed') {
+ if (BY_CHANGE) {
console.log(` ${changed.length} changed path(s) read for suite ownership`
+ `${SUITES.size ? '' : ' — none of them under a suite\'s `owns`'}`);
}
if (unpaid.length && !NARROWED) {
- const why = SUITE_MODE === 'owed'
+ const why = BY_CHANGE
? 'nothing changed under what they answer for; CI runs them all'
: `--suites ${SUITE_MODE}; CI runs them`;
console.log(` test suites NOT run: ${unpaid.map((g) => g.id).join(', ')} — ${why}`);
diff --git a/tools/tests/suite-ownership.test.ts b/tools/tests/suite-ownership.test.ts
index 1740f4dc9..2552b6752 100644
--- a/tools/tests/suite-ownership.test.ts
+++ b/tools/tests/suite-ownership.test.ts
@@ -9,7 +9,7 @@
*/
import { describe, it, expect } from 'vitest';
// @ts-expect-error — a repo tool, shipped as .mjs with no declarations
-import { GATES, owedSuites } from '../gates.mjs';
+import { GATES, owedSuites, relatedRun, RELATED_MOST } from '../gates.mjs';
const owed = (...paths: string[]): string[] => [...owedSuites(paths)].sort();
@@ -56,3 +56,32 @@ describe('owedSuites names the direct unit-test owner of a change', () => {
expect(orphans).toEqual([]);
});
});
+
+describe('relatedRun runs a suite in part only where its runner can say which part', () => {
+ const gate = (id: string) => (GATES as { id: string }[]).find((g) => g.id === id)!;
+
+ it('hands the changed sources, by the paths of its package, to the runner that follows imports', () => {
+ const part = relatedRun(gate('sdk-tests'), ['sdk/src/foliage/builder.ts', 'sdk/tests/foliage-builder.test.ts', 'docs/x.md']);
+ expect(part.files).toBe(2);
+ expect(part.run).toBe('pnpm --filter ./sdk exec vitest related --run "src/foliage/builder.ts" "tests/foliage-builder.test.ts"');
+ expect(relatedRun(gate('engine-tests'), ['pipeline/src/world/cookWorld.ts']).run)
+ .toBe('pnpm exec vitest related --run --config vitest.engine.config.ts "pipeline/src/world/cookWorld.ts"');
+ });
+
+ it('owes the whole suite for what no import names: a config, a fixture, a script, a file that is gone', () => {
+ const sdk = gate('sdk-tests');
+ expect(relatedRun(sdk, ['sdk/package.json'])).toBeNull();
+ expect(relatedRun(sdk, ['sdk/vitest.config.ts'])).toBeNull();
+ expect(relatedRun(sdk, ['sdk/src/a.ts', 'sdk/tests/fixtures/scene.json'])).toBeNull();
+ expect(relatedRun(gate('engine-tests'), ['tools/gates.mjs'])).toBeNull();
+ expect(relatedRun(sdk, ['sdk/src/gone.ts'], () => false)).toBeNull();
+ });
+
+ it('owes the whole suite past the most files, for a suite with no runner of the kind, and nothing where nothing changed under it', () => {
+ const many = Array.from({ length: RELATED_MOST + 1 }, (_, i) => `sdk/src/f${i}.ts`);
+ expect(relatedRun(gate('sdk-tests'), many)).toBeNull();
+ expect(relatedRun(gate('sdk-tests'), many.slice(1)).files).toBe(RELATED_MOST);
+ expect(relatedRun(gate('editor-tests'), ['desktop/src/a.ts'])).toBeNull();
+ expect(relatedRun(gate('sdk-tests'), ['pipeline/src/a.ts'])).toBeNull();
+ });
+});