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.

test(settings): retain restart diagnostics and focused CI evidence

yhh31a915dd1453
diff --git a/.github/workflows/settings-restart.yml b/.github/workflows/settings-restart.yml
new file mode 100644
index 000000000..881467bc1
--- /dev/null
+++ b/.github/workflows/settings-restart.yml
@@ -0,0 +1,62 @@
+name: Settings restart acceptance
+
+on:
+ workflow_dispatch:
+ inputs:
+ artifact-run:
+ description: Build run with a successful Web artifact from identical runtime sources
+ type: string
+ required: true
+
+permissions:
+ contents: read
+ actions: read
+
+jobs:
+ settings:
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ fetch-depth: 0
+ - uses: ./.github/actions/setup
+ - name: Require matching sources and a successful Web build
+ env:
+ GH_TOKEN: ${{ github.token }}
+ ARTIFACT_RUN: ${{ inputs.artifact-run }}
+ run: |
+ [[ "$ARTIFACT_RUN" =~ ^[0-9]+$ ]]
+ source=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$ARTIFACT_RUN" --jq .head_sha)
+ git diff --exit-code "$source" HEAD -- src sdk native include CMakeLists.txt package.json toolchain.manifest.json build-tools pipeline
+ passed=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$ARTIFACT_RUN/jobs?per_page=100" --jq '[.jobs[] | select(.name == "Web (Emscripten)" and .conclusion == "success")] | length')
+ test "$passed" -eq 1
+ gh run download "$ARTIFACT_RUN" --repo "$GITHUB_REPOSITORY" --name wasm-web --dir build/wasm/web
+ - name: Install virtual display dependencies
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y xvfb libasound2t64 libgtk-3-0t64 libgbm1
+ - name: Build the SDK and export the audio settings scene
+ run: |
+ pnpm --filter ./sdk build
+ node pipeline/bin/estella.mjs export examples/audio-demo --platform web --wasm build/wasm/web --out output/settings-web
+ - name: Verify settings across independent processes
+ run: |
+ node --input-type=module <<'JS'
+ import { spawnSync } from 'node:child_process';
+ import { GOLDEN } from './tools/goldenProjects.mjs';
+ 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),
+ '--log', 'output/settings-restart/process.log'], { stdio: 'inherit' });
+ if (run.error) throw run.error;
+ process.exit(run.status ?? 1);
+ JS
+ - name: Keep restart evidence
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: settings-restart-evidence
+ path: output/settings-restart
+ if-no-files-found: warn
+ retention-days: 7
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 5e76f7acf..0cec7bd18 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -30,6 +30,8 @@ export const NOTES_FLOOR = 'v0.65.0';
export const NOTED = {
'test(nav): yield fixed-step capture work to the compositor':
{ internal: 'Headless workshop acceptance yields between fixed simulation batches so software rendering can drain before screenshots, and persists sampled facts before capture failures.' },
+ 'test(settings): retain restart diagnostics and focused CI evidence':
+ { internal: 'Settings acceptance preserves every restart process result and screenshot in existing CI artifacts, reports explicit exit status and signal, and has a focused workflow that verifies matching runtime sources before reusing Web artifacts.' },
'fix(test): wait for package boot before settling input':
{ internal: 'Export acceptance counts settling frames only after the startup overlay releases input and uses a wall-clock watchdog independent of animation frames. Delayed real Web startup demonstrates that early clicks were previously lost.' },
'fix(nav): apply grid obstacle changes without bake throttling':
diff --git a/tools/tests/settings-verifier.test.ts b/tools/tests/settings-verifier.test.ts
new file mode 100644
index 000000000..1797be048
--- /dev/null
+++ b/tools/tests/settings-verifier.test.ts
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+import {expect, it} from 'vitest';
+import {build} from 'esbuild';
+import {mkdtempSync, readFileSync, rmSync} from 'node:fs';
+import {spawnSync} from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+
+it.each(['pass', 'killed', 'wrong-label'])('settings restart diagnostics preserve %s evidence', async mode => {
+ const temp=mkdtempSync(path.join(os.tmpdir(),'estella-settings-contract-'));
+ try {
+ const entry=path.join(temp,'settings.mjs'), log=path.join(temp,'logs','restarts.log');
+ const compiled=await build({entryPoints:['tools/verify-settings.mjs'],outfile:entry,
+ bundle:true,platform:'node',format:'esm',metafile:true,plugins:[{
+ name:'fixture-only-launcher',setup(builder){
+ builder.onResolve({filter:/electronRun\.mjs$/},()=>({path:'run',namespace:'fixture'}));
+ builder.onLoad({filter:/.*/,namespace:'fixture'},()=>({contents:`
+ let launch=0;
+ export function runElectron(args) {
+ const step=launch++, mode=${JSON.stringify(mode)};
+ if(mode==='killed')return {status:null,signal:'SIGKILL',stdout:'boot trace before termination',stderr:'renderer diagnostic'};
+ const labels=['Master 66%','Master 33%','Master 0%','Master 0%'];
+ const at={MasterLabel:{text:mode==='wrong-label'?'Master 100%':labels[step]},Bar0:{h:step<2?40:6}};
+ return {status:0,signal:null,stdout:'probe: '+JSON.stringify({at})+'\\n',stderr:'',args};
+ }
+ `,loader:'js'}));
+ },
+ }]});
+ expect(Object.keys(compiled.metafile!.inputs).some(file=>file.endsWith('/lib/electronRun.mjs'))).toBe(false);
+ const spec={control:{x:.2,y:.5},unlock:{x:.01,y:.01},label:'MasterLabel',
+ expected:['Master 66%','Master 33%','Master 0%'],bars:['Bar0'],floor:6,w:800,h:600};
+ const run=spawnSync(process.execPath,[entry,'--dir',temp,'--spec',JSON.stringify(spec),'--log',log],{encoding:'utf8'});
+ expect(run.status).toBe(mode==='pass'?0:1);
+ const records=readFileSync(log,'utf8').trim().split('\n').map(line=>JSON.parse(line));
+ const launches=records.filter(record=>record.kind==='launch');
+ expect(launches).toHaveLength(mode==='pass'?4:1);
+ expect(launches[0].step).toBe(0);
+ if(mode==='killed'){
+ expect(launches[0]).toMatchObject({status:null,signal:'SIGKILL',stdout:'boot trace before termination',stderr:'renderer diagnostic'});
+ expect(run.stderr).toContain('settings restart 0 failed: status=none signal=SIGKILL');
+ } else if(mode==='wrong-label'){
+ expect(run.stderr).toContain('settings label was Master 100%, expected Master 66%');
+ expect(launches[0].stdout).toContain('Master 100%');
+ } else {
+ expect(records.at(-1).kind).toBe('complete');
+ expect(launches.map(record=>record.restart)).toEqual([false,false,false,true]);
+ }
+ } finally {
+ if(path.dirname(temp)!==path.resolve(os.tmpdir())||!path.basename(temp).startsWith('estella-settings-contract-'))throw Error('Unexpected fixture path');
+ rmSync(temp,{recursive:true,force:true,maxRetries:10,retryDelay:50});
+ }
+});
diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjs
index 212a1c17c..f5c8574fb 100644
--- a/tools/verify-golden.mjs
+++ b/tools/verify-golden.mjs
@@ -424,10 +424,12 @@ for (const { id, target } of pairs) {
// the height the game wrote from an analyser bin — silence leaves it on its floor.
const audio = audioFor(golden);
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)], { cwd: ROOT, encoding: 'utf8' });
+ '--dir', out, '--spec', JSON.stringify(golden.settings), '--log', settingsLog], { 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') });
+ 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}` });
console.log(`${ok ? '✓' : '✗'} ${id} ${target} — settings process restart`);
for (const line of (run.stdout || '').trim().split('\n')) if (line) console.log(` ${line}`);
if (!ok) for (const line of (run.stderr || '').trim().split('\n').slice(-8)) if (line) console.log(` ${line}`);
diff --git a/tools/verify-settings.mjs b/tools/verify-settings.mjs
index 7a9697034..507a1d399 100644
--- a/tools/verify-settings.mjs
+++ b/tools/verify-settings.mjs
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import path from 'node:path';
import net from 'node:net';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { appendFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import os from 'node:os';
import { runElectron } from './lib/electronRun.mjs';
import { fileURLToPath } from 'node:url';
@@ -13,6 +13,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);
+const log = flag('log');
+const record = value => {
+ if (!log) return;
+ mkdirSync(path.dirname(path.resolve(log)), {recursive: true});
+ appendFileSync(log, JSON.stringify(value) + '\n');
+};
const server = net.createServer();
await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
const port = server.address().port;
@@ -21,13 +27,21 @@ await new Promise(resolve => server.close(resolve));
const profile = mkdtempSync(path.join(os.tmpdir(), 'estella-settings-'));
const names = [spec.label, ...spec.bars];
try {
+ record({kind: 'session', startedAt: new Date().toISOString(), dir: path.resolve(dir)});
for (let i = 0; i <= spec.expected.length; i++) {
const restart = i === spec.expected.length;
const pointer = restart ? spec.unlock : spec.control;
+ const screenshot = log ? path.resolve(`${log}.launch-${i}.png`) : null;
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(',')], { cwd: root, encoding: 'utf8' });
- if (run.status !== 0) throw new Error((run.stdout || '') + (run.stderr || ''));
+ '--input', JSON.stringify({ pointer, frames: spec.frames ?? 60 }), '--probe', names.join(','),
+ ...(screenshot ? ['--out', screenshot] : [])], { cwd: root, encoding: 'utf8' });
+ record({kind: 'launch', step: i, restart, screenshot, expected: spec.expected[restart ? i - 1 : i],
+ status: run.status, signal: run.signal ?? null, timedOut: !!run.timedOut,
+ error: run.error?.message, stdout: run.stdout ?? '', stderr: run.stderr ?? ''});
+ if (run.status !== 0) throw new Error('settings restart ' + i + ' failed: status='
+ + (run.status ?? 'none') + ' signal=' + (run.signal ?? 'none') + ' timedOut=' + !!run.timedOut
+ + '\n' + (run.stdout || '') + (run.stderr || ''));
const match = /probe: (\{.*\})/.exec(run.stdout || '');
if (!match) throw new Error('settings launch produced no probe');
const at = JSON.parse(match[1]).at;
@@ -40,6 +54,7 @@ try {
if (i === 0 && peak <= spec.floor) throw new Error('settings test began with no audible output');
console.log(`settings restart ${i}: ${expected}, spectrum peak ${peak}`);
}
+ record({kind: 'complete', launches: spec.expected.length + 1});
console.log('✓ settings survived process restart and restored mute affects output');
} finally {
const resolved = path.resolve(profile);