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.

fix(test): present settings frames on one shared virtual display

yhh57b85aed90f5
diff --git a/.github/workflows/settings-restart.yml b/.github/workflows/settings-restart.yml
index 881467bc1..cc9f65bae 100644
--- a/.github/workflows/settings-restart.yml
+++ b/.github/workflows/settings-restart.yml
@@ -48,6 +48,7 @@ jobs:
const spec = GOLDEN.find(project => project.id === 'audio-demo').settings;
const run = spawnSync(process.execPath, ['tools/verify-settings.mjs',
'--dir', 'output/settings-web', '--spec', JSON.stringify(spec),
+ '--present',
'--log', 'output/settings-restart/process.log'], { stdio: 'inherit' });
if (run.error) throw run.error;
process.exit(run.status ?? 1);
diff --git a/tools/launchers/launch-export.mjs b/tools/launchers/launch-export.mjs
index ea3957dd4..278001c0e 100644
--- a/tools/launchers/launch-export.mjs
+++ b/tools/launchers/launch-export.mjs
@@ -24,6 +24,7 @@
* --timeout <ms> how long to wait for the first frame (default 30000)
* --scene <name> boot this named scene instead of the package's entry
* --port <n> serve on a fixed loopback port for same-origin restart tests
+ * --present present without taking focus, for virtual-desktop frame checks
* --allow-flat accept a single-colour frame (a deliberately blank scene)
* --input <json> drive it: {"keys":["ArrowRight"]} or {"pointer":{"x":.5,"y":.5}}
* --touch present as a touch device (maxTouchPoints > 0), so a
@@ -113,6 +114,7 @@ const LOG = flag('log', '');
const THROTTLE = flag('throttle', '');
/** Report when the first screen appeared and how its progress moved. */
const BOOT = has('boot');
+const PRESENT = BOOT || has('present');
const logRe = LOG ? new RegExp(LOG, 'i') : null;
/**
@@ -271,14 +273,14 @@ const SCENE = flag('scene', '');
// Before the load, and through Chrome's own emulation rather than a hand-rolled
// server: the numbers are the vendor's, and a recorder installed here runs in
// the page's own world ahead of every script the page carries.
- if (THROTTLE || BOOT) {
+ if (THROTTLE || PRESENT) {
// A window that has never navigated answers no CDP command — `Page.enable`
// simply never resolves. One blank document is enough to make it a page.
- if (BOOT) win.showInactive();
- await win.loadURL(BOOT
+ if (PRESENT) win.showInactive();
+ await win.loadURL(PRESENT
? 'data:text/html,<body style="font:14px system-ui;background:%230e121b;color:white">Estella</body>'
: 'about:blank');
- if (BOOT) {
+ if (PRESENT) {
// Players navigate in an already-presented browser. Settle the virtual
// desktop compositor before navigation timing starts, not during it.
await win.webContents.executeJavaScript('new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)))');
diff --git a/tools/lib/electronRun.mjs b/tools/lib/electronRun.mjs
index 75c4385a7..a3fe3e69d 100644
--- a/tools/lib/electronRun.mjs
+++ b/tools/lib/electronRun.mjs
@@ -55,6 +55,13 @@ const SCREEN = '-screen 0 1920x1080x24';
export const NEEDS_XVFB = process.platform === 'linux'
&& !process.env.DISPLAY && !process.env.ESTELLA_NO_XVFB;
+/** Keep one display alive for a Node controller and all of its Electron children. */
+export function runWithElectronDisplay(args, options = {}) {
+ return NEEDS_XVFB
+ ? runTool('xvfb-run', ['-a', '--server-args', SCREEN, process.execPath, ...args], options)
+ : runTool(process.execPath, args, options);
+}
+
/**
* Run Electron with a script and its arguments, under whatever this host needs.
*
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 7e1e3a04d..d1aefe6c4 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -32,6 +32,8 @@ export const NOTED = {
{ note: 'Navigation replacements commit only from the latest request.' },
'feat(nav): stage cancellable surface replacements and explain pending routes':
{ note: 'Navigation replacements commit only from the latest request.' },
+ 'fix(test): present settings frames on one shared virtual display':
+ { internal: 'The shared Electron owner can host a controller and all restart processes on one virtual display. CI presents package windows without taking focus, avoiding hidden-window frame throttling while preserving deadlines and full failure evidence.' },
'fix(test): replay settings transactions after confirmed GPU loss':
{ internal: 'Settings acceptance applies the shared bounded GPU failure policy to whole fresh-profile transactions, preserving each failed attempt and screenshot while refusing retries for ordinary process or settings failures.' },
'test(nav): yield fixed-step capture work to the compositor':
diff --git a/tools/tests/settings-verifier.test.ts b/tools/tests/settings-verifier.test.ts
index c367f9004..f2debdcdc 100644
--- a/tools/tests/settings-verifier.test.ts
+++ b/tools/tests/settings-verifier.test.ts
@@ -15,6 +15,8 @@ it.each(['pass', 'killed', 'wrong-label', 'gpu-once', 'gpu-then-wrong-label'])('
name:'fixture-only-launcher',setup(builder){
builder.onResolve({filter:/electronRun\.mjs$/},()=>({path:'run',namespace:'fixture'}));
builder.onLoad({filter:/.*/,namespace:'fixture'},()=>({contents:`
+ export const NEEDS_XVFB=false;
+ export function runWithElectronDisplay(){throw new Error('Unexpected display launch in fixture');}
let launch=0; const profiles=new Map();
export function runElectron(args) {
const globalStep=launch++, mode=${JSON.stringify(mode)};
diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjs
index f5c8574fb..83b004469 100644
--- a/tools/verify-golden.mjs
+++ b/tools/verify-golden.mjs
@@ -426,7 +426,8 @@ for (const { id, target } of pairs) {
if (golden.settings && target === 'web') {
const settingsLog = path.join(WORK, `${id}-${target}-settings.log`);
const run = spawnSync(process.execPath, [path.join(ROOT, 'tools/verify-settings.mjs'),
- '--dir', out, '--spec', JSON.stringify(golden.settings), '--log', settingsLog], { cwd: ROOT, encoding: 'utf8' });
+ '--dir', out, '--spec', JSON.stringify(golden.settings), '--log', settingsLog,
+ ...(process.env.CI ? ['--present'] : [])], { cwd: ROOT, encoding: 'utf8' });
const ok = run.status === 0;
results.push({ id, target, stage: 'settings', ok, why: ok ? '' : String(run.stderr || run.stdout || 'settings verifier did not complete')
+ `\nsettings verifier exit=${run.status ?? 'none'}, signal=${run.signal ?? 'none'}; full launch trace: ${settingsLog}` });
diff --git a/tools/verify-settings.mjs b/tools/verify-settings.mjs
index 713d78ff4..5834fd2c0 100644
--- a/tools/verify-settings.mjs
+++ b/tools/verify-settings.mjs
@@ -4,7 +4,7 @@ import path from 'node:path';
import net from 'node:net';
import { appendFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import os from 'node:os';
-import { runElectron } from './lib/electronRun.mjs';
+import { NEEDS_XVFB, runElectron, runWithElectronDisplay } from './lib/electronRun.mjs';
import { gpuFailed, retryOnDeadGpu } from './lib/deadGpu.mjs';
import { fileURLToPath } from 'node:url';
@@ -14,6 +14,12 @@ const flag = name => { const i = args.indexOf('--' + name); return i < 0 ? undef
const dir = flag('dir'), specArg = flag('spec');
if (!dir || !specArg) throw new Error('verify-settings requires --dir and --spec');
const spec = JSON.parse(specArg);
+if (NEEDS_XVFB) {
+ const run = runWithElectronDisplay([fileURLToPath(import.meta.url), ...args], {cwd: root, stdio: 'inherit'});
+ if (run.error) throw run.error;
+ process.exit(run.status ?? 1);
+}
+const present = args.includes('--present');
const log = flag('log');
const record = value => {
if (!log) return;
@@ -37,11 +43,14 @@ function runAttempt() {
const restart = i === spec.expected.length;
const pointer = restart ? spec.unlock : spec.control;
const screenshot = log ? path.resolve(`${log}.attempt-${attempt}.launch-${i}.png`) : null;
+ const began = performance.now();
const run = runElectron(['--user-data-dir=' + profile, path.join(root, 'tools/launchers/launch-export.mjs'),
'--dir', path.resolve(dir), '--port', String(port), '--w', String(spec.w), '--h', String(spec.h),
'--input', JSON.stringify({ pointer, frames: spec.frames ?? 60 }), '--probe', names.join(','),
+ ...(present ? ['--present'] : []),
...(screenshot ? ['--out', screenshot] : [])], { cwd: root, encoding: 'utf8' });
record({kind: 'launch', attempt, step: i, restart, screenshot, expected: spec.expected[restart ? i - 1 : i],
+ elapsedMs: Math.round(performance.now() - began),
status: run.status, signal: run.signal ?? null, timedOut: !!run.timedOut,
error: run.error?.message, stdout: run.stdout ?? '', stderr: run.stderr ?? ''});
if (run.status !== 0) {